Agent Memory Engine

Local-first persistent memory and project knowledge runtime for coding agents.

English | 中文

---

Agent Memory Engine

A local-first MCP runtime that gives coding agents persistent, evidence-backed project memory and grounded project knowledge across sessions.

---

Why it exists

Coding agents face a fundamental problem: every session starts cold.

• They forget project context between sessions.
• They repeatedly scan repositories to re-learn what modules do.
• They lose debugging lessons and historical decisions.
• Flat RAG cannot distinguish stable constraints, past incidents, architecture decisions, and raw code evidence.
• Even large context windows still require intelligent prioritization and token budgeting.

Memory Engine solves this by maintaining a structured, evidence-backed memory tree alongside an indexed project knowledge base — both local, both automatic, no infrastructure required.

---

Core capabilities

| Capability | Details | |---|---| | Persistent memory tree | MemoryNode hierarchy: constraints, architecture, modules, decisions, incidents, procedures | | Evidence-backed memory | Each node links to source Evidence entries (test output, code references, review notes) | | Candidate staging | Reflection generates MemoryCandidates before promoting to the live tree | | Confidence-aware promotion | create / update / merge / supersede / discard / needs_review | | Conflict detection | High-risk areas (auth, schema, state-machine, retry) flagged for review | | Ancestor consolidation | Parent node summaries auto-updated after each promotion | | Agent-native recall | Intent-aware retrieval before coding tasks — no manual queries | | Progressive inspection | Drill down into any memory node, its children, and linked evidence | | Automatic post-task reflection | Agent reports outcome → system decides whether and how to retain knowledge | | Knowledge ingestion | Markdown, code, ADR, test reports, runtime logs, git diffs | | Local FTS5 search | SQLite FTS5 with porter tokenizer; no external search engine | | Optional semantic retrieval | Persistent local sqlite-vec backend with sentence-transformers / Ollama embeddings (Phase 13); default OFF, no required deps | | Lexical structured fallback | Full retrieval without vector backend or Docker | | Unified ContextPack | Memory + knowledge merged, deduplicated, token-budgeted | | Retrieval traceability | Per-signal score breakdown in every response | | Local-first privacy | All data stays inside .memory-engine/; no telemetry, no cloud calls | | Python MCP server | stdio transport; no TypeScript, no Docker, no external daemon | | Zero-touch bootstrap | Auto-initializes on first MCP connection | | Incremental indexing | JSON manifest; only changed files re-indexed on subsequent runs | | Git-aware synchronization | Detects branch, HEAD commit, staged/modified files via safe read-only Git commands | | Branch-aware retrieval | Prefers memory from the current branch; falls back to mainline then global | | Branch-scoped memory writes | New memories stamped with branch name and scope; mainline promotion is explicit | | Multi-granularity memory | Four retrieval layers (proposition → paragraph → chunk → module summary) created at write-time; selected at query-time by intent | | Deterministic proposition extraction | Atomic facts extracted from docstrings, security comments, raise statements, markdown bullets — no LLM required | | Intent-aware granularity routing | bug_fix retrieves constraint/risk propositions; architecture_review retrieves module summaries | | Query-time context assembly | Proposition hits optionally expand to parent paragraphs; architecture queries attach module summaries | | Memory retention & compaction | Candidate expiry, stale/superseded archival, multi-source compaction with full lineage — no physical deletion | | Protected memory types | constraint, security_rule, architecture, decision excluded from all auto-archive and auto-compaction | | Agent memory policy | Canonical AGENT_MEMORY_POLICY.md auto-installed to CLAUDE.md / .cursor/rules/ on first bootstrap; CLI available for manual control | | Project context seeding | seed_project_context MCP tool + memory seed CLI wizard — write initial constraints, decisions, and project overview on day 1, eliminating the cold-start problem | | Windows installer | PowerShell installer (scripts/install.ps1) for Windows-native setup without Docker, WSL, or cloud services |

---

Quick Start

macOS / Linux:

git clone https://github.com/uudam42/agent-memory-engine.git
cd agent-memory-engine
bash scripts/install.sh

Windows (PowerShell):

git clone https://github.com/uudam42/agent-memory-engine.git
cd agent-memory-engine
.\scripts\install.ps1

The installer checks Git and Python 3.11+, installs uv when needed, resolves dependencies, runs a health check, and prints a ready-to-copy MCP configuration for Cursor or Claude Code. No Docker, WSL, or cloud services required.

Default Deployment Model

Agent Memory Engine runs locally as a stdio MCP server. The default setup uses Python, uv, and local SQLite/FTS5 storage. Docker, cloud databases, and external embedding services are not required for the standard local workflow.

MCP Stdio Mode (recommended)

Runs locally through the MCP client using uv run. Supported by Cursor, Claude Code, and any client that implements the MCP stdio transport.

Option A — explicit project root (Cursor, most clients):

{
  "mcpServers": {
    "memory-engine": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "/absolute/path/to/agent-memory-engine",
        "memory-engine-mcp",
        "--project-root",
        "/absolute/path/to/your-project"
      ]
    }
  }
}

