akitaonrails/ai-memory

Overview

ai‑memory is a Rust‑based, self‑contained long‑term memory service for AI‑driven coding assistants (like Claude Code, OpenAI Codex / Command‑Code …​). It records everything a coding agent — prompts & tool‑calls — that happens during a development session, automatically — via lifecycle‑hooks — and stores the data as ordinary markdown files in a git‑backed wiki.

• Cross‑agent – One shared memory that any supported agent can read/write, so you can switch from Claude Code to Codex without re‑explaining the project.
• **Cross‑project & cross‑machine **– A small user profile follows you to every repository; the memory server can run on any machine (laptop, homelab, Docker, etc.) and be accessed by many users.
• Zero‑LLM by default – Capture, search and hand‑off work entirely offline; optional LLM‑driven “dream” consolidation is opt‑in.
• Plain‑text source of truth – All notes live as markdown files that can be grepped, edited in Obsidian, version‑controlled with git, and restored.
• Aging & deduplication – Memory decays on a configurable schedule, with usage‑based reinforcement, automatic compaction, duplicate collapse and contradiction flagging – all without external APIs.
• Team‑ready – Multi‑user authentication, per‑person attribution, audit logs and per‑project sharing are built‑in.

How it works

1. Capture – Agents emit sanitized observations through lifecycle‑hooks.
2. Consolidate – At session end the observations are turned into markdown pages (optionally LLM‑written).
3. Recall – Any later session can search the wiki (full‑text, entities, links, optional vector embeddings) and receive a brief hand‑off.
4. Handoff – The next agent claims the hand‑off (typed protocol, claimed once) and continues the work.

The service runs as a single binary (ai‑memory) that hosts a small HTTP/MCP server and a derived index for fast retrieval.

Key Features

Feature	What it does
Multi‑agent integration	Supports >20 agents (Claude Code, Codex, Cursor, Gemini CLI, OpenCode, Grok, Devin, Kimi, Kiro, etc.) via first‑party hooks and MCP registration.
Cross‑project profile	Stores a per‑user profile (package manager, test layout, architectural habits) that is automatically applied to new repos.
Cross‑machine server	Run the server locally, in Docker/Podman, as a systemd service, or as a macOS menu‑bar app.
Git‑backed markdown wiki	All memory lives as .md files; the index can be rebuilt from the repo at any time.
Zero‑LLM default path	Capture, search and hand‑off use only full‑text search; no API keys required.
Optional LLM “dream”	Background pass that rewrites cold clusters into coherent pages (requires an LLM provider).
Aging & decay	Configurable per‑tier decay curves; used pages decay slower; automatic compaction, deduplication, contradiction flagging.
Audit & auth	Multi‑user authentication, per‑person attribution, immutable audit log of all mutations.
Self‑contained binary	One executable; install via AUR, RPM, Docker, macOS app, or native zip.
Extensible search	Full‑text, entity extraction, graph edges; optional vector embeddings via OpenAI/Anthropic etc.

Getting Started

1. Install – Use your platform’s package manager (AUR, RPM), Docker, or the macOS .app. The binary ships with systemd/launchd units for background service.
2. Initialize – Create a data directory and start the service:

   ai-memory --data-dir ~/.local/share/ai-memory init
   systemctl --user enable --now ai-memory.service
   

3. Wire an agent – Install the MCP client and hooks for the agent you use:

   ai-memory install-mcp   --client claude-code --apply
   ai-memory install-hooks --agent  claude-code --apply
   

   Repeat for other agents (codex, cursor, etc.).
4. Run – Launch your coding assistant through the wrapper so that capture happens automatically:

   ai-memory run claude      # starts Claude Code with hooks attached
   ai-memory run codex --yolo
   

   When you switch agents, the next one receives a hand‑off summarising where you left off.

Use Cases

Scenario	Benefit
Switching tools	Move from Claude Code to Codex mid‑task without losing context.
Team collaboration	All teammates share the same project‑level wiki; personal notes stay private.
Long‑term project memory	Automatic decay keeps frequently used knowledge alive while old, unused notes are compacted.
Offline work	Zero‑LLM mode works without any API keys; you can still search and hand‑off.
Audit & compliance	Immutable audit log records every mutation, useful for regulated environments.

Limitations & Considerations

• The “dream” consolidation and vector‑based ranking require external LLM/embedding providers and API keys.
• Native Windows support is still experimental; Windows users typically run via Docker or the zip install.
• Memory aging and compaction are configurable; mis‑tuned curves could prune useful notes too quickly.
• The service assumes a trusted environment – the markdown files are plain text and can be edited manually.

License & Community

ai‑memory is released under the MIT license. Development is in Rust (requires 1.95+). Contributions are welcome via pull requests; the project maintains a support matrix and CI for all listed agents.

---

All information above is taken directly from the repository’s README.