Repository navigation
fix(memory): make recall useful across agents — scopes, crawler noise, watcher storm, access bump - #9
Merged
Merged
Conversation
…, watcher storm, access bump
The store was 99.8% crawler noise (22k docs, 21.7k of them worktree copies
misfiled as `fact`), every project shared one scope so scoped recall returned
nothing, the watcher issued a delete task for every file removed under
~/Projects (181k/day), and the access bump replaced documents via POST.
Crawler
- Classify by agent-agnostic rules: instruction files for Claude Code, Codex,
Gemini CLI, Cursor, Windsurf, Cline, Zed, Copilot; memory files for Claude
Code (~/.claude/projects/*/memory), Codex, Windsurf, Cline. Drop the
`/.claude/` catch-all that indexed every doc inside a worktree.
- Skip linked git worktrees (`.git` is a file) and `.claude/worktrees`.
- Scope = nearest git repository; Claude memory dirs resolve their slug back
to the project path.
- Index each agent's knowledge roots (memories, global rules) so one agent's
memory is visible to all the others.
- Load crawler state in a few paged requests instead of one GET per file.
- Watcher ignores paths the classifier doesn't recognise; deletions no longer
hit the engine.
- `memd crawl run --reset` rebuilds from scratch.
Memory service
- Hierarchical scopes: a query scoped to /a/b/c matches /a/b/c, its ancestors,
`global`, and sub-paths (STARTS WITH, with a fallback for older engines).
Scopes are normalised (~ expanded, worktree segment stripped).
- `last_accessed_at` bumps use PUT (merge); POST would have replaced the
memory with `{id, last_accessed_at}`.
Agents
- Session-start and end-of-turn hooks for Claude Code, Codex (hooks.json) and
Gemini CLI (JSON hook output); directives for Windsurf and Cline.
- `memd context` reads the hook payload's cwd, injects only agent/user
memories plus other agents' memory files, never crawled project files.
- `memd capture` handles Claude, Codex and Gemini payloads and rejects
injected context (skill loads, subagent hand-backs, system reminders).
- `memd setup --agents a,b` for scripted, explicit selection.
- `memd doctor --fix` prunes finished engine tasks older than a week.
- Claude Code memory slugs never resolve to `global`: worktree and sub-directory sessions map to their repository, unknown slugs to a reconstructed path. A `global` fallback injected one project's notes into every other session. - `MEMORY.md` index files are classified `reference`, so they are searchable but not injected. - Crawled memory files take their title from front matter (`description`, then `name`), not the file name. - `memd context` lists real memories first, then other agents' memory files about the project, and never shows an agent its own memory directory.
qdequele
force-pushed
the
qdequele/memory-quality
branch
from
October 9, 2026 07:15
8cd3712 to
93cd75b
Compare
qdequele
added this pull request to stack #11
October 9, 2026 08:08
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Why
A review of the installed daemon (2026-10-08) found the memory store was 99.8% crawler noise: 22,385 docs, 21,708 of them copies under
.claude/worktrees/misfiled asfact. Only 15 agent-written memories existed and they were unreachable by scoped recall. Four code-level causes:classify_pathtreated any Markdown under a/.claude/path as a memory.root + first component, so every project under~/Projects/Meilisearchshared one scope and exact-match filters returned nothing.forget()for every file deleted under~/Projects(181k deletion tasks in one day, 86k 404 log lines).last_accessed_atbump used POST (replace); it only failed to wipe memories because the embedder template rejected the partial doc.What changed
Crawler — agent-agnostic classification (Claude Code, Codex, Gemini CLI, Cursor, Windsurf, Cline, Zed, Copilot instruction files; Claude/Codex/Windsurf/Cline memory files), linked git worktrees skipped, scope = nearest git repo, each agent's knowledge roots indexed, bulk state load, watcher pre-filter,
memd crawl run --reset.Memory service — hierarchical scopes (self + ancestors +
global+ sub-paths), scope normalisation, PUT-based access bump.Agents — hooks for Claude Code, Codex and Gemini CLI; directives for Windsurf and Cline;
memd contextinjects only memories (never crawled project files) and reads the hook payload'scwd;memd capturehandles all three payload shapes and rejects injected context;memd setup --agents a,b;memd doctor --fixprunes task history.Verification
cargo fmt --check,cargo clippy --all-targets -D warnings,cargo test(86 tests) green.After upgrading, run
memd crawl run --resetonce so existing crawled docs pick up the new scopes.🤖 Generated with Claude Code