Ai Memory Protocol

🚀 AI Memory Protocol

Versioned, graph-based persistent memory for AI coding agents, powered by Sphinx-Needs.

AI agents often lose context between sessions. This protocol provides a structured way for them to remember, recall, and evolve knowledge, featuring full Git history, typed entries, graph links, and machine-readable output.

✨ Features

• Typed memories: Observations, decisions, facts, preferences, risks, goals, open questions.
• Graph links: Relates, supports, depends, supersedes, contradicts, example_of.
• Tag-based discovery: topic:api, repo:backend, tier:core.
• Context-optimized output: Brief / compact / context / JSON formats with body toggling.
• Stale detection: Auto-expire, review reminders, staleness checks.
• Auto-scaling: RST files split at 50 entries, transparent to queries.
• Git-native: Every memory is an RST directive, fully diffable and versioned.
• MCP server: Expose memory as tools for Claude Desktop, VS Code Copilot, and other MCP clients.
• Build-as-guardian: needs_warnings quality gates enforce tagging, linking, and body quality at build time.
• CLI-first: 12 subcommands for full lifecycle management.

📦 Installation

git clone https://github.com/bburda/ai_memory_protocol.git
pipx install -e ai_memory_protocol/

# With MCP server support
pipx install -e 'ai_memory_protocol/[mcp]'

This installs the memory CLI command (and optionally memory-mcp-stdio) globally on PATH.

🚀 Quick Start

# 1. Create a memory workspace
memory init .memories --name "My Project" --install

# 2. Add your first memory
memory add fact "API runs on port 8080" \
  --tags "topic:api,repo:backend" \
  --confidence high \
  --body "Gateway listens on 0.0.0.0:8080 by default" \
  --rebuild

# 3. Search
memory recall api port
memory recall --tag topic:api --format brief

# 4. Get full details
memory get FACT_api_runs_on_port_8080

📚 Documentation

How It Works

