agentmemory

The Problem

AI‑coding agents lose all context when a session ends. Developers must repeatedly re‑explain architecture, re‑discover conventions, and re‑enter secrets. The result is wasted tokens, fragile prompts, and duplicated effort across agents.

What This Does

agentmemory captures every tool use, file edit, test run and error through the hook scripts in plugin/scripts/. Raw observations are compressed (see src/functions/compress.ts) into structured facts defined in src/types.ts. The facts are stored in an in‑process key‑value store (src/state/kv.ts) and indexed by a hybrid BM25 + vector search (src/state/hybrid-search.ts). A dedicated MCP server (src/mcp/server.ts) exposes a JSON‑RPC API so any MCP‑compatible agent can query, add, or forget memories. The viewer (src/viewer/server.ts) provides a simple UI for inspection.

Key responsibilities are isolated in a few hub modules:

• src/types.ts – 70 exported types (Session, Observation, Memory, etc.) and is imported by 116 other modules.
• src/state/schema.ts – defines the on‑disk schema; imported by 57 modules.
• src/state/kv.ts – the low‑level KV implementation; imported by 55 modules.

These files dominate the import graph and therefore have the highest blast radius for change.

How It Is Wired

Execution starts at src/cli.ts (function main at line 197). main parses CLI flags, loads environment variables via src/config.ts (loadConfig, getMergedEnv), and then:

1. Initialises providers – createEmbeddingProvider (src/providers/embedding/index.ts) builds a concrete embedding client (e.g. OpenAI, Cohere). The provider chain is wrapped by a circuit‑breaker (src/providers/circuit-breaker.ts).
2. Starts the MCP server – src/mcp/server.ts creates an HTTP listener, registers tool handlers from src/mcp/tools-registry.ts, and wires them to the core functions (search, recall, compress, auto‑forget). The server is the only component that reaches outside the process: it writes observations to the KV store and, via src/providers/embedding/*, calls external LLM APIs.
3. Handles a request – a typical flow is search → src/state/hybrid-search.ts.search (called from 8 places) → src/state/vector-index.ts.cosineSimilarity and src/state/search-index.ts.search. The search result is then passed to src/functions/compress.ts or src/functions/recall.ts before being returned to the agent.

The most widely used internal functions are:

Because src/types.ts is imported by 116 modules, any change to a type definition ripples through the entire codebase. Likewise, the KV and schema modules are pure data layers; keeping them stable is essential for downstream consumer safety.

How To Use It

# Clone the repo
git clone https://github.com/moses-y/agentmemory
cd agentmemory

# Install dependencies
npm ci

# Build TypeScript
npm run build   # defined in package.json

# Start the MCP server (default port 8000)
node dist/src/mcp/server.js   # entry compiled from src/mcp/server.ts

Configuration is read from environment variables and optional .env files via src/config.ts. The README recommends setting provider API keys (e.g. OPENAI_API_KEY) before launch. The CLI also supports a one‑shot start that spins up the viewer and the server together (npx @agentmemory/agentmemory as shown in the README).

Real‑World Use

A team integrating Claude Code can add the agentmemory plugin to their .claude-plugin directory. When Claude runs a tool (e.g. file_edit), the corresponding hook (plugin/scripts/post-tool-use.mjs) posts the observation to the MCP server. On the next session, Claude calls search via the MCP API; the returned memories include prior design decisions, allowing Claude to continue the same project without re‑explaining the authentication middleware.

// Example POST from a hook
{
  "type": "observation",
  "session": "abc123",
  "payload": { "file": "src/auth.ts", "action": "added JWT middleware" }
}

Code Health & Issues

• MEDIUM – GITHUB_TOKEN permissions – .github/workflows/ci.yml lacks explicit permissions.
• MEDIUM – Dependabot missing – no automated dependency updates.
• MEDIUM – No dependency‑vulnerability scan – CI does not run a review action.
• MEDIUM – Large binaries – assets/demo.mp4 (11 MB) and demo.gif (7.8 MB) should be moved to Git LFS or external storage.
• MEDIUM – Checkout persists token – .github/workflows/ci.yml should set persist-credentials: false.
• LOW – No job timeout – add timeout-minutes to CI jobs.

Static analysis also flagged high cognitive‑load files (src/types.ts, src/mcp/server.ts, src/mcp/tools-registry.ts) and hub modules (src/types.ts, src/state/schema.ts, src/state/kv.ts). Consider refactoring these into smaller, responsibility‑focused units to reduce change impact.

The Bottom Line

agentmemory delivers a fully self‑contained, versioned memory layer for AI coding agents, with a clear API surface and extensive test coverage (581 tests). The codebase is functional but concentrates a lot of logic in a few large modules, which raises maintenance risk. Teams that need cross‑agent context and are comfortable managing the modest CI hygiene gaps will find the project immediately useful.