|
| 1 | +# aimemo |
| 2 | + |
| 3 | +[](https://golang.org/) [](LICENSE) [](https://github.com/MyAgentHubs/aimemo/releases) |
| 4 | + |
| 5 | +Zero-dependency MCP memory server for AI agents — persistent, searchable, local-first, single binary. |
| 6 | + |
| 7 | +``` |
| 8 | +$ claude "let's keep working on the payment service" |
| 9 | +
|
| 10 | + ╭─ memory_context ──────────────────────────────────────────────────╮ |
| 11 | + │ [project: payment-service] │ |
| 12 | + │ │ |
| 13 | + │ Last session (3 days ago): │ |
| 14 | + │ • Stripe webhook signature verification — DONE │ |
| 15 | + │ • Idempotency key refactor — IN PROGRESS │ |
| 16 | + │ • Blocked: race condition in concurrent refund handler │ |
| 17 | + │ │ |
| 18 | + │ Related: Redis connection pool, pkg/payments/refund.go │ |
| 19 | + ╰───────────────────────────────────────────────────────────────────╯ |
| 20 | +
|
| 21 | + Picking up where we left off. The race condition in the refund |
| 22 | + handler looks like a missing mutex around the in-flight map. |
| 23 | + Let me check pkg/payments/refund.go ... |
| 24 | +
|
| 25 | + [... Claude works through the fix ...] |
| 26 | +
|
| 27 | + ╭─ memory_store (journal) ──────────────────────────────────────────╮ |
| 28 | + │ Resolved refund race — added sync.Mutex around inFlightRefunds. │ |
| 29 | + │ Tests passing. Next: load test with k6 at 500 rps. │ |
| 30 | + ╰───────────────────────────────────────────────────────────────────╯ |
| 31 | +``` |
| 32 | + |
| 33 | +## 🧠 Why aimemo |
| 34 | + |
| 35 | +- **No infra to babysit.** Single Go binary. No Docker, no Node.js runtime, no cloud account, no API keys. `brew install` in 30 seconds. |
| 36 | +- **Memory stays with the project.** Stored in `.aimemo/` next to your code — commit it to git or add it to `.gitignore`. Switch branches; memory follows the directory. |
| 37 | +- **Claude picks up exactly where it left off.** `memory_context` fires automatically on every session start. Claude sees what it was doing, what was blocked, what decisions were made. You stop repeating yourself. |
| 38 | +- **Full-text search that ranks correctly.** FTS5 + BM25 scoring weighted by recency and access frequency. Relevant memories surface first; old noise fades naturally. |
| 39 | +- **Concurrent sessions, no corruption.** SQLite WAL mode lets multiple Claude windows write simultaneously without locking each other out. |
| 40 | +- **You stay in control.** Every tool Claude has, you have from the terminal. Inspect, edit, retract, export. Your memory is readable Markdown or JSON — never locked in a proprietary format. |
| 41 | + |
| 42 | +## ⚡ Quick Start |
| 43 | + |
| 44 | +```bash |
| 45 | +# 1. Install |
| 46 | +brew install MyAgentHubs/tap/aimemo |
| 47 | + |
| 48 | +# 2. Initialize memory for your project (run from project root) |
| 49 | +aimemo init |
| 50 | + |
| 51 | +# 3. Register with Claude Code |
| 52 | +claude mcp add-json aimemo '{"type":"stdio","command":"aimemo","args":["serve"]}' |
| 53 | +``` |
| 54 | + |
| 55 | +Restart Claude Code. On the next session, Claude will automatically load project context. |
| 56 | + |
| 57 | +## 🔧 How It Works |
| 58 | + |
| 59 | +`aimemo serve` runs as a stdio MCP server; Claude Code manages the process lifecycle, so there is nothing to keep alive yourself. When Claude starts a session it calls `memory_context` to load relevant prior context; as it works it calls `memory_store` and `memory_link` to record decisions and relationships. You can call `aimemo search`, `aimemo list`, or `aimemo get` at any time to read or edit the same data from your terminal. Everything lives in a SQLite database inside `.aimemo/`, discovered by walking up from the current directory — the same way Git finds `.git/`. |
| 60 | + |
| 61 | +## 🛠 MCP Tools |
| 62 | + |
| 63 | +| Tool | Description | When Claude calls it | |
| 64 | +|------|-------------|----------------------| |
| 65 | +| `memory_context` | Returns ranked, recent observations for the current project | Session start — automatic | |
| 66 | +| `memory_store` | Saves an observation (fact, decision, journal entry, TODO) | After completing a task or making a decision | |
| 67 | +| `memory_search` | Full-text search across all observations, BM25-ranked | When it needs to recall something specific | |
| 68 | +| `memory_forget` | Soft-deletes an observation by ID | When instructed to discard something | |
| 69 | +| `memory_link` | Creates a named relationship between two observations | When it identifies a dependency or connection | |
| 70 | + |
| 71 | +All tool schemas total under 2,000 tokens. Each call has a hard 5-second timeout — the server never stalls your session. Empty-state queries return in under 5 ms. |
| 72 | + |
| 73 | +## 📋 CLI Reference |
| 74 | + |
| 75 | +### Setup |
| 76 | + |
| 77 | +| Command | Description | |
| 78 | +|---------|-------------| |
| 79 | +| `aimemo init` | Create `.aimemo/` in the current directory | |
| 80 | +| `aimemo serve` | Start the MCP stdio server (called by Claude Code automatically) | |
| 81 | +| `aimemo doctor` | Verify DB health, FTS5 support, WAL mode, and MCP registration | |
| 82 | + |
| 83 | +### Memory |
| 84 | + |
| 85 | +| Command | Description | |
| 86 | +|---------|-------------| |
| 87 | +| `aimemo add <text>` | Store an observation from the terminal | |
| 88 | +| `aimemo observe <text>` | Alias for `add` | |
| 89 | +| `aimemo retract <id>` | Surgically remove a single observation | |
| 90 | +| `aimemo forget <pattern>` | Soft-delete all observations matching a pattern | |
| 91 | +| `aimemo search <query>` | Full-text search with ranked results | |
| 92 | +| `aimemo get <id>` | Show a single observation by ID | |
| 93 | +| `aimemo link <id1> <id2> <label>` | Create a named link between two observations | |
| 94 | +| `aimemo append <id> <text>` | Append text to an existing observation | |
| 95 | + |
| 96 | +### Journal |
| 97 | + |
| 98 | +| Command | Description | |
| 99 | +|---------|-------------| |
| 100 | +| `aimemo journal` | Open an interactive journal entry (respects `$EDITOR`) | |
| 101 | +| `aimemo journal <text>` | Record a quick inline journal entry | |
| 102 | + |
| 103 | +### Inspect & Export |
| 104 | + |
| 105 | +| Command | Description | |
| 106 | +|---------|-------------| |
| 107 | +| `aimemo list` | List recent observations | |
| 108 | +| `aimemo tags` | List all tags in use | |
| 109 | +| `aimemo stats` | Show DB size, observation count, last-write time | |
| 110 | +| `aimemo export --format md` | Export all memory to Markdown | |
| 111 | +| `aimemo export --format json` | Export all memory to JSON | |
| 112 | +| `aimemo import <file>` | Import from mcp-knowledge-graph JSONL or aimemo JSON | |
| 113 | + |
| 114 | +All commands accept `--context <name>` to target a named context (a separate `.db` file inside `.aimemo/`). |
| 115 | + |
| 116 | +## ⚙️ Configuration |
| 117 | + |
| 118 | +`~/.aimemo/config.toml` — global defaults, all optional: |
| 119 | + |
| 120 | +```toml |
| 121 | +[defaults] |
| 122 | +context = "main" # default context name |
| 123 | +max_results = 20 # observations returned by memory_context |
| 124 | + |
| 125 | +[scoring] |
| 126 | +recency_weight = 0.7 # 0–1, weight of recency vs. access frequency |
| 127 | + |
| 128 | +[server] |
| 129 | +timeout_ms = 5000 # hard timeout on every MCP call |
| 130 | +log_level = "warn" # "debug" | "info" | "warn" | "error" |
| 131 | +``` |
| 132 | + |
| 133 | +Per-project overrides live in `.aimemo/config.toml` in the project root — same keys, project values win over global values. |
| 134 | + |
| 135 | +## 🔀 Migration from mcp-knowledge-graph |
| 136 | + |
| 137 | +```bash |
| 138 | +# Export your existing graph |
| 139 | +npx @modelcontextprotocol/inspector export > knowledge-graph.jsonl |
| 140 | + |
| 141 | +# Import into aimemo |
| 142 | +aimemo import knowledge-graph.jsonl |
| 143 | +``` |
| 144 | + |
| 145 | +Entities become observations; relations become links; tags are preserved. Run `aimemo stats` to confirm the import count. |
| 146 | + |
| 147 | +## 🤖 Claude Code Integration |
| 148 | + |
| 149 | +Register the server once per machine: |
| 150 | + |
| 151 | +```bash |
| 152 | +claude mcp add-json aimemo '{"type":"stdio","command":"aimemo","args":["serve"]}' |
| 153 | +``` |
| 154 | + |
| 155 | +Add the following to your project's `CLAUDE.md` so Claude knows memory is available and how to use it: |
| 156 | + |
| 157 | +```markdown |
| 158 | +## Memory |
| 159 | + |
| 160 | +This project uses aimemo for persistent memory across sessions. |
| 161 | + |
| 162 | +- Call `memory_context` at the start of every session to load prior context. |
| 163 | +- Call `memory_store` with `type: journal` before ending a session to record |
| 164 | + what was completed, what is still in progress, and any blockers. |
| 165 | +- Use `memory_link` to connect related observations (e.g. a bug to its fix, |
| 166 | + a decision to its rationale). |
| 167 | +- Do not store secrets, credentials, or PII. |
| 168 | +``` |
| 169 | + |
| 170 | +## 🤝 Contributing |
| 171 | + |
| 172 | +Bug reports and feature requests go in [GitHub Issues](https://github.com/MyAgentHubs/aimemo/issues). Pull requests are welcome — please open an issue first for anything non-trivial so we can align on direction before you invest time writing code. |
0 commit comments