ai-memory: Shared, Git-Backed Long-Term Memory for AI Coding Agents

Table of Contents

Why This Repo, Why Now

Checking github.com/trending today, the top repository is akitaonrails/ai-memory — described by its README as “long-term memory for AI coding agents. Quit Claude Code mid-task, start OpenAI Codex in the same directory, continue without re-explaining the architecture, the failed approaches, or the open questions.”

The problem it targets is familiar to anyone who switches between coding agents during a workday: each harness (Claude Code, Cursor, Codex, and the rest) keeps its own memory, if it keeps one at all, so context about a project’s architecture, failed approaches, and open questions doesn’t travel with you when you change tools, hand off to a teammate, or switch machines. ai-memory’s pitch is a single shared memory layer, captured automatically from agent lifecycle hooks, stored as a git-backed markdown wiki rather than an opaque database, and retrievable by more than twenty supported agent harnesses through MCP.

Part of why it’s resonating right now is the design choice to make the zero-LLM path the default: capture, search, and cross-agent handoffs all work with no API key, while LLM-backed features (session summaries, semantic search, an opt-in “dream” consolidation pass) stay strictly opt-in. As always, a trending position reflects visibility and momentum at a point in time, not an independent verdict on quality, security, or production-readiness — those are reviewed separately below.

What the Technology Actually Is

Per the project’s README and ARCHITECTURE.md, ai-memory ships as one self-contained Rust binary that runs an MCP/HTTP server and owns a single data directory:

<data_dir>/
├── wiki/    # markdown source of truth, git-versioned
├── raw/     # immutable sanitized managed-workstream transcript segments
├── db/      # SQLite indexes, including FTS5, entities, and embeddings
├── models/  # reserved for local embedding models
└── logs/    # rolling tracing output

Documented architectural pieces:

• Lifecycle hooks — installed per agent harness, these observe prompts, tool calls, and session boundaries, sanitize the captured data at what the README calls “a typed privacy boundary,” and POST it to the server.
• Consolidation — at session end, captured observations are compiled into readable markdown wiki pages (optionally LLM-written, but useful without one).
• Retrieval — the next session, in any supported agent, gets a bounded startup brief and can search full-text (SQLite FTS5), entities, and links, with optional local or remote vector embeddings fused into one ranking.
• Cross-agent handoffs — a typed protocol where each handoff has an owner and is claimed exactly once, so quitting Claude Code mid-task and opening Codex in the same directory resumes from a defined state rather than a lossy summary.
• Optional management UI — a server-rendered console for user administration, session inspection, and personal MCP API keys, gated behind both a compile-time feature flag and a runtime flag.

At a high level, per the README’s own diagram: capture ──▶ consolidate ──▶ recall ──▶ handoff. Hooks observe silently, session-end turns observations into wiki pages, the next session gets a brief plus search, and handoffs pass the baton explicitly between harnesses.

Purpose and Use Cases

Per the README, ai-memory’s primary purpose is giving a coding agent persistent, portable project memory that isn’t tied to one tool, one machine, or one person.

Documented use cases and target users:

• Solo developers switching agent harnesses mid-task — quitting Claude Code and resuming the same work in Codex or Cursor without re-explaining architecture decisions or what’s already been tried.
• Multi-machine workflows — picking up a project on a laptop with the same memory state left on a desktop, since memory lives in a server you run rather than on a single machine’s disk.
• Teams sharing project knowledge — pointing every teammate’s agent at one server so project knowledge is shared while personal handoffs stay personal, with multi-user auth, per-person attribution, and an audit log documented as built in, not a paid tier.
• Adopting an existing project with history — the documented ai-memory bootstrap command for importing months of prior project context when first adopting ai-memory on a mature codebase.
• Teams wanting memory they can inspect and edit by hand — since the source of truth is plain markdown files (grep-able, editable in Obsidian, syncable with rsync), not a vector store or binary blob.

Target users per the README and support matrix are developers already using one or more of the 20+ supported harnesses (Claude Code, Codex, Cursor, Gemini CLI, OpenCode, Devin, Kiro, GitHub Copilot CLI, and others listed in docs/support-matrix.md) who want continuity across tool switches without standing up their own memory infrastructure.

Installation

Per the project’s documented Quick start. The maintainer documents the native two-command install as the primary path on Linux and macOS, with separate documented paths for Windows, Arch Linux, Fedora, Docker, and NixOS.

