Content
# agent-memory-mcp
A local-first, LLM-free persistent memory stack for AI agents. Exposes a
canonical MCP (Model Context Protocol) server with 19 tools spanning 5
memory systems + persistent tasks.
## Highlights
- **Five memory systems, one MCP server**: memories (semantic + FTS5),
skills (procedural), bookmarks (URLs), snippets (code), decisions (ADR).
Tasks surface separately via `task_list`.
- **Linear-time guarantees**: pattern validation uses the `regex` module
(Thompson NFA) — even pathological patterns match in O(n).
- **Sub-20ms writes**: embedding cache + content-hash dedupe short-circuit
expensive work; first save with new content ~3ms, repeat save ~0.5ms.
- **Canonical response shapes**: every list returns
`{items, total, filter}`, every search returns `{items, total, query, took_ms}`.
One source of truth: [`docs/MCP_API.md`](./docs/MCP_API.md).
- **Modular**: 12 focused files (avg ~250 lines) instead of a monolithic
back-end. Adding a new memory system is a self-contained PR.
- **Live capture patterns**: models can write regex capture phrases
(`memory_save(category='pattern', ...)`) that propagate to the opencode
plugin within 30s without restart.
## Architecture
```
MCP client (opencode agent)
│ stdio JSON-RPC
▼
server.py ─────────► memory.sqlite3
│ in-process ├ memories, skills, bookmarks, snippets,
│ MLX embeddings │ decisions, tasks, patterns
│ (worker thread) ├ core_memory, memory_confidence, embeddings,
│ │ tool_usage, pending
▼
ov_mcp/ ← modular package (12 files)
shapes.py canonical response helpers
core/ db, embed, normalize
systems/ one file per memory system (atomic CRUD)
obs.py usage + health
```
Single SQLite file. No LLM calls in the data path. No HTTP between
components.
## Quick start
### Requirements
- macOS with Apple Silicon (MLX requirement)
- Python 3.12+
- `pip install mlx_embeddings regex`
### Install
```bash
git clone https://github.com/saqlain5544/agent-memory-mcp
cd agent-memory-mcp
pip install mlx_embeddings regex
```
### Run as an MCP server (stdio JSON-RPC)
Configure in `~/.config/opencode/opencode.json`:
```json
{
"mcp": {
"agent-memory": {
"type": "local",
"command": [
"/path/to/venv/bin/python",
"/path/to/agent-memory-mcp/server.py"
],
"timeout": 30000
}
}
}
```
### Run standalone (for testing)
```bash
/path/to/venv/bin/python server.py
# stdio JSON-RPC ready
```
## Tool surface (19 MCP tools)
See [`docs/MCP_API.md`](./docs/MCP_API.md) for the full canonical reference.
Tool names follow `<resource>_<verb>`:
| System | Tools |
|---|---|
| memories | `memory_save`, `memory_search`, `memory_recall`, `memory_list`, `memory_delete`, `memory_find_duplicates`, `memory_merge`, `core_memory_get`, `core_memory_set`, `memory_pending`, `memory_approve`, `memory_reject`, `memory_link` |
| skills | `skill_create`, `skill_list`, `skill_view`, `skill_search`, `skill_delete` |
| bookmarks | `bookmark_save`, `bookmark_list`, `bookmark_search`, `bookmark_delete` |
| snippets | `snippet_save`, `snippet_list`, `snippet_search`, `snippet_delete` |
| decisions | `decision_log_save`, `decision_log_get`, `decision_log_list`, `decision_log_update`, `decision_log_search` |
| tasks | `task_create`, `task_list`, `task_get`, `task_update`, `task_complete`, `task_delete` |
| observability | `memory_health`, `memory_usage_stats` |
## When to use which memory system
| What you learned | System | Category |
|---|---|---|
| Insight about how something works | memories | `insight` |
| Undocumented gotcha | memories | `gotcha` |
| User corrected approach | memories | `correction` |
| Recurring tool error | memories | `error` |
| Design decision worth keeping | decisions | (ADR shape) |
| Reusable code block | snippets | (language-tagged) |
| External doc/URL worth keeping | bookmarks | (URL) |
| Todo that survives sessions | tasks | (priority + due_at) |
| Multi-step procedure | skills | (with triggers) |
## Performance
| Path | Target p50 |
|---|---|
| `memory_save` (new) | <5ms |
| `memory_save` (dedupe hit) | <0.5ms |
| `memory_save` (repeat) | <0.5ms |
| `memory_search` | <1ms |
| `memory_recall` | <1ms |
| `bookmark_*`, `snippet_*`, etc. | <0.5ms |
| `memory_health` | <1ms |
## License
MIT
