aimemo

# aimemo [](https://golang.org/) [](LICENSE) [](https://github.com/MyAgentHubs/aimemo/releases) [English](README.md) | [中文](README.zh-CN.md) Zero-dependency MCP memory server for AI agents — persistent, searchable, local-first, single binary. ``` $ claude "let's keep working on the payment service" ╭─ memory_context ──────────────────────────────────────────────────╮ │ [project: payment-service] │ │ │ │ Last session (3 days ago): │ │ • Stripe webhook signature verification — DONE │ │ • Idempotency key refactor — IN PROGRESS │ │ • Blocked: race condition in concurrent refund handler │ │ │ │ Related: Redis connection pool, pkg/payments/refund.go │ ╰───────────────────────────────────────────────────────────────────╯ Picking up where we left off. The race condition in the refund handler looks like a missing mutex around the in-flight map. Let me check pkg/payments/refund.go ... [... Claude works through the fix ...] ╭─ memory_store (journal) ──────────────────────────────────────────╮ │ Resolved refund race — added sync.Mutex around inFlightRefunds. │ │ Tests passing. Next: load test with k6 at 500 rps. │ ╰───────────────────────────────────────────────────────────────────╯ ``` ## 🧠 Why aimemo - **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 directory. - **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. - **Full-text search that ranks correctly.** FTS5 + BM25 scoring weighted by recency and access frequency. Relevant memories surface first; old noise fades naturally. - **Concurrent sessions, no corruption.** SQLite WAL mode lets multiple Claude windows write simultaneously without locking each other out. - **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. ## ⚡ Quick Start ```bash # 1. Install # Linux/macOS (one-line install): curl -sSL https://raw.githubusercontent.com/MyAgentHubs/aimemo/main/install.sh | bash # Or macOS via Homebrew: brew install MyAgentHubs/tap/aimemo # 2. Initialize memory for your project (run from project root) aimemo init # 3. Register with Claude Code claude mcp add-json aimemo-memory '{"command":"aimemo","args":["serve"]}' ``` Restart Claude Code. On the next session, Claude will automatically load project context. ### Quick Start for OpenClaw If you're using OpenClaw skills, see the [OpenClaw Integration](#-openclaw-integration) section below for per-skill memory isolation. ## 🔧 How It Works `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/`. ## 🛠 MCP Tools | Tool | Description | When Claude calls it | |------|-------------|----------------------| | `memory_context` | Returns ranked, recent observations for the current project | Session start — automatic | | `memory_store` | Saves an observation (fact, decision, journal entry, TODO) | After completing a task or making a decision | | `memory_search` | Full-text search across all observations, BM25-ranked | When it needs to recall something specific | | `memory_forget` | Soft-deletes an observation by ID | When instructed to discard something | | `memory_link` | Creates a named relationship between two observations | When it identifies a dependency or connection | 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. ## 📋 CLI Reference ### Setup | Command | Description | |---------|-------------| | `aimemo init` | Create `.aimemo/` in the current directory | | `aimemo serve` | Start the MCP stdio server (called by Claude Code automatically) | | `aimemo doctor` | Verify DB health, FTS5 support, WAL mode, and MCP registration | ### Memory | Command | Description | |---------|-------------| | `aimemo add <name> <type> [observations...] [--tag]` | Add an entity with one or more observations | | `aimemo observe <entity-name> <observation>` | Add a new observation to an existing entity | | `aimemo retract <entity-name> <observation>` | Remove a specific observation from an entity | | `aimemo forget <entity-name> [--permanent]` | Soft-delete an entity (recoverable); use `--permanent` to hard-delete | | `aimemo search <query>` | Full-text search with ranked results | | `aimemo get <entity-name>` | Show an entity with all its observations and relations | | `aimemo link <from> <relation> <to>` | Create a typed relation between two entities | | `aimemo append <entity-name> <observation>` | Add an observation to an entity (alias for `observe`) | ### Journal | Command | Description | |---------|-------------| | `aimemo journal` | Open an interactive journal entry (respects `$EDITOR`) | | `aimemo journal <text>` | Record a quick inline journal entry | ### Inspect & Export | Command | Description | |---------|-------------| | `aimemo list` | List recent observations | | `aimemo tags` | List all tags in use | | `aimemo stats` | Show DB size, observation count, last-write time | | `aimemo export --format md` | Export all memory to Markdown | | `aimemo export --format json` | Export all memory to JSON | | `aimemo import <file>` | Import from JSONL or JSON export file | All commands accept `--context <name>` to target a named context (a separate `.db` file inside `.aimemo/`). ## ⚙️ Configuration `~/.aimemo/config.toml` — global defaults, all optional: ```toml [defaults] context = "main" # default context name max_results = 20 # observations returned by memory_context [scoring] recency_weight = 0.7 # 0–1, weight of recency vs. access frequency [server] timeout_ms = 5000 # hard timeout on every MCP call log_level = "warn" # "debug" | "info" | "warn" | "error" ``` Per-project overrides live in `.aimemo/config.toml` in the project root — same keys, project values win over global values. ## 🤖 Claude Code Integration Register the server once per machine: ```bash claude mcp add-json aimemo-memory '{"command":"aimemo","args":["serve"]}' ``` Add the following to your project's `CLAUDE.md` so Claude knows memory is available and how to use it: ```markdown ## Memory This project uses aimemo for persistent memory across sessions. - Call `memory_context` at the start of every session to load prior context. - Call `memory_store` with `type: journal` before ending a session to record what was completed, what is still in progress, and any blockers. - Use `memory_link` to connect related observations (e.g. a bug to its fix, a decision to its rationale). - Do not store secrets, credentials, or PII. ``` ## 🦞 OpenClaw Integration aimemo solves OpenClaw's "remembers everything but understands none" problem with **per-skill memory isolation** and **zero infrastructure**. ### Why aimemo for OpenClaw? **The Problem:** - OpenClaw's native Markdown memory gets worse the more you use it - Skills share memory, causing cross-contamination - Context compression loses important context **The Solution:** - ✅ **Zero dependencies** — Single Go binary, no Docker/Node.js/databases - ✅ **Per-skill isolation** — Each skill gets its own memory database - ✅ **Actually works** — BM25 search + importance scoring finds what matters - ✅ **Local-first** — All data stays on your machine **vs Other Solutions:** | | aimemo | Cognee | memsearch | Supermemory | |---|--------|---------|-----------|-------------| | **Dependencies** | Zero | Neo4j/Kuzu | Milvus | Cloud service | | **Installation** | 30 sec | Complex | Complex | Sign up required | | **Skill isolation** | Built-in | Manual | Manual | N/A | | **Linux support** | ✅ Native | ✅ | ✅ | N/A | ### 5-Minute Setup ```bash # 1. Install (Linux amd64/arm64) curl -sSL https://raw.githubusercontent.com/MyAgentHubs/aimemo/main/install.sh | bash # 2. Register MCP server with OpenClaw claude mcp add-json aimemo-memory '{"command":"aimemo","args":["serve"]}' # Or add to ~/.openclaw/openclaw.json: # { # "mcpServers": { # "aimemo-memory": { # "command": "/usr/local/bin/aimemo", # "args": ["serve"] # } # } # } # 3. Initialize workspace memory cd ~/.openclaw/workspace aimemo init # 4. Restart OpenClaw Gateway # Linux: systemctl --user restart openclaw-gateway # macOS: launchctl stop com.openclaw.gateway && launchctl start com.openclaw.gateway ``` ### Per-Skill Memory Isolation Each skill gets its own isolated memory by using the `context` parameter: **In your SKILL.md:** ```markdown --- name: my-skill description: A skill with persistent memory --- # My Skill ## Instructions When doing work: 1. **Load memory FIRST**: ``` memory_context({context: "my-skill"}) ``` 2. Do your task with loaded context 3. **Store learnings**: ``` memory_store({ context: "my-skill", entities: [{ name: "preferences", entityType: "config", observations: ["User prefers snake_case"] }] }) ``` **CRITICAL**: Always pass `context: "my-skill"` to prevent memory pollution. ``` **Result:** ``` ~/.openclaw/workspace/.aimemo/ ├── memory.db # Shared/default (no context) ├── memory-skill-a.db # Skill A's isolated memory ├── memory-skill-b.db # Skill B's isolated memory └── memory-skill-c.db # Skill C's isolated memory ``` ### Complete Example See [`examples/openclaw-github-pr-reviewer/`](examples/openclaw-github-pr-reviewer/) for a full working skill that: - Reviews GitHub PRs - Learns code style preferences - Remembers patterns across sessions - Stores feedback for improvement ### Documentation - **[OpenClaw Integration Guide](docs/openclaw-integration.md)** — Step-by-step setup - **[OpenClaw Workflow](docs/openclaw-workflow.md)** — Architecture deep-dive - **[Example Skill](examples/openclaw-github-pr-reviewer/)** — Complete implementation ### Debugging ```bash # List a skill's memory aimemo list --context my-skill # Search within a skill aimemo search "keyword" --context my-skill # Export for inspection aimemo export --context my-skill --format json > memory.json # Get database stats aimemo stats --context my-skill ``` ## 🖥 Client Support aimemo works with any MCP-compatible AI coding client. The server command is always `aimemo serve`. > **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. ### Claude Code ```bash claude mcp add-json aimemo-memory '{"command":"aimemo","args":["serve"]}' ``` Or commit `.mcp.json` to the project root (see the one in this repo as an example). ### Cursor Project-local (`.cursor/mcp.json`) or global (`~/.cursor/mcp.json`): ```json { "mcpServers": { "aimemo-memory": { "command": "aimemo", "args": ["serve"] } } } ``` ### Windsurf Edit `~/.codeium/windsurf/mcp_config.json` (global only): ```json { "mcpServers": { "aimemo-memory": { "command": "aimemo", "args": ["serve"] } } } ``` ### OpenAI Codex CLI Project-local (`.codex/config.toml`) or global (`~/.codex/config.toml`): ```toml [mcp_servers.aimemo-memory] command = "aimemo" args = ["serve"] ``` ### Cline (VS Code) Edit `~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json`: ```json { "mcpServers": { "aimemo-memory": { "command": "aimemo", "args": ["serve"], "disabled": false, "alwaysAllow": [] } } } ``` ### Continue (VS Code / JetBrains) Project-local (`.continue/mcpServers/aimemo-memory.yaml`): ```yaml name: aimemo-memory version: 0.0.1 schema: v1 mcpServers: - name: aimemo-memory command: aimemo args: - serve ``` Or add to global `~/.continue/config.yaml` under the `mcpServers:` key. ### Zed In `~/.zed/settings.json` (global) or `.zed/settings.json` (project-local): ```json { "context_servers": { "aimemo-memory": { "source": "custom", "command": "aimemo", "args": ["serve"], "env": {} } } } ``` ## 🤝 Contributing 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.