The Problem
AI coding agents suffer from total memory loss between sessions. Each new session requires re-explaining architecture, re-discovering patterns, and re-teaching preferences. Built-in memory files like CLAUDE.md and .cursorrules act as 200-line sticky notes that overflow, go stale, and provide no semantic search capability. There is no persistent, cross-agent memory layer that survives session boundaries.
What This Does
agentmemory replaces per-session amnesia with a searchable, versioned memory database. The codebase (114 files in src/) implements triple-stream retrieval combining BM25, vector, and knowledge graph search (src/functions/graph-retrieval.ts, src/functions/search.ts, src/state/vector-index.ts). Memory consolidation operates across 4 tiers through the pipeline in src/functions/consolidation-pipeline.ts, with cascading staleness propagation via the graph functions (src/functions/temporal-graph.ts, src/functions/crystallize.ts). Privacy stripping occurs before storage via src/functions/privacy.ts. The system runs as a single instance serving Claude Code, Cursor, Codex, Windsurf, and any MCP client simultaneously — 41 MCP tools are exposed through src/mcp/server.ts and src/mcp/tools-registry.ts. Measured across 240 real observations across 30 sessions: 64% Recall@10, perfect MRR, and 92% token reduction versus context dumping.
How To Use It
Setup: The project uses npm as package manager (package.json, package-lock.json). Install with:
npx @agentmemory/agentmemory # installs iii-engine if missing, starts everything
The docker-compose.yml at root enables containerized deployment. The iii-config.yaml at root likely contains configuration defaults.
Configuration: Environment variables and API keys belong in a .env file or the iii-config.yaml root file. The src/config.ts handles configuration loading. No external database dependencies — all state persists through the custom KV and vector store implementations in src/state/.
Running it: Start the MCP server with src/mcp/server.ts or invoke the CLI entry point at src/cli.ts. The system begins recording observations via hooks automatically — src/hooks/session-start.ts and src/hooks/session-end.ts orchestrate capture.
Real-World Use
When an agent searches "database performance optimization" across sessions, hybrid retrieval (src/functions/smart-search.ts combining BM25 + vector) surfaces the N+1 fix from three weeks prior — a result keyword grep cannot achieve. The graph retention layer (src/functions/retention.ts) propagates staleness to related nodes, ensuring retired facts never pollute current context. Project profiles aggregated in src/functions/profile.ts surface top concepts, files, and conventions for the new session's context injection.
Code Health & Issues
Tests & CI: 46 test files present with GitHub Actions workflows (.github/workflows/ci.yml, .github/workflows/publish.yml) configured. License: LICENSE file present at root. Secrets handling: src/functions/privacy.ts strips API keys, secrets, and <private> tags before storage — evidence of deliberate privacy design. No structural red flags: Tests, CI, license, and lockfile all present where expected. Observed concern: The 200-file scope is heavily function-oriented (src/functions/ has ~70 files); heavy reliance on functional composition may increase cognitive load for new contributors versus a more modular architecture.
The Bottom Line
agentmemory delivers a functional persistent-memory layer for AI coding agents with measurable context-reduction benefits and zero external DB dependencies. The implementation is credible and well-tested, though the function-dense structure may pose onboarding friction. Best suited for teams running multiple agent instances across extended sessions where cross-session context retention provides immediate productivity gains. Solo developers with short-lived projects may derive less value relative to the setup overhead.