docs

Install qfile, choose what it can search, and use its local search, memory, conversation summarization, and TUI knowledge browser. Raw transcripts remain local; Codex is used only when you ask it to think or summarize.

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",
  "~/.qfile/knowledge",
]

qfile 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.

qfile summarize

Generate searchable Markdown knowledge from changed conversations.

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."
qfile summarize --limit 10

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 four tabs: Metrics, Search, Think, and Knowledge. Knowledge browses the Markdown summaries generated from conversations and refreshes stale summaries in the background while the interface remains usable.

Tabs: Metrics | Search | Think | Knowledge
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