docs

Install qfile, choose what it can search, and use five simple commands: think, search, metrics, source, and remember. qfile is local by default. Only Think calls Codex; the TUI Think tab can use compact session evidence for recent-history questions.

install latest build

These downloads are published on every main branch deploy.

# 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

verify

qfile --help
qfile metrics

choose what qfile can search

Put `.qfile` in the repository where your agent is working. Add project folders, notes, vaults, and optional transcript folders. Paths can be relative to the repo or absolute home paths.

[search]
targets = [
  ".",
  "~/Develop/vault",
  "~/.codex/sessions",
  "~/.claude/projects",
]

the five commands

qfile search

Search local files, memory, and conversations. Results are grouped by type; conversations use Metrics-style session rows.

qfile think

Search first, then send the best local context or compact session evidence to Codex.

qfile metrics

Open the terminal UI with Metrics, Search, and Think tabs.

qfile source

Add a folder to the `.qfile` manifest.

qfile remember

Save a durable lesson as searchable memory.

common examples

qfile search "bounded context"
qfile search --source files "manifest loader"
qfile search --source history "what did we decide about metrics?"
qfile search --source memory --format agent "simplify memory commands"
qfile think "explain qfile architecture"
qfile source add ~/Develop/vault
qfile remember "Search behavior belongs in the search domain."

sources

qfile keeps sources separate so results are easier to trust.

files
Project code, docs, notes, and vault folders from `.qfile`.

memory
Small durable lessons stored under `.qfile_memory`.

history
Raw Codex and Claude transcripts shown as newest-first session audits in TUI search.

terminal ui

Run `qfile metrics` to open the terminal UI. It has three tabs: Metrics, Search, and Think. Metrics shows session audit rows, recent questions, qfile activity, memory activity, captured qfile results, and source coverage. Search is local only, groups results by type, and orders conversations by newest session using the same session rows as Metrics. Think uses Codex; recent-history prompts are reduced to matching user questions from local sessions before Codex synthesizes an answer.

Tabs: Metrics | Search | Think
Filters: 1 All | 2 Files | 3 Conversations | 4 Memory
Memory (3) | Conversations (8) | Files (9)
claude:17b868 today 16:09  qfile 12 memory 0 questions 140
/ edit | Enter view | Up/Down select | q quit

agent memory

Agents should search memory before work and remember only durable lessons after work. Memory is for reusable project knowledge, not status updates or file change summaries.

# manual agent flow
qfile search --source memory --format agent "the user prompt"
qfile remember "durable lesson for future agents"

# integration docs
integrations/README.md

integrations

Codex and Claude Code can use the same instruction snippet. opencode can use the TypeScript plugin included in the repo. The integrations folder also includes agent-stop notification examples for Claude, Codex, and opencode, backed by a shared shell hook that can send macOS notifications and optional ntfy pushes.

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

checksums

https://qfile.dev/downloads/qfile-macos-arm64.tar.gz.sha256
https://qfile.dev/downloads/qfile-linux-x86_64.tar.gz.sha256