# Agent Memory Mcp

> A portable, Dockerized, Obsidian-backed memory system for AI agents — MCP server, HTTP API, CLI, and hybrid search

- **Type:** MCP server
- **Install:** `agentstack add mcp-ambushalgorithm-agent-memory-mcp`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [ambushalgorithm](https://agentstack.voostack.com/s/ambushalgorithm)
- **Installs:** 0
- **Category:** [Databases](https://agentstack.voostack.com/c/databases)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [ambushalgorithm](https://github.com/ambushalgorithm)
- **Source:** https://github.com/ambushalgorithm/agent-memory-mcp

## Install

```sh
agentstack add mcp-ambushalgorithm-agent-memory-mcp
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Agent Memory MCP

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

  
  
  =3.11">

## 🚀 Quick Start

**Prerequisites:** [Docker](https://docs.docker.com/get-docker/), [Make](https://www.gnu.org/software/make/), [curl](https://curl.se/).

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

2. 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.

3. Configure environment:
   ```bash
   cp .env.example .env
   ```

4. Build and start:
   ```bash
   docker compose up --build
   ```

5. 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

```text
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

```text
~/.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**](https://github.com/qdrant/fastembed) — Local ONNX embedding generation (default provider)
- [**sqlite-vec**](https://github.com/asg017/sqlite-vec) — Vector ANN search inside SQLite

## 📡 API

### Health Check

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

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

### Search Memory

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

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

### Propose Memory

```bash
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:
```json
{"id": "proposal-042", "status": "accepted", "path": "inbox/proposal-042.md"}
```

### CLI Examples

```bash
# 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.

```bash
# 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:
```bash
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.

```bash
# 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.

```bash
# 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.

```bash
# 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)

```bash
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)

```bash
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](https://github.com/your-org/agent-memory-mcp/issues) 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](https://github.com/ambushalgorithm)
- **Source:** [ambushalgorithm/agent-memory-mcp](https://github.com/ambushalgorithm/agent-memory-mcp)
- **License:** MIT

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

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** yes
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** yes
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-ambushalgorithm-agent-memory-mcp
- Seller: https://agentstack.voostack.com/s/ambushalgorithm
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.