Agent Memory Kit

Execution memory for coding agents — structured context that survives between sessions.

No database. No embeddings. No cloud services. Just flat files, deterministic retrieval, and a session lifecycle that makes agents smarter over time.

The 3-call session lifecycle

Every agent session is boot, work, finalize. Two memory calls total:

boot_context()                                         # auto-detect branch, recover everything
  ... meaningful work ...
  record_event(kind="decision", message="Use RS256")   # auto-resolve node from branch
finalize_node(summary="Auth done. Next: rate limiting.")  # quality-checked, handoff generated

The next session calls boot_context() and immediately knows what was done, decided, failed, and what should happen next. Memory compounds — each session makes the next one better.

What it gives you

| For agents | For developers | For teams | |---|---|---| | Instant context recovery on boot | See what agents did and decided | Quality scores on every close | | Zero-ID workflow via branch auto-detection | Handoff packs for seamless resumption | Stale/blocked item tracking | | Quality gates catch low-effort memory | TypeScript + Python SDKs | Multi-workspace isolation | | Continuity snapshots verify memory state | Visual workbench UI | Actor/audit trail |

Quick start

From source

git clone https://github.com/jsalvadorlpz/agent-memory-kit.git
cd agent-memory-kit
pnpm install && pnpm build
pnpm eval
# http://localhost:3457  (workbench + API)

npm

npm install -g @agent-memory/cli
agent-memory serve

Docker

docker compose up -d

Verify

curl http://localhost:3457/health
# {"ok":true,"service":"agent-memory-api","version":"0.5.0"}

Claude Code / MCP setup

Add to .claude/settings.json:

{
  "mcpServers": {
    "agent-memory": {
      "command": "npx",
      "args": ["-y", "@agent-memory/mcp"],
      "env": { "MEMORY_DIR": "/path/to/project/.agent-memory" }
    }
  }
}

For shared backends, set AGENT_MEMORY_URL, AGENT_MEMORY_TOKEN, and AGENT_MEMORY_WORKSPACE instead. See Claude Code Integration Guide.

MCP tools

Session lifecycle (primary workflow)

| Tool | Description | |------|-------------| | boot_context | Session start. Auto-detects git branch, resolves context, includes handoff. Returns activeNodeId, memoryQuality, confidence, suggestedTask, validation. | | finalize_node | Session end. Records summary, sets status, returns handoff + continuity + qualityScore + optional validation state. Validation persists across calls: omitting it preserves prior state; passing validationStatus: 'unknown' clears it. ID optional — auto-resolves from branch. | | record_event | Record a decision, test, failure. ID optional — auto-resolves from branch. Returns _feedback with event counts. | | check_quality | Memory quality check: score (0-100), level, actionable warnings. |

Node management: create_node, close_node, get_node, get_children, get_hierarchy, get_dashboard, search_related, resolve_context, get_handoff

Aliases: create_feature, create_story, create_task, close_task, close_story

Example: 3-session lifecycle

Session 1: Fresh start
  boot_context() -> no match -> suggestedTask with title/sourceRefs from branch
  create_task(from suggestion)
  record_event(kind="decision", message="Use RS256 JWT")
  finalize_node(summary="JWT auth implemented. Next: rate limiting.")
  -> qualityScore: 85

Session 2: Resume
  boot_context() -> recovers task + handoff, memoryQuality: good
  record_event(kind="failure", message="Redis connection issue")
  finalize_node(summary="Rate limiting blocked by Redis.", status="interrupted")
  -> continuity.blockerCount: 1

Session 3: Finish
  boot_context() -> recovers interrupted state + blockers
  record_event(kind="test", message="All 15 tests pass")
  finalize_node(summary="Auth complete. Ready for review.")
  -> qualityScore: 90

Quality gates

Every finalize_node and close_node returns a quality assessment:

| Score | Level | What it means | |-------|-------|---------------| | 75-100 | good | Summary + decisions + events + sourceRefs | | 45-74 | acceptable | Some context but gaps | | 1-44 | poor | Very little for the next session | | 0 | empty | Nothing recorded |

Scoring factors: summary (25), summary depth (10), events (15), event depth (10), decisions (20), source refs (10), tags (5), parent link (5).

Summary validation catches low-effort patterns ("done", "fixed") with actionable warnings. Never blocks, always warns.

HTTP API

Base URL: http://localhost:3457

| Method | Path | Description | |--------|------|-------------| | GET | /boot | Boot context (?branch=, ?nodeId=, ?format=markdown) | | POST | /nodes/:id/finalize | Finalize with summary | | POST | /finalize | Finalize by branch (branchName in body) | | GET | /nodes/:id/quality | Quality check | | POST | /events | Record event (returns _feedback) | | GET/POST | /nodes | List/create nodes | | POST | /nodes/:id/close | Close (returns _quality) | | GET | /handoff/:id | Handoff pack | | GET | /dashboard | Dashboard overview | | GET | /context/resolve | Context resolution | | GET | /search?q= | Search |

# Boot
curl "http://localhost:3457/boot?branch=feature/AUTH-42"

# Record event
curl -X POST http://localhost:3457/events \
  -H "Content-Type: application/json" \
  -d '{"nodeId":"TASK-xxx","kind":"decision","message":"Use RS256"}'

# Finalize
curl -X POST http://localhost:3457/nodes/TASK-xxx/finalize \
  -H "Content-Type: application/json" \
  -d '{"summary":"JWT auth done. Tests pass. Next: refresh tokens."}'

# Quality check
curl http://localhost:3457/nodes/TASK-xxx/quality

Auth: set API_TOKEN env var. Add API_AUTH_ALL=true for read auth too.

SDKs

TypeScript

npm install @agent-memory/sdk

import { AgentMemoryClient } from '@agent-memory/sdk';
const client = new AgentMemoryClient();

const boot = await client.bootContext({ branchName: 'feature/AUTH-42' });
await client.recordEvent({ nodeId: boot.activeNodeId!, kind: 'decision', message: 'Use RS256' });
const result = await client.finalizeNode(boot.activeNodeId, {
  summary: 'JWT auth done. Tests pass.',
});
console.log(result.continuity.nextSessionCanRecover);

Python

pip install agent-memory-sdk

from agent_memory import AgentMemoryClient

client = AgentMemoryClient.from_env()
boot = client.boot_context(branch_name="feature/AUTH-42")
client.record_event(node_id=boot["activeNodeId"], message="Use RS256", kind="decision")
result = client.finalize_node("JWT auth done.", node_id=boot["activeNodeId"])

Architecture

packages/
  core/       Domain: schemas, storage, hierarchy, boot, finalize, quality
  api/        HTTP API (Hono, port 3457)
  mcp/        MCP server (stdio, local + HTTP proxy)
  cli/        agent-memory CLI
  sdk/        TypeScript SDK (zero deps)
  adapters/   GitAdapter
  workbench/  React workbench
python/       Python SDK (zero deps)

Storage: flat files in .agent-memory/ — JSON nodes, JSONL events, Markdown summaries.

Tests

pnpm test   # 511 tests, 27 suites

Evaluating for your team?

• Overview — what's real today
• Pilot guide — setup and trial scenarios
• Demo script — 5-10 minute walkthrough
• FAQ — honest answers

Safety

Stores structured execution metadata only. Do not store credentials, PII, or secrets. All data is local. See SECURITY.md.

License

MIT