ai-memory: A Portable Memory Layer for AI Agents, Written in Rust

Forum topic · ✨步子哥 · 2026-08-17

Summary

ai-memory is a local-first, long-term memory layer for AI coding agents, written in Rust by Akita On Rails. It captures key decisions, failed attempts, and open questions during agent sessions via MCP configuration and lifecycle hooks, then stores them deterministically in SQLite with FTS5 full-text indexing plus a human-readable Markdown mirror. Its standout feature is cross-vendor handoff: it supports over twenty agent CLIs including Claude Code, Codex, Cursor, Gemini CLI, OpenCode, and Devin CLI, automatically injecting handoff notes via SessionStart hooks when developers switch tools. The post argues that SQLite+Markdown beats vector databases and LLM-as-memory approaches through determinism, auditability, and zero vendor lock-in, while Rust's ownership model eliminates data races from concurrent agent writes. It also covers capture exclusions for sensitive data, honest limitations (hook fragmentation, capture sees outputs not reasoning, single-machine only), and positions the project as solving memory portability between vendors the way Git solved code collaboration.

You sigh, getting ready to explain your whole line of thinking all over again.

This is the "amnesia" of the Agent era — every AI coding CLI is an island, with no shared memory. Akita On Rails (a veteran of the Brazilian Ruby community) got tired of this fragmentation and wrote ai-memory in Rust: a local-first, long-term memory layer that lets agents hand off work to each other.

What It Actually Does

In one sentence: it turns agents' working memory into portable files.

Concretely, ai-memory does three things:

1. Automatic capture: Through MCP configuration + lifecycle hooks, it records key decisions, failed attempts, and open questions in every agent session. No need for the agent to call anything — hooks fire on SessionStart/Stop events. 2. Structured storage: Dual writes to SQLite (with FTS5 full-text indexing) and Markdown. SQLite gives agents a query interface; Markdown gives humans something to read. It's not a black box — you can open the files directly and see what the agent remembered. 3. Cross-vendor handoff: Supports Claude Code, Codex, Cursor, Gemini CLI, OpenCode, Devin CLI, Command Code, Antigravity CLI, Grok Build CLI, OpenClaw... twenty-plus agent CLIs. When you switch agents, the new agent's SessionStart hook automatically injects the previous handoff notes.

The revolutionary part: agent vendors can't lock you in anymore. You're no longer bound to Anthropic just because "Claude Code remembers my project" — your memory is yours, stored locally, readable by anyone.

Why Rust + SQLite

Akita's choices run against the trend: it's 2026 — why not a vector database? Why not LLM-as-memory?

The answer lies in "debuggability." Vector databases are black boxes — you don't know why the agent recalled something. LLM-as-memory is Schrödinger's cat — every recollection might differ. SQLite + FTS5 is deterministic: the same query always returns the same result. Markdown is human-readable: when a bug appears, you can open the file and see exactly what the agent got wrong.

Rust isn't about speed either — an agent memory layer doesn't need nanosecond latency. Rust's real value is type safety and thread safety. Agents may write memory concurrently (multiple subagents working at once), and Rust's ownership model eliminates data races at compile time. A classic engineering trade of compiler checks for runtime checks.

How It Differs From Other Memory Solutions

| Approach | Storage | Readability | Cross-agent | Deterministic | |----------|---------|-------------|-------------|---------------| | Vector DBs (Mem0, etc.) | vectors | black box | needs adapters | fuzzy | | LLM context compression | model-internal | unreadable | unsupported | non-deterministic | | MemTools (declarative contracts) | JSON | semi-readable | needs adapters | deterministic | | ai-memory | SQLite+MD | human-readable | native support | deterministic |

The key difference: ai-memory isn't "installing a memory system on the agent" — it's "installing a window through which humans can understand agent memory." The Markdown dual-write is the soul of the design: it turns the agent's black-box thought process into auditable engineering documentation.

Conceptual Lineage: Memory's "USB-C Port"

This points to a bigger pattern. In a lineage of "solving problems at a different layer," ai-memory is the eleventh member:

Octopuses use RNA editing for "DNA pretraining + compute at inference time"
Slime molds externalize memory in slime trails
SOPHIA routes different states to different output directions
Euclid-MCP outsources reasoning to Prolog
ai-memory moves memory out of the agent and onto the filesystem

Shared principle: don't strengthen the same component — solve the problem at a different layer. An agent's context window is limited, volatile, and vendor-locked. So stop fighting the context window; externalize memory to the filesystem where every agent can read it.

This is isomorphic to MemTools' "USB-C port" idea: MemTools gives memory systems a standard interface, while ai-memory gives working memory a standard format. MemTools solves "how memory systems interoperate" (the data layer); ai-memory solves "how agents hand off to each other" (the session layer).

An Overlooked Detail: Capture Exclusions

A design detail deserves its own mention: native commands enforce capture exclusions. Sensitive operations (say, asking the agent to handle files containing secrets) are not written into memory.

This isn't a technical footnote — it's a security boundary. The biggest risk of agent memory isn't "forgetting too much" but "remembering too much" — recording API keys, passwords, customer data, then handing it all to the next agent. ai-memory accounts for this from day one: capture is opt-in (--capture-assistant is off by default) and exclusions are enforced.

This mirrors the output-layer intervention tier in alignment frameworks: don't retrain the model, just constrain at the output layer. ai-memory constrains at the memory-capture layer, far more reliable than trusting the agent to "judge for itself what to remember."

Limitations and an Honest Assessment

Not without problems:

Hook dependency: Every agent CLI's lifecycle hooks differ. Devin CLI has no SessionEnd hook, so you must run ai-memory finalize-session manually. This fragmentation mirrors the current state of the agent ecosystem.
Memory quality: Automatic capture records "what happened," not "why." The agent's reasoning remains a black box — hooks see inputs and outputs, not intermediate thinking.
Single-machine assumption: Local SQLite doesn't support team collaboration. If two people use different agents on the same project, memories fork. That's the next problem to solve.

But as "the first memory standard of the agent era," it gets the most important thing right: memory belongs to the user, not the agent vendor.

Closing

ai-memory recalls the birth of Git — Linus's problem wasn't "how to store code" but "how code flows between people." Akita's problem isn't "how agents remember" but "how agent memory flows between vendors."

From an agent-engineering perspective, this re-validates the "granularity isomorphism" principle: the carrier of memory should match the granularity of its use. Agents work at session level, so memory is captured at session level; agents need cross-vendor handoff, so memory is stored at the filesystem level. Not a stronger model — a better-matched granularity.

---

Project: https://github.com/akitaonrails/ai-memory Language: Rust Stars today: 207 Best for: developers switching between multiple agent CLIs, especially mixed Claude Code + Codex workflows