agmem

Purpose

agmem provides coding agents with persistent, source-linked project memory. The core problem it solves is: agents have to re-grep the same repository on every session, while static rule files such as CLAUDE.md, AGENTS.md, .cursor/rules/ cannot reflect a constantly changing codebase. agmem indexes the repository into queryable local storage, letting agents quickly retrieve relevant context on every task.

Main Capabilities

• Indexing:agmem index Traverses the repository (respecting .gitignore), extracting Terraform resources, modules, variables, outputs; Python classes, top-level functions, FastAPI-style routes; Go types, functions, methods, chi/gin/echo HTTP routes; YAML/Helm values (flattened into searchable dot-separated key paths); Markdown sections (long documents split by H2) and PRD status.
• Retrieval:agmem context "<task>" Returns task-relevant snippets ranked by BM25 + lexical aliases, grouped as Constraints / Facts / Patterns, each with a source_ref and commit. Queries are best made with identifier-dense noun phrases (such as waf-alb-public storefront ingress-gateway-external count), rather than full sentences.
• Rule memory: For content the indexer cannot infer (team conventions, "don't do X again"), you can use agmem remember "..." --kind rule to write them, and rules get a 4x score boost in retrieval.
• Session mode: Multi-query workflows can add --session, and subsequent calls downweight already-seen results, boost sibling sections of already-read files, and give "not yet seen" hints.
• Git awareness: post-merge hooks keep memory in sync after teammates push; post-commit and post-rewrite hooks follow local commits.
• Drift tracking: Every record carries a source_hash + source_commit, making provenance verifiable.
• Performance: Search takes under 100ms on stores with thousands of records.

How to Use

Supports any agent that can execute shell commands (Claude Code, Codex, opencode, Cursor, Aider). Installation takes about 60 seconds. Claude Code has the deepest integration, and can automatically inject task-relevant context on every prompt via a plugin, along with the agmem skill and the /agmem:setup command; it can also be integrated manually by adding an idempotent block to CLAUDE.md, a UserPromptSubmit hook, and three git hooks. For Codex/opencode (AGENTS.md), Cursor (.cursor/rules/), Aider, or custom CI scripts, see the agent integration guide.

Suitable Scenarios

• Coding agent workflows that need to remember codebase structure across sessions.
• Teams that want context retrieval to be fully local, with no API calls and no SaaS dependency.
• Scenarios that need to track memory-source drift and verify provenance.

Limitations

• In Alpha, used daily in real repositories since April 2026; the API may change between minor versions before 1.0.
• Tested on macOS and Linux; Windows is best-effort: the package can be imported and core commands can run, but file locking degrades to a no-op (assuming a single writer), and it is not yet included in CI.
• The default installation has no heavy dependencies; the optional [hybrid] extension pulls in sentence-transformers, installing PyTorch (about 2 GB) and downloading a 90 MB embedding model on first use.
• No fine-tuning, no daemon or server required, no MCP dependency, and nothing stored in the cloud.
• The LongMemEval benchmark measures conversational history retrieval rather than code retrieval; agmem's primary usecase is code memory.