Option B — project root via environment variable (Claude Code):

{
  "mcpServers": {
    "memory-engine": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "/absolute/path/to/agent-memory-engine",
        "memory-engine-mcp"
      ],
      "env": {
        "MEMORY_ENGINE_PROJECT_ROOT": "/absolute/path/to/your-project"
      }
    }
  }
}

> Note: Replace all /absolute/path/to/... with real paths on your machine. > Config file location and workspace-variable support differ by client: > - Cursor: .cursor/mcp.json or global Cursor MCP settings > - Claude Code: ~/.claude.json or project-level config > - Run bash scripts/install.sh to get a pre-filled config block with your actual paths.

FastAPI / HTTP Mode (optional)

A FastAPI application (memory_engine/main.py) is included for direct API experimentation, demos, or containerized environments. It is not required for the standard MCP workflow.

uvicorn memory_engine.main:app --reload
# API docs at http://localhost:8000/docs

Manual setup (advanced)

# Install uv once
curl -LsSf https://astral.sh/uv/install.sh | sh

# Install dependencies
uv sync

# Run MCP server directly
uv run memory-engine-mcp --project-root /path/to/project --log-level DEBUG

Open your target project and start coding

That's it. Memory Engine starts automatically on the first MCP connection and handles bootstrap, indexing, and memory management from there.

---

What happens automatically

User opens project
     │
     ▼
MCP client starts memory-engine-mcp via stdio
     │
     ▼
Project root resolved (.git / pyproject.toml / package.json marker)
     │
     ▼
.memory-engine/ created (if first use)
     │
     ▼
README, ADRs, architecture docs, constraints indexed first
     │
     ▼
Broader source files indexed incrementally in background
     │
     ▼
Agent starts non-trivial coding task
     │
     ▼  [automatic]
retrieve_agent_context called
     │   → relevant constraints, incidents, decisions, procedures, source refs
     │
     ▼
Agent implements and validates
     │
     ▼  [automatic, on success]
reflect_and_write called
     │   → system evaluates retention gates
     │   → creates MemoryCandidates if worthy
     │   → promotes to memory tree
     │   → consolidates ancestor summaries
     │
     ▼
memory_status shows updated counts

---

Architecture

graph TD
    A[User / Coding Agent] --> B[MCP Client]
    B -->|stdio| C[Python MCP Server]
    C --> D[Agent Skills]
    C --> E[Service Layer]
    C --> F[Knowledge Layer]
    D -->|recall / inspect / reflect| E
    E -->|memory lifecycle| G[(Memory Tree\nSQLite)]
    F -->|ingest / search| H[(Knowledge Base\nSQLite + FTS5)]
    F --> I[Optional Vector Backend]
    E --> G
    F --> H
    C --> J[Bootstrap & Incremental Index]
    J --> K[.memory-engine/\nproject-local storage]
    G --> K
    H --> K

---

Agent calling chain

sequenceDiagram
    participant Agent
    participant MCP as MCP Server
    participant Skills as Agent Skills
    participant Services as Service Layer
    participant DB as SQLite / FTS5

    Agent->>MCP: retrieve_agent_context(task, files, symbols)
    MCP->>Skills: QueryAnalyzer.analyze()
    Skills->>DB: MemoryNode recall (intent-weighted SQL)
    Skills->>DB: KnowledgeSearch (FTS5 + vector RRF)
    Skills->>Skills: Rank, compose, dedup, token-trim
    MCP-->>Agent: ContextPack (memory + knowledge + trace)

    Note over Agent: implements and validates

    Agent->>MCP: reflect_and_write(task, outcome, verification_status)
    MCP->>Skills: ReflectionSkill.analyze() — gate check
    Skills->>Services: PostTaskService.reflect_and_write()
    Services->>Services: PromotionService.promote()
    Services->>Services: ConsolidationService.update_ancestors()
    Services->>DB: persist MemoryNode updates
    MCP-->>Agent: {outcome: "persisted", candidates_promoted: 2}

---

Memory lifecycle

Task result
    │
    ▼
ReflectionSkill.analyze()
    │  gates: outcome ≠ failed/reverted, verification_status, confidence ≥ threshold,
    │         summary word count, known-trivial patterns
    │
    ├─ skip → return {skip_reason}
    │
    └─ pass ▼
    │
MemoryCandidate generation
    ├─ constraint     (importance 0.92)
    ├─ procedure      (importance 0.72)
    ├─ incident/debug (importance 0.85)
    ├─ module         (importance 0.62)
    └─ decision       (importance 0.82)
    │
    ▼
PromotionService.promote()
    ├─ create     — new node
    ├─ update     — same title, content refreshed
    ├─ merge      — near-duplicate (Jaccard ≥ 0.80)
    ├─ supersede  — existing node confirmed wrong
    ├─ discard    — low value / already known
    └─ needs_review — conflicts with high-confidence existing node
    │
    ▼
ConsolidationService.update_ancestors()
    │  parent.summary = concat(children.summaries)
    ▼
