Agent Memory Mcp

Agent Memory MCP

A portable, Dockerized, Obsidian-backed memory system for AI agents.

=3.11">

🚀 Quick Start

Prerequisites: Docker, Make, curl.

1. Clone the repository:

``bash git clone https://github.com/ambushalgorithm/agent-memory-mcp.git cd agent-memory-mcp ``

1. Initialize data directories:

``bash make setup ` This creates ~/.agent-memory/brain/ and ~/.agent-memory/data/ with the required subdirectory structure. If you have existing data in the old ./brain/ or ./data/ locations (from a previous checkout), make setup` migrates it automatically.

1. Configure environment:

``bash cp .env.example .env ``

1. Build and start:

``bash docker compose up --build ``

1. Verify it's running:

``bash curl http://localhost:8787/v1/health ``

✨ Features

• 🐳 Dockerized — One-command setup with docker compose up. No profile selection required.
• 🔍 Hybrid Search — FTS5 BM25 keyword search + vector ANN + RRF fusion for best results.
• 🧠 Markdown Brain — Human-readable markdown files as the source of truth in ~/.agent-memory/brain/.
• 📥 Proposal Inbox — Agents write to inbox/, not directly to canon. Safety first.
• 🔌 API Interfaces — MCP-style JSON-RPC over stdio for agents, HTTP API for apps, CLI for maintenance.
• 💾 Backup Ready — Git versioned backups and Rsync file sync modes.
• 📝 Obsidian-Compatible — Browse and edit brain files with any markdown editor.
• 👁️ Audit Events — Full event log for all memory operations.
• 🏗️ Context Pack Builder — Build rich context packs for AI agents.
• ⚡ Zero External Dependencies — Local ONNX embeddings via fastembed.

🧠 Architecture

The system has three storage layers:

1. 📁 Filesystem Brain — Markdown files in ~/.agent-memory/brain/ organized by domain (agents, identity, projects, decisions, knowledge, etc.). This is the human-readable source of truth.
2. 🗄️ SQLite Database — ~/.agent-memory/data/memory.sqlite stores metadata, FTS5 keyword index, vector embeddings, and the audit log.
3. 🌐 API / Interface Layer — MCP-style JSON-RPC over stdio (for agents), HTTP API (for apps/bots), and CLI (for maintenance).

Data Flow

query ──► SQLite FTS5 (BM25) ──┐
                                ├─► RRF fusion ──► ranked results
query ──► embed() → vec0 ANN  ──┘

Hybrid Search Pipeline: When a query arrives, it runs two parallel searches — keyword (FTS5 BM25) and semantic (vector ANN via sqlite-vec). Results are fused using Reciprocal Rank Fusion (RRF) to produce a single ranked list. The RRF constant (RRF_K, default 60) controls how aggressively low-ranked results from one method are boosted.

Safety Model

By default, agents do not overwrite canonical memory. They write proposals to ~/.agent-memory/brain/inbox/. A human or trusted process reviews and merges proposals into the appropriate domain directories.

Brain Directory Structure

~/.agent-memory/brain/
├── inbox/         # Agent proposals (pending review)
├── agents/        # Agent-specific rules and context
├── identity/      # Core identity documents
├── preferences/   # User preferences
├── projects/      # Project memory
├── _templates/    # Note templates
├── decisions/     # Decision records
├── knowledge/     # Knowledge base
├── logs/          # Activity logs
└── systems/       # System-level memory

⚙️ Configuration

| Variable | Default | Description | Required | |---|---|---|---| | EMBEDDING_PROVIDER | fastembed | Embedding provider: fastembed (local ONNX) or openai | No | | EMBEDDING_MODEL | BAAI/bge-base-en-v1.5 | Embedding model name | No | | OPENAI_API_KEY | — | OpenAI API key | Only when EMBEDDING_PROVIDER=openai | | RRF_K | 60 | RRF constant for Reciprocal Rank Fusion | No | | EMBEDDING_DIM | 768 | Embedding vector dimension | No |

> 📝 See .env.example for the full list of available environment variables.

Key Dependencies

• fastembed — Local ONNX embedding generation (default provider)
• sqlite-vec — Vector ANN search inside SQLite

