pretool-memory retrieves local search results before selected Claude Code tool calls for operators using hosted Claude models. It supplies candidate context from owned records when the current session needs earlier decisions.
Requirements: Bash, jq, shasum, and a configured QMD Markdown collection.
Optional SQLite FTS5 session recall requires sqlite3 and a compatible fts_unified table.
git clone https://github.com/b2bvic/owned-record.git
cd owned-record/components/pretool-memoryThe quick start also requires Python 3. It uses synthetic search output and needs no QMD installation or model credentials.
bash examples/demo.shThe demo builds a synthetic transcript and supplies a mock QMD executable.
It prints PreToolUse JSON with a sample additionalContext value.
Its temporary files are removed when the demo exits.
For real use in this checkout, review components/pretool-memory/pretool-memory.sh.
After reviewing the corpus, merge this opt-in entry into the root .claude/settings.json:
{
"hooks": {
"PreToolUse": [
{
"matcher": "Read|Glob|Grep|WebFetch|WebSearch|Task",
"hooks": [
{
"type": "command",
"command": "bash \"$CLAUDE_PROJECT_DIR/components/pretool-memory/pretool-memory.sh\""
}
]
}
]
}
}For a separate project, copy the script into its .claude/hooks/ folder and adjust the hook command to that path.
Use the Claude Code hook reference when merging existing settings.
AI agent memory retrieval follows a bounded transcript tail:
- Filter calls to
Read,Glob,Grep,WebFetch,WebSearch, orTask. - Read the last 200 transcript lines and retain up to 1,500 bytes of thinking text.
- Skip short thinking, recent queries, and repeated thinking hashes.
- Use QMD
searchfor BM25 context retrieval with at most three results. - Query an optional SQLite ledger for at most two history snippets.
- Emit the matches as
additionalContext.
The hook uses a 30-second per-session throttle after a successful recall. Session IDs become SHA-256 cache keys. Search failures yield no result from that source; the other source can still supply context.
| Variable | Default | Purpose |
|---|---|---|
QMD_BIN |
~/.bun/bin/qmd |
QMD executable or scoped search wrapper |
LEDGER_DB |
~/.claude/session-ledger.db |
Optional SQLite ledger |
MEMORY_STATE_DIR |
${XDG_CACHE_HOME:-$HOME/.cache}/pretool-memory |
Hash and throttle files |
Memory resides in the source Markdown collection and optional SQLite ledger.
The export path is your collection directory and the database selected by LEDGER_DB.
The hook supplies no export command and does not create a ledger.
When changing model vendors, carry the original Markdown files and a consistent SQLite backup.
Rebuild the search index from those records and configure the next client's retrieval adapter.
The supplied PreToolUse adapter and thinking extraction target Claude Code.
Moving records does not make this hook compatible with another client.
- Recall needs a readable transcript with an assistant thinking block of at least 100 characters.
- Hidden or absent thinking produces no recall.
- Retrieval can miss records or return unsuitable context.
- Write, Edit, and Bash calls do not trigger recall.
- Search has no internal wall-clock timeout or measured latency guarantee.
- The ledger schema must contain
domain,timestamp, andcontent_textinfts_unified. - Retrieved text remains untrusted evidence and can enter a hosted-model session.
- The hook returns success without acting as an approval gate.
python3 -m unittest discover -s tests -v
bash -n pretool-memory.sh examples/demo.sh
shellcheck pretool-memory.sh examples/demo.sh
ruff check --select F,E9 testsTests use synthetic transcripts, a mock QMD command, and a temporary SQLite database. Install ShellCheck and Ruff 0.16.10 for lint.
- owned-record: Markdown context folders and routing configuration.
- vault-crawl: Retrieve source material and preserve provenance.
- cc-bridge: Convert transcript exchanges to Markdown logs.
- voice-calibration: Recall writing samples for a target file genre.
MIT. See LICENSE.