RST files (memory/*.rst)          ← Human + AI editable, Git-tracked
    │
    ▼ memory rebuild (sphinx-build)
needs.json (_build/html/needs.json)   ← Machine-readable index
    │
    ▼ memory recall / get / list
Formatted output                  ← Optimized for LLM context windows

Memories are stored as Sphinx-Needs directives in RST files. A memory rebuild command runs Sphinx to produce needs.json, which serves as the single query layer for all search operations. This means memories are both human-readable documentation and machine-queryable data.

CLI Reference

memory init <dir>                       # Create a new workspace
memory add <type> "<title>" [options]   # Record a memory
memory recall [query] [--tag ...] [--format brief|compact|context|json]
memory get <ID>                         # Full details of one memory
memory related <ID> [--hops N]          # Graph walk from a memory
memory list [--type TYPE] [--status S]  # Browse all memories
memory update <ID> [--confidence ...] [--add-tags ...] [--body ...] [--title ...]
memory deprecate <ID> [--by NEW_ID]     # Mark as deprecated
memory tags [--prefix PREFIX]           # Discover tags in use
memory stale                            # Find expired/overdue memories
memory review                           # Show memories needing review
memory rebuild                          # Rebuild needs.json

Key flags for recall:

• --format brief: Ultra-compact, minimal tokens.
• --body: Include body text (off by default).
• --sort newest|oldest|confidence|updated.
• --limit N: Cap results.
• --expand 0: Disable graph expansion.
• --stale: Only expired/review-overdue.

MCP Server

Expose memory tools to LLM clients via the Model Context Protocol.

Setup

Install with MCP extras:

pipx install -e 'ai_memory_protocol/[mcp]'

Claude Code

claude mcp add --transport stdio --env MEMORY_DIR=/path/to/.memories memory -- memory-mcp-stdio

Or add to .mcp.json in your project root (project scope):

{
  "mcpServers": {
    "memory": {
      "type": "stdio",
      "command": "memory-mcp-stdio",
      "env": {
        "MEMORY_DIR": "/path/to/.memories"
      }
    }
  }
}

VS Code (GitHub Copilot)

Add to .vscode/mcp.json:

{
  "servers": {
    "memory": {
      "command": "memory-mcp-stdio",
      "env": {
        "MEMORY_DIR": "${workspaceFolder}/.memories"
      }
    }
  }
}

Available MCP Tools

Memory Types

Graph Links

Metadata

Tagging Conventions

Tags use prefix:value format for consistent discovery:

• topic:: Subject area (topic:gateway, topic:auth).
• repo:: Repository (repo:backend, repo:web-ui).
• domain:: Knowledge domain (domain:robotics, domain:web).
• tier:: Importance level (tier:core, tier:detail).
• intent:: Purpose (intent:decision, intent:coding-style).

AI Agent Integration

Recommended Workflow

1. READ — Peek then Drill (two-phase recall)

Always use a two-phase approach. Never go straight to body text on broad queries.

Phase A — Peek (scan titles, zero body text):

memory recall --tag topic:gateway --format brief --expand 0

Returns [ID] Title (confidence) one-liners. Minimal tokens. Do this FIRST.

Phase B — Drill (read full body of specific memories):

memory get DEC_handler_context_pattern

Only after peeking, pick the 2 - 3 most relevant IDs and get them individually.

When to recall: Recall is NOT just a session-start ritual. Recall at each of these moments:

2. WRITE — Record at specific trigger points

Recording memories is NOT optional. Write at these concrete moments:

End-of-task writes: Summarize architecture learned (fact), record conventions (pref), note anything a future agent needs (mem), capture unfinished goals (goal).

Write quality rules:

• --tags is mandatory. Without tags, the memory is unfindable.
• --body must be self-contained with file paths and concrete details.
• Use --rebuild flag to make new memories immediately searchable.

3. SUPERSEDE, don't edit

When knowledge changes, add a new entry with --supersedes OLD_ID and deprecate the old one.

4. CHECK STALENESS periodically

Run memory stale at the start of long sessions to keep the graph accurate.

Context Window Optimization

• recall omits body by default. This is intentional, not a limitation.
• Peek with --format brief → drill with get <ID>. This is the core pattern.
• Use --limit 10 and --expand 0 when exploring broad topics.
• Use --tag filters to narrow results instead of free-text.
• Use memory tags to discover available tag prefixes before filtering.

Project Structure

ai_memory_protocol/
├── pyproject.toml           # Package definition, CLI + MCP entry points
├── README.md
├── LICENSE                  # Apache 2.0
├── CONTRIBUTING.md
├── .pre-commit-config.yaml
├── .github/workflows/ci.yml
└── src/
    └── ai_memory_protocol/
        ├── __init__.py
        ├── cli.py           # CLI (argparse, 12 subcommands)
        ├── mcp_server.py    # MCP server (8 tools, stdio transport)
        ├── config.py        # Type definitions, constants
        ├── engine.py        # Workspace detection, search, graph walk
        ├── formatter.py     # Output formatting (brief/compact/context/json)
        ├── rst.py           # RST generation, editing, file splitting
        └── scaffold.py      # Workspace scaffolding (init command)

Memory data lives in a separate workspace (e.g., .memories/), created with memory init.

Build-as-Guardian

The Sphinx build acts as a quality gate for the memory graph. needs_warnings in conf.py define constraints that fire during memory rebuild:

needs_warnings = {
    "missing_topic_tag": "type in ['mem','dec','fact',...] and not any(t.startswith('topic:') for t in tags)",
    "empty_body": "description == '' or description == 'TODO: Add description.'",
    "deprecated_without_supersede": "status == 'deprecated' and len(supersedes_back) == 0",
}

With sphinx-build -W (warnings as errors), the build fails if any memory violates these constraints. This means:

• Every memory must have at least one topic: tag.
• No empty placeholders survive to the index.
• Deprecated memories must be superseded by a replacement.

Agents learn to self-correct: if rebuild fails, they read the warning, fix the offending memory, and retry.

Human Role

Humans are observers and editors, not gatekeepers:

• Dashboards: memory/dashboards.rst contains needtable, needlist, and needflow directives rendering the live state of the memory graph as HTML.
• RST editing: Memories are plain RST, editable in any text editor or IDE with full diff/blame in Git.
• Override: Humans can update status, confidence, or tags on any memory via CLI or direct RST edit.
• Review: memory review surfaces memories whose review_after date has passed, prompting human validation.

The protocol is designed so that agents maintain knowledge autonomously while humans retain full visibility and override capability.

Contributing

See CONTRIBUTING.md for guidelines on how to contribute.

📄 License

Apache 2.0