📡 API

Health Check

curl -X GET http://localhost:8787/v1/health \
  -H 'Content-Type: application/json'

Response:

{"status": "ok", "timestamp": "2026-06-11T12:00:00Z"}

Search Memory

curl -X POST http://localhost:8787/v1/memory/search \
  -H 'Content-Type: application/json' \
  -d '{"query": "communication preferences"}'

Response:

{
  "results": [
    {"id": "pref-001", "content": "User prefers best answer first, then steps.", "score": 0.89}
  ]
}

Propose Memory

curl -X POST http://localhost:8787/v1/memory/propose \
  -H 'Content-Type: application/json' \
  -d '{
    "type": "preference",
    "tags": ["communication"],
    "content": "User prefers best answer first, then steps."
  }'

Response:

{"id": "proposal-042", "status": "accepted", "path": "inbox/proposal-042.md"}

CLI Examples

# Search from inside the container
docker compose exec memory python -m scripts.memory_cli search "preferences"

# Reindex the database from brain files
docker compose exec memory python -m scripts.memory_cli reindex

🔄 Reset

Two tiers of reset are available, depending on how much you want to clean up.

Quick Reset (database only)

Delete the SQLite database to start fresh. Brain files (Markdown source of truth) are preserved — just run reindex afterward to repopulate.

Use this for: Daily resets when you want to keep your brain files.

# Via Makefile (recommended)
make reset
make up

# Via CLI (from inside a running container)
docker compose exec memory python -m scripts.memory_cli reset --force

# Manual
rm -f ~/.agent-memory/data/memory.sqlite*

After resetting, rebuild the database:

docker compose exec memory python -m scripts.memory_cli reindex

Full Wipe (removes everything)

Stops containers, deletes ALL data including brain files, and reinitializes from scratch.

Use this for: A completely clean slate — all brain files, database, and directory structure are destroyed and recreated.

# Via Makefile (recommended)
make reset-full
make up

# Via CLI (from inside a running container)
docker compose exec memory python -m scripts.memory_cli reset --force --all

💾 Backup

Git mode (versioned)

Creates a local git commit of all changes in ~/.agent-memory/ with a timestamp. Optionally push to a remote.

# Local timestamped commit
make backup

# With remote push
export AGENT_MEMORY_REMOTE=git@github.com:user/agent-memory-backup.git
make backup

Rsync mode (file sync)

Syncs ~/.agent-memory/ to a configured destination.

# Default destination (~/pCloud/agent-memory-backup)
make backup-sync

# Custom destination
export AGENT_MEMORY_SYNC_DEST=/path/to/backup
make backup-sync

> 📋 See .env.example for backup configuration variables.

🗓️ Scheduling Automated Backups

macOS (launchd)

scripts/install-backup-launchd.sh

Installs a launchd agent that runs make backup daily at 02:00. Logs are written to ~/Library/Logs/agent-memory-backup.log.

Linux (systemd)

scripts/install-backup-systemd.sh

Installs a systemd user timer that runs make backup daily (OnCalendar=daily).

Both installers check prerequisites, copy the unit files with the correct repository path, and verify the installation. Run them with no arguments for the default setup.

✅ Project Status

This is a working v1 production scaffold — actively developed and ready for use.

• 🐳 Fully Dockerized with docker compose
• ⚡ FastAPI HTTP server with OpenAPI docs
• 🔌 MCP-style JSON-RPC stdio server
• 🗄️ SQLite schema with FTS5 full-text search
• 🔍 sqlite-vec vector ANN search
• 🧪 Hybrid search (FTS5 BM25 + semantic vectors + RRF fusion)
• 📝 Markdown parser with YAML frontmatter
• 🏗️ Context pack builder
• 📥 Proposal inbox safety model
• 👁️ Audit event logging
• 📖 OpenAPI and MCP schema files

License

This project is licensed under the [MIT License](LICENSE).

Contributing

Have a suggestion or found a bug? Open an issue or submit a pull request.

Source & license

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

• Author: ambushalgorithm
• Source: ambushalgorithm/agent-memory-mcp
• License: MIT

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