QFILE

local context for agents

search what your agents know.

qfile searches project files, saved memories, and Codex or Claude history on your machine. It groups conversation search results by dated session and audits whether agents searched or stored memory. Think can use those sessions as compact evidence, then ask Codex to synthesize instead of just showing matches. Everything stays local except the Codex call you choose to run with `qfile think`.

sources
files / memory / history
commands
think / search / metrics
runtime
Rust + SQLite FTS
open docs install latest build
qfile metrics live local context
Usage | 77 qfile mentions
memory ██████████ 60 history ████████████████████████ 1604 files ██████ 166
Tabs: Metrics | Search | Think
> claude:11604a today qfile 1 memory 1 questions 3
got: Relevant qfile memories: metrics lesson
codex:3cfc6c yesterday qfile 2 memory 0 questions 1
$ qfile think "metabase lately"
/ local questions -> Codex
synthesized answer from compact session evidence
Search results
Conversations (2)
same session rows as Metrics, newest first

search

Find files, memories, and transcripts grouped by type. Conversation hits are newest first.

think

Ask Codex with local context or compact evidence from recent agent sessions.

remember

Save durable lessons so future agents can find them.

metrics

Audit sessions, qfile searches, qfile results, memory usage, and source coverage.

why it exists

Agents forget useful project context. Search tools find files, but they do not separate durable lessons from noisy chat history.

qfile gives agents one local place to search files, saved memory, and raw transcripts. It keeps those sources labeled so you can see what came from code, what came from memory, and what came from history.

how qfile thinks

  1. Read the folders listed in `.qfile`.
  2. Label each result as file, memory, or history.
  3. Rank matches with local search.
  4. Group Search results by type and put newest conversations first.
  5. For `think`, send the best context to Codex; recent-history prompts use compact question evidence.
  6. For `metrics`, show session audit, qfile actions, and captured qfile results.

the five commands

qfile has a small product API. Use `search` when you only want local retrieval. Use `think` when you want Codex to answer with local context. Use `remember` only for reusable lessons.

qfile search
Search files, memories, and conversations without calling an LLM.
qfile think
Find relevant context or recent session evidence and ask Codex to answer with it.
qfile metrics
Open the TUI for Metrics, Search, and Think.
qfile source
Add another folder to the `.qfile` search manifest.
qfile remember
Save a durable lesson as searchable memory.

files

Project code, docs, notes, and vault folders listed in `.qfile`. qfile skips generated folders like `target`, `node_modules`, and `dist`.

memory

Small Markdown notes under `.qfile_memory`. These are durable lessons that should help future agents, not task logs.

history

Raw Codex and Claude transcript folders. Search groups conversation hits by type and orders sessions newest first using the same session audit rows as Metrics; open a row to inspect questions, qfile searches, and captured results.

agent memory loop

Before work, agents search memory with the user's prompt. After work, they remember only lessons that should matter later.

This keeps memory small. The next agent gets a few relevant lessons instead of a whole transcript dump. 

qfile search --source memory --format agent "$PROMPT"

qfile remember "Search behavior belongs in the search domain."

install latest public build

# Apple Silicon Mac
curl -L https://qfile.dev/downloads/qfile-macos-arm64.tar.gz | tar -xz
sudo install qfile /usr/local/bin/qfile

# Linux x86_64
curl -L https://qfile.dev/downloads/qfile-linux-x86_64.tar.gz | tar -xz
sudo install qfile /usr/local/bin/qfile

agent loop

qfile search --source memory --format agent "$PROMPT"
qfile search "thing I forgot"
qfile think "summarize relevant files"
qfile remember "durable lesson"

integrations

Codex and Claude Code can use the same instruction snippet: search memory before work, remember durable lessons after work.

opencode can also load memory automatically with the TypeScript plugin in the repo. Stop notification examples cover Claude, Codex, and opencode, with optional ntfy delivery. 

integrations/AGENTS.memory.md
integrations/README.md
integrations/hooks/agent_stop_notify.sh
integrations/opencode/qfile_memory.ts