cache invalidated + memory_revision bumped

Node statuses

| Status | Meaning | Default retrieval | |---|---|---| | candidate | Staged, pending promotion decision | Excluded | | active | Live, returned in recall | Included | | stale | Outdated; preserved for history | Penalized | | superseded | Replaced by newer node | Excluded | | needs_review | Flagged conflict; human review recommended | Excluded | | archived | Historical / audit-only (Phase 11) | Excluded | | compacted | Synthesis of source memories (Phase 11) | Included with lineage | | expired | Candidate never promoted past window (Phase 11) | Excluded |

Phase 11: Memory Retention

Memory does not grow indefinitely. The MemoryRetentionService runs lifecycle transitions:

# Diagnose
memory retention status 
memory retention report 

# Apply (dry-run by default)
memory retention run 
memory retention run  --no-dry-run

# Restore an archived memory
memory retention restore  

Protected types (constraint, security_rule, architecture, decision) are never auto-archived or auto-compacted.

See [docs/memory_retention_compaction.md](docs/memoryretentioncompaction.md).

---

Knowledge lifecycle

Documents / code / ADRs / tests / logs / diffs
    │
    ▼
redact()  ← 8 patterns: API keys, tokens, passwords, private keys,
           │             connection strings, JWTs, AWS keys, Slack tokens
    ▼
SHA-256 content hash → dedup check
    │
    ▼
Source-type chunker
    ├─ Markdown    → heading-based sections (≤1200 tokens)
    ├─ Code        → class/function blocks   (≤1000 tokens)
    ├─ Test report → result windows
    ├─ Log         → sliding windows         (≤600 tokens)
    └─ Diff/Patch  → hunk-based chunks
    │
    ▼
KnowledgeDocument + KnowledgeChunk (SQLite)
    │
    ├─ FTS5 insert    (lexical — always available)
    └─ Vector upsert  (optional — InMemoryVectorIndex or Qdrant)
    │
    ▼
hybrid retrieval → RRF fusion → source-quality ranking
    │
    ▼
UnifiedContextPack (40% of token budget)

─── Phase 10: multi-granularity write path (runs in parallel) ───────────────

same raw content
    │
    ├─ paragraph_segmenter  → KnowledgeParagraphORM  → knowledge_paragraphs_fts
    ├─ proposition_extractor → KnowledgePropositionORM → knowledge_propositions_fts
    └─ summarizer           → KnowledgeChunkSummaryORM → knowledge_summaries_fts
    │
    ▼
multigranular retrieval (25% of knowledge budget)
    │
    ▼
UnifiedContextPack.multigranular_chunks (independent of knowledge_chunks budget)

---

Directory structure

memory_engine/
├── main.py                  ← FastAPI app (dev / direct API use)
├── cli.py                   ← Debug CLI
├── config.py                ← Pydantic Settings
│
├── agent/                   ← Stage 8 namespace (re-exports)
│   ├── skills/              → memory_engine.skills
│   ├── policies/            → reflection gate constants
│   └── contracts/           → agent I/O domain models
│
├── skills/                  ← agent-facing behaviors (recall, inspect, reflect)
├── services/                ← domain orchestration (promotion, consolidation)
├── knowledge/               ← ingestion, chunking, FTS5, vector, search, fusion, cache
│                               proposition_extractor, paragraph_segmenter, summarizer,
│                               granularity_router, multigranular_search  (Phase 10)
├── repositories/            ← persistence abstraction (memory_node, candidate, evidence)
├── models/                  ← Pydantic domain + SQLAlchemy ORM
│
├── bootstrap/               ← local runtime (project_root, storage, security, state)
├── runtime/                 ← Stage 8 namespace (re-exports bootstrap + cache + config)
│
├── mcp/                     ← MCP adapter (tools, resources, server, project_context)
├── api/                     ← FastAPI routes
└── db/                      ← SQLite session + init

docs/
├── architecture/            ← system-overview, memory-lifecycle, knowledge-pipeline,
│                               retrieval-pipeline, mcp-integration, local-runtime,
│                               multigranular_memory_architecture  (Phase 10)
└── guides/                  ← quickstart, configuration, privacy-and-security

tests/
├── test_phase4.py – test_phase7.py   ← phase integration tests
└── test_*.py                          ← unit and component tests

---

MCP tools

| Tool | Purpose | |---|---| | seed_project_context | Call once on new projects. Write initial constraints, decisions, project description, and conventions directly as active memory nodes. Auto-extracts from README.md when fields are omitted. Eliminates cold-start problem. | | retrieve_agent_context | Retrieve memory + knowledge before a coding task. Phase 10: pass task_intent, preferred_layers, proposition_types to guide granularity routing. | | inspect_memory | Drill into a MemoryNode, its children, and evidence | | inspect_knowledge | Inspect a KnowledgeChunk or source file range (redacted) |

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: uudam42
• Source: uudam42/agent-memory-engine
• License: MIT

Install and usage instructions live in the source repository linked above.