English | 中文 Zero-dependency MCP memory server for AI agents — persistent, searchable, local-first, single binary. - No infra to babysit. Single Go binary. No Docker, no Node.js runtime, no cloud account, no API keys. brew install in 30 seconds. - 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 dire
Add this skill
npx mdskills install MyAgentHubs/aimemoWell-documented MCP memory server with useful tools, but lacks clear agent instruction guidance
1# aimemo23[](https://golang.org/) [](LICENSE) [](https://github.com/MyAgentHubs/aimemo/releases)45[English](README.md) | [中文](README.zh-CN.md)67Zero-dependency MCP memory server for AI agents — persistent, searchable, local-first, single binary.89```10$ claude "let's keep working on the payment service"1112 ╭─ memory_context ──────────────────────────────────────────────────╮13 │ [project: payment-service] │14 │ │15 │ Last session (3 days ago): │16 │ • Stripe webhook signature verification — DONE │17 │ • Idempotency key refactor — IN PROGRESS │18 │ • Blocked: race condition in concurrent refund handler │19 │ │20 │ Related: Redis connection pool, pkg/payments/refund.go │21 ╰───────────────────────────────────────────────────────────────────╯2223 Picking up where we left off. The race condition in the refund24 handler looks like a missing mutex around the in-flight map.25 Let me check pkg/payments/refund.go ...2627 [... Claude works through the fix ...]2829 ╭─ memory_store (journal) ──────────────────────────────────────────╮30 │ Resolved refund race — added sync.Mutex around inFlightRefunds. │31 │ Tests passing. Next: load test with k6 at 500 rps. │32 ╰───────────────────────────────────────────────────────────────────╯33```3435## 🧠 Why aimemo3637- **No infra to babysit.** Single Go binary. No Docker, no Node.js runtime, no cloud account, no API keys. `brew install` in 30 seconds.38- **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.39- **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.40- **Full-text search that ranks correctly.** FTS5 + BM25 scoring weighted by recency and access frequency. Relevant memories surface first; old noise fades naturally.41- **Concurrent sessions, no corruption.** SQLite WAL mode lets multiple Claude windows write simultaneously without locking each other out.42- **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.4344## ⚡ Quick Start4546```bash47# 1. Install48# Linux/macOS (one-line install):49curl -sSL https://raw.githubusercontent.com/MyAgentHubs/aimemo/main/install.sh | bash5051# Or macOS via Homebrew:52brew install MyAgentHubs/tap/aimemo5354# 2. Initialize memory for your project (run from project root)55aimemo init5657# 3. Register with Claude Code58claude mcp add-json aimemo-memory '{"command":"aimemo","args":["serve"]}'59```6061Restart Claude Code. On the next session, Claude will automatically load project context.6263### Quick Start for OpenClaw6465If you're using OpenClaw skills, see the [OpenClaw Integration](#-openclaw-integration) section below for per-skill memory isolation.6667## 🔧 How It Works6869`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/`.7071## 🛠 MCP Tools7273| Tool | Description | When Claude calls it |74|------|-------------|----------------------|75| `memory_context` | Returns ranked, recent observations for the current project | Session start — automatic |76| `memory_store` | Saves an observation (fact, decision, journal entry, TODO) | After completing a task or making a decision |77| `memory_search` | Full-text search across all observations, BM25-ranked | When it needs to recall something specific |78| `memory_forget` | Soft-deletes an observation by ID | When instructed to discard something |79| `memory_link` | Creates a named relationship between two observations | When it identifies a dependency or connection |8081All 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.8283## 📋 CLI Reference8485### Setup8687| Command | Description |88|---------|-------------|89| `aimemo init` | Create `.aimemo/` in the current directory |90| `aimemo serve` | Start the MCP stdio server (called by Claude Code automatically) |91| `aimemo doctor` | Verify DB health, FTS5 support, WAL mode, and MCP registration |9293### Memory9495| Command | Description |96|---------|-------------|97| `aimemo add <name> <type> [observations...] [--tag]` | Add an entity with one or more observations |98| `aimemo observe <entity-name> <observation>` | Add a new observation to an existing entity |99| `aimemo retract <entity-name> <observation>` | Remove a specific observation from an entity |100| `aimemo forget <entity-name> [--permanent]` | Soft-delete an entity (recoverable); use `--permanent` to hard-delete |101| `aimemo search <query>` | Full-text search with ranked results |102| `aimemo get <entity-name>` | Show an entity with all its observations and relations |103| `aimemo link <from> <relation> <to>` | Create a typed relation between two entities |104| `aimemo append <entity-name> <observation>` | Add an observation to an entity (alias for `observe`) |105106### Journal107108| Command | Description |109|---------|-------------|110| `aimemo journal` | Open an interactive journal entry (respects `$EDITOR`) |111| `aimemo journal <text>` | Record a quick inline journal entry |112113### Inspect & Export114115| Command | Description |116|---------|-------------|117| `aimemo list` | List recent observations |118| `aimemo tags` | List all tags in use |119| `aimemo stats` | Show DB size, observation count, last-write time |120| `aimemo export --format md` | Export all memory to Markdown |121| `aimemo export --format json` | Export all memory to JSON |122| `aimemo import <file>` | Import from JSONL or JSON export file |123124All commands accept `--context <name>` to target a named context (a separate `.db` file inside `.aimemo/`).125126## ⚙️ Configuration127128`~/.aimemo/config.toml` — global defaults, all optional:129130```toml131[defaults]132context = "main" # default context name133max_results = 20 # observations returned by memory_context134135[scoring]136recency_weight = 0.7 # 0–1, weight of recency vs. access frequency137138[server]139timeout_ms = 5000 # hard timeout on every MCP call140log_level = "warn" # "debug" | "info" | "warn" | "error"141```142143Per-project overrides live in `.aimemo/config.toml` in the project root — same keys, project values win over global values.144145## 🤖 Claude Code Integration146147Register the server once per machine:148149```bash150claude mcp add-json aimemo-memory '{"command":"aimemo","args":["serve"]}'151```152153Add the following to your project's `CLAUDE.md` so Claude knows memory is available and how to use it:154155```markdown156## Memory157158This project uses aimemo for persistent memory across sessions.159160- Call `memory_context` at the start of every session to load prior context.161- Call `memory_store` with `type: journal` before ending a session to record162 what was completed, what is still in progress, and any blockers.163- Use `memory_link` to connect related observations (e.g. a bug to its fix,164 a decision to its rationale).165- Do not store secrets, credentials, or PII.166```167168## 🦞 OpenClaw Integration169170aimemo solves OpenClaw's "remembers everything but understands none" problem with **per-skill memory isolation** and **zero infrastructure**.171172### Why aimemo for OpenClaw?173174**The Problem:**175- OpenClaw's native Markdown memory gets worse the more you use it176- Skills share memory, causing cross-contamination177- Context compression loses important context178179**The Solution:**180- ✅ **Zero dependencies** — Single Go binary, no Docker/Node.js/databases181- ✅ **Per-skill isolation** — Each skill gets its own memory database182- ✅ **Actually works** — BM25 search + importance scoring finds what matters183- ✅ **Local-first** — All data stays on your machine184185**vs Other Solutions:**186187| | aimemo | Cognee | memsearch | Supermemory |188|---|--------|---------|-----------|-------------|189| **Dependencies** | Zero | Neo4j/Kuzu | Milvus | Cloud service |190| **Installation** | 30 sec | Complex | Complex | Sign up required |191| **Skill isolation** | Built-in | Manual | Manual | N/A |192| **Linux support** | ✅ Native | ✅ | ✅ | N/A |193194### 5-Minute Setup195196```bash197# 1. Install (Linux amd64/arm64)198curl -sSL https://raw.githubusercontent.com/MyAgentHubs/aimemo/main/install.sh | bash199200# 2. Register MCP server with OpenClaw201claude mcp add-json aimemo-memory '{"command":"aimemo","args":["serve"]}'202203# Or add to ~/.openclaw/openclaw.json:204# {205# "mcpServers": {206# "aimemo-memory": {207# "command": "/usr/local/bin/aimemo",208# "args": ["serve"]209# }210# }211# }212213# 3. Initialize workspace memory214cd ~/.openclaw/workspace215aimemo init216217# 4. Restart OpenClaw Gateway218# Linux: systemctl --user restart openclaw-gateway219# macOS: launchctl stop com.openclaw.gateway && launchctl start com.openclaw.gateway220```221222### Per-Skill Memory Isolation223224Each skill gets its own isolated memory by using the `context` parameter:225226**In your SKILL.md:**227```markdown228---229name: my-skill230description: A skill with persistent memory231---232233# My Skill234235## Instructions236237When doing work:2382391. **Load memory FIRST**:240 ```241 memory_context({context: "my-skill"})242 ```2432442. Do your task with loaded context2452463. **Store learnings**:247 ```248 memory_store({249 context: "my-skill",250 entities: [{251 name: "preferences",252 entityType: "config",253 observations: ["User prefers snake_case"]254 }]255 })256 ```257258**CRITICAL**: Always pass `context: "my-skill"` to prevent memory pollution.259```260261**Result:**262```263~/.openclaw/workspace/.aimemo/264├── memory.db # Shared/default (no context)265├── memory-skill-a.db # Skill A's isolated memory266├── memory-skill-b.db # Skill B's isolated memory267└── memory-skill-c.db # Skill C's isolated memory268```269270### Complete Example271272See [`examples/openclaw-github-pr-reviewer/`](examples/openclaw-github-pr-reviewer/) for a full working skill that:273- Reviews GitHub PRs274- Learns code style preferences275- Remembers patterns across sessions276- Stores feedback for improvement277278### Documentation279280- **[OpenClaw Integration Guide](docs/openclaw-integration.md)** — Step-by-step setup281- **[OpenClaw Workflow](docs/openclaw-workflow.md)** — Architecture deep-dive282- **[Example Skill](examples/openclaw-github-pr-reviewer/)** — Complete implementation283284### Debugging285286```bash287# List a skill's memory288aimemo list --context my-skill289290# Search within a skill291aimemo search "keyword" --context my-skill292293# Export for inspection294aimemo export --context my-skill --format json > memory.json295296# Get database stats297aimemo stats --context my-skill298```299300## 🖥 Client Support301302aimemo works with any MCP-compatible AI coding client. The server command is always `aimemo serve`.303304> **PATH note (macOS/Homebrew):** GUI apps may not inherit your shell PATH. If a client can't find `aimemo`, use the absolute path `/opt/homebrew/bin/aimemo` instead.305306### Claude Code307308```bash309claude mcp add-json aimemo-memory '{"command":"aimemo","args":["serve"]}'310```311312Or commit `.mcp.json` to the project root (see the one in this repo as an example).313314### Cursor315316Project-local (`.cursor/mcp.json`) or global (`~/.cursor/mcp.json`):317318```json319{320 "mcpServers": {321 "aimemo-memory": {322 "command": "aimemo",323 "args": ["serve"]324 }325 }326}327```328329### Windsurf330331Edit `~/.codeium/windsurf/mcp_config.json` (global only):332333```json334{335 "mcpServers": {336 "aimemo-memory": {337 "command": "aimemo",338 "args": ["serve"]339 }340 }341}342```343344### OpenAI Codex CLI345346Project-local (`.codex/config.toml`) or global (`~/.codex/config.toml`):347348```toml349[mcp_servers.aimemo-memory]350command = "aimemo"351args = ["serve"]352```353354### Cline (VS Code)355356Edit `~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json`:357358```json359{360 "mcpServers": {361 "aimemo-memory": {362 "command": "aimemo",363 "args": ["serve"],364 "disabled": false,365 "alwaysAllow": []366 }367 }368}369```370371### Continue (VS Code / JetBrains)372373Project-local (`.continue/mcpServers/aimemo-memory.yaml`):374375```yaml376name: aimemo-memory377version: 0.0.1378schema: v1379mcpServers:380 - name: aimemo-memory381 command: aimemo382 args:383 - serve384```385386Or add to global `~/.continue/config.yaml` under the `mcpServers:` key.387388### Zed389390In `~/.zed/settings.json` (global) or `.zed/settings.json` (project-local):391392```json393{394 "context_servers": {395 "aimemo-memory": {396 "source": "custom",397 "command": "aimemo",398 "args": ["serve"],399 "env": {}400 }401 }402}403```404405## 🤝 Contributing406407Bug 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.408
Full transparency — inspect the skill content before installing.