aimemo

English | 中文

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

# 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 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:

[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:

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:

## 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

# 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:

---
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/ 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 — Step-by-step setup
• OpenClaw Workflow — Architecture deep-dive
• Example Skill — Complete implementation

Debugging

# 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

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):

{
  "mcpServers": {
    "aimemo-memory": {
      "command": "aimemo",
      "args": ["serve"]
    }
  }
}

Windsurf

Edit ~/.codeium/windsurf/mcp_config.json (global only):

{
  "mcpServers": {
    "aimemo-memory": {
      "command": "aimemo",
      "args": ["serve"]
    }
  }
}

OpenAI Codex CLI

Project-local (.codex/config.toml) or global (~/.codex/config.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:

{
  "mcpServers": {
    "aimemo-memory": {
      "command": "aimemo",
      "args": ["serve"],
      "disabled": false,
      "alwaysAllow": []
    }
  }
}

Continue (VS Code / JetBrains)

Project-local (.continue/mcpServers/aimemo-memory.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):

{
  "context_servers": {
    "aimemo-memory": {
      "source": "custom",
      "command": "aimemo",
      "args": ["serve"],
      "env": {}
    }
  }
}

🤝 Contributing

Bug reports and feature requests go in GitHub 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.