How ai-memory Provides Long-Term Memory for AI Coding Agents Across Sessions and Machines

ai-memory gives AI coding agents a persistent "brain" by combining versioned markdown storage, an FTS5-backed SQLite index, and lifecycle hooks that trigger automatic knowledge consolidation.

The akitaonrails/ai-memory repository solves the ephemeral nature of LLM coding sessions by implementing a durable memory layer that survives CLI restarts, machine switches, and multi-agent workflows. Unlike simple conversation history, this system maintains a structured knowledge graph with full-text search, entity relationships, and automatic refinement.

Three-Layer Architecture for Persistent Memory

Atomic Wiki Storage with Supersession Chains

At the core of ai-memory’s long-term memory for AI coding agents lies a markdown-based wiki stored under <data_dir>/wiki/. Every piece of knowledge persists as a discrete markdown page that serves as the immutable source of truth.

The system achieves atomicity through a supersession versioning model implemented in crates/ai-memory-wiki/src/lib.rs. Rather than overwriting content, edits create new versions in a chain while preserving complete history. File writes follow a strict tmp + rename + fsync pattern to prevent corruption, ensuring that agents never lose historical context even during crashes or power failures.

High-Performance SQLite Indexing

To enable fast retrieval without parsing markdown files at query time, ai-memory maintains a companion SQLite database at <data_dir>/db/memory.sqlite managed by crates/ai-memory-store/src/lib.rs. The schema implements a multi-modal search strategy through four key structures:

• pages_fts – Full-text search using FTS5 over page titles and bodies
• entities – Lexical entity index for named concept extraction
• links – Wikilink graph capturing relationships between pages
• page_embeddings – Optional vector embeddings for semantic similarity

Queries execute a FTS5 + entity-match + link-neighbour RRF (Reciprocal Rank Fusion) blend, with an optional LLM reranker in crates/ai-memory-mcp/src/server.rs for higher-quality results.

Event-Driven Lifecycle Hooks

Agents communicate with the memory system through lifecycle events posted to the /hook endpoint. When an agent emits events like session-start or post-tool-use, the hook router (defined in docs/ARCHITECTURE.md) sanitizes the payload, assigns an ObservationKind, and enqueues a write command to a single-writer SQLite actor.

This fire-and-forget architecture ensures that untrusted text crosses only one trust boundary—the sanitizer—before entering the persistent store.

Multi-Tiered Retrieval Strategy

The system implements sophisticated memory tiers that decay at different rates based on access patterns and age:

• Working-session-only – Temporary scratchpad content
• Episodic (30d → 180d) – Recent events with time-based decay
• Semantic (indefinite) – Core concepts and extracted knowledge
• Procedural – Step-by-step instructions and gotchas

crates/ai-memory-store/src/lib.rs calculates salience scores using decay formulas and access counters, blending these tiers during retrieval to surface the most relevant context for current coding tasks.

Practical MCP Tool Integration

Agents interact with long-term memory through 18 built-in MCP tools exposed via crates/ai-memory-mcp/src/server.rs. The following examples demonstrate typical integration patterns:

// Query the long-term memory for relevant pages
let result = memory_query::call(memory_query::Params {
    q: "rust async file watcher".into(),
    n: Some(5),
    // default scope = current project
    ..Default::default()
})?;
// `result.hits` contains page IDs, titles, snippets

// Fetch the full content of a page when a snippet isn't enough
let page = memory_read_page::call(memory_read_page::Params {
    path: result.hits[0].path.clone(),
    ..Default::default()
})?;
println!("Full page:\n{}", page.body);

Writing new knowledge and submitting feedback triggers the auto-improvement pipeline:

// Write a new knowledge page from an agent-generated note
memory_write_page::call(memory_write_page::Params {
    path: "concepts/async_file_watcher.md".into(),
    body: "# Async File Watcher\n...details...".into(),

    ..Default::default()
})?;

// Submit feedback so the auto-improve scheduler can boost salience
memory_feedback::call(memory_feedback::Params {
    path: "concepts/async_file_watcher.md".into(),
    kind: FeedbackKind::Helpful,
    ..Default::default()
})?;

These calls map directly to the tool surface defined in the architecture specifications.

Auto-Improvement and Safety Guarantees

When a session ends, ai-memory automatically synthesizes a summary page and optionally invokes the consolidation pipeline in crates/ai-memory-consolidate/src/lib.rs. This LLM-driven process rewrites fragmented pages, extracts high-level concepts, and creates structured knowledge entries (decisions, gotchas, procedures) to prevent context bloat.

All writes funnel through the wiki writer in crates/ai-memory-core/src/page.rs, maintaining an audit log and ensuring that the SQLite index remains synchronized with the markdown source of truth. The atomic file operations and single-writer actor model prevent race conditions during concurrent access from multiple agents.

Summary

• ai-memory implements long-term memory for AI coding agents through a three-layer stack: atomic markdown wiki, SQLite FTS5 index, and lifecycle hook processing
• The <data_dir>/wiki/ directory stores versioned pages using supersession chains, while <data_dir>/db/memory.sqlite enables sub-second full-text and semantic search
• Query results blend FTS5, entity matching, and link graph analysis using RRF ranking, with optional LLM reranking for precision
• The MCP tool surface in crates/ai-memory-mcp/src/server.rs exposes 18 functions including memory_query, memory_write_page, and memory_feedback
• Automatic consolidation in crates/ai-memory-consolidate/src/lib.rs distills ephemeral notes into durable structured knowledge after each session

Frequently Asked Questions

How does ai-memory ensure data persistence across machine restarts?

All knowledge persists as markdown files in <data_dir>/wiki/ with atomic write semantics (temporary file creation followed by rename and fsync) implemented in crates/ai-memory-wiki/src/lib.rs. The companion SQLite database is purely an index; if corrupted, it can be rebuilt entirely from the markdown source, ensuring no data loss when moving between machines or recovering from crashes.

What search algorithms does ai-memory use for retrieval?

The system employs a hybrid approach combining FTS5 for lexical matching, entity extraction for concept identification, and wikilink graph traversal for relationship discovery. These signals fuse through Reciprocal Rank Fusion (RRF) scoring in crates/ai-memory-store/src/lib.rs, with an optional LLM reranker available for high-stakes queries requiring semantic nuance beyond keyword matching.

How does the automatic knowledge consolidation work?

Upon session termination, the auto-improve scheduler triggers crates/ai-memory-consolidate/src/lib.rs to analyze recent observations. The pipeline uses LLM calls to extract core concepts, merge redundant pages, and generate structured entries (decisions, procedures, gotchas). This prevents the "scroll effect" where old information gets buried, actively maintaining the knowledge graph's usefulness over extended timeframes.

Which files handle the core page and storage logic?

The page definition and atomic operations reside in crates/ai-memory-core/src/page.rs, while crates/ai-memory-wiki/src/lib.rs manages the file watcher and git integration. Database operations including FTS5 indexing and decay mathematics live in crates/ai-memory-store/src/lib.rs. The high-level design is documented in docs/ARCHITECTURE.md.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}