Prerequisites

• A supported OS: Linux, macOS, Windows via WSL2 (native Windows is documented as experimental), or NixOS.
• For the Docker path: Docker or Podman, plus an agent CLI from the support matrix.
• For a source/macOS-app build: a Rust toolchain and, on macOS, Xcode / Swift 6.

Recommended: native install (Linux and macOS)

curl -fsSL https://github.com/akitaonrails/ai-memory/releases/latest/download/install.sh | sh
ai-memory setup

Per the README, install.sh downloads the release build for your OS and CPU, checks it against the release’s published SHA-256 checksum and refuses to install without a match, and links ~/.local/bin/ai-memory. ai-memory setup then creates the data directory (owner-only on Unix), starts a per-user service (systemd --user or a launchd LaunchAgent), and wires MCP, hooks, and Agent Skills for every agent it detects, or the ones named with --agent. It shows its plan first and asks before writing anything; --plan previews with no changes.

Windows

irm https://github.com/akitaonrails/ai-memory/releases/latest/download/install.ps1 | iex
ai-memory setup

Docker (no native binary required on the host)

docker run -d --name ai-memory \
    --restart unless-stopped \
    -p 127.0.0.1:49374:49374 \
    -v ai-memory-data:/data \
    docker.io/akitaonrails/ai-memory:latest

The README notes this quick-start container runs with no authentication (the container never runs init), binds to loopback only by default, and that a CLI wrapper (also checksum-verified against a published SHA-256) is needed on the host to wire agent hooks:

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

Minimal getting-started example

After ai-memory setup completes and you restart your agent, the README’s documented smoke test is simply to ask it:

What do you remember about this project?

and confirm it answers through ai-memory rather than its own built-in memory, if any.

Quick Verification

Based on documented commands in the README and docs/install.md:

1. Version check — ai-memory --version confirms the installed binary and rules out a stale Cargo- or package-manager-installed binary shadowing it earlier in PATH.
2. Self-check during setup — ai-memory setup itself runs a documented self-check that writes nothing: a GET /healthz call, a memory_status MCP call using the install’s own credential, and ai-memory doctor.
3. Scoped health check — ai-memory doctor reports the health of every detected agent registration; per the README, its overall healthy field can read false while the one workflow you actually use is fine, so check the specific client/provider you wired.
4. Service status — ai-memory status (or docker exec ai-memory ai-memory status --json for the container path) reports whether the server is reachable and its current auth state (e.g., auth: none (loopback)).
5. End-to-end check — asking your agent “What do you remember about this project?” after a restart is the README’s own documented confirmation that hooks, MCP, and recall are working together.

Security Review

Verified from the repository itself (SECURITY.md, DATA_HANDLING.md, and the README’s Security section):

• The project documents a private disclosure process: GitHub private security advisories at github.com/akitaonrails/ai-memory/security/advisories/new, with a stated 7-day response target and a 30-day patch goal once an issue is confirmed. Public issues requesting vulnerability details are explicitly discouraged.
• SECURITY.md states ai-memory’s threat model explicitly: it is a “single-tenant workstation/homelab service.” It supports multiple attributed users, but every authenticated user shares the same trust domain and can read the same project memory — there are no per-user or per-project ACLs documented for v1, and the project recommends separate servers/data directories for users who must not see one another’s data.
• No encryption at rest is documented for v1; the data directory is described as a plain filesystem tree, with reliance on OS filesystem permissions (owner-only 0700/0600 on Unix for newly created files).
• The HTTP server binds to loopback only by default and “fails closed” before serving unauthenticated traffic on a non-loopback bind; --allow-insecure-no-auth is documented as a deliberate, explicitly named override. SECURITY.md notes the fail-closed check is relaxed to a warning inside a container, since a published Docker port forces an internal 0.0.0.0 bind regardless of real host reachability — the operator’s own -p flag is what actually determines exposure there.
• A fresh ai-memory init mints a root bearer token by default; installs created before that default, and the documented Docker quick-start, run without authentication until ai-memory auth enable is run, and ai-memory status is documented to report that state.
• Published executable integrity: install scripts and Docker wrapper binaries are distributed as GitHub Release assets with SHA-256 companion checksums that the install scripts verify before use; GitHub Actions are pinned to reviewed commits; Gitleaks scanning runs on pushed/proposed commit ranges plus a separate periodic full-history scan.
• SECURITY.md documents several narrower hardening details: a Host-header allowlist against DNS rebinding, a 10 MB inbound request body cap, per-project data isolation enforced at the database-query level, and symlink/reparse-point rejection when reading or writing the (operator-editable, therefore untrusted) wiki directory.
• Assistant-turn capture is opt-in behind a documented double opt-in (capture_assistant server-side plus install-hooks --capture-assistant client-side) and is sanitized on both the client and server before storage — SECURITY.md is explicit that this sanitizer is “a best-effort credential strip, not a guarantee.”
• The project is licensed MIT (LICENSE).
• Release history shows active maintenance: v3.1.1 is the latest tag at the time of writing, with a visible release cadence back through the 2.x and 3.0 lines on the repository’s tags page, and recent commits (including same-day fixes to consolidation and TTL-expiry handling) landing within the current week.
• No published GitHub Security Advisories were found against this repository at the time of writing; absence of advisories is not proof of absence of vulnerabilities.

Security considerations to weigh yourself (documented factors, not verified vulnerabilities):

• SECURITY.md explicitly flags stored-content prompt injection as a standing concern: handoffs, briefs, and LLM maintenance prompts mark stored memory as “untrusted historical data,” but the project itself states that sanitization “remain[s] defense in depth, not proof that a model cannot be manipulated.”
• Enabling the optional LLM reranker (AI_MEMORY_RERANKER=llm) sends live queries plus bounded page titles/snippets to the configured LLM provider — SECURITY.md recommends leaving reranking off, or using a local provider, when query content must not leave the server.
• The no-ACL, single-tenant trust model means anything written into shared project memory is readable by every authenticated user of that server; this is a design choice documented up front, not an oversight, but it matters for any multi-team or multi-tenant deployment.
• Running the server on a non-loopback bind without AI_MEMORY_AUTH_TOKEN (outside the documented fail-closed default) would expose MCP and admin routes on the local network.

Practical recommendations:

• Pin a specific released version rather than always pulling :latest (Docker) or re-running the install script unattended, given the active release cadence.
• Verify the published SHA-256 checksum yourself before trusting install.sh/install.ps1 in any automated or CI context, even though the script already performs this check.
• Keep the server bound to loopback unless you specifically need LAN/WAN access, and enable ai-memory auth enable plus a reverse-proxy TLS layer before exposing it beyond localhost, per docs/https-via-proxy.md.
• Treat any LLM-backed feature (consolidation, reranking, the opt-in “dream” pass) as an explicit outbound-data decision, and leave it off for repositories where query content or stored notes must never leave the host.
• Run a new install in an isolated environment first, and review docs/security.md and DATA_HANDLING.md directly before wiring ai-memory into a shared team server, since the single-tenant trust model is a structural property, not a configuration bug to be worked around.

Should You Use It?

Strengths: a published, detailed threat model (SECURITY.md) that states what the project does and does not defend against rather than implying blanket security; a zero-LLM default path for capture, search, and handoffs, with every LLM-backed feature opt-in; a git-backed, human-editable markdown source of truth instead of an opaque database; broad harness coverage (20+ agents) behind one MCP/CLI interface; checksum-verified release artifacts; and a visibly active release cadence (v3.1.1 current, with same-week bug-fix commits).

Limitations: the documented threat model is explicitly single-tenant — no per-user or per-project ACLs, so any authenticated user on a shared server can read the same project memory; no encryption at rest in v1; prompt-injection risk from stored content is acknowledged by the maintainers as unsolved in general, only mitigated; and the optional LLM reranker and “dream” consolidation pass send query or note content to an external provider if enabled.

Good fit for: individual developers and small teams already using one or more supported coding-agent harnesses who want continuity when switching tools or machines; homelab or small-team setups comfortable running and securing their own server; and anyone who specifically wants project memory stored as inspectable, git-versioned markdown rather than a vector database.

Evaluate alternatives if: you need per-user or per-project access control on a shared server (ai-memory’s own SECURITY.md states this is out of scope for v1); your organization requires encryption at rest for stored project context; or your threat model cannot tolerate any current gap in prompt-injection defenses for LLM-consumed stored content.

Primary sources used: GitHub repository · README · SECURITY.md · DATA_HANDLING.md · docs/install.md · docs/ARCHITECTURE.md · docs/support-matrix.md · Repository tags · LICENSE