How ai-memory Enables Long-Term Cross-Session Memory for AI Coding Agents

ai-memory provides persistent memory for AI coding agents through a three-tier architecture: a markdown wiki for durable storage, a SQLite-backed index for fast retrieval, and lifecycle hooks that automatically capture and consolidate knowledge across sessions.

The akitaonrails/ai-memory repository implements a Rust-based memory server designed specifically for AI coding agents that need to remember context across CLI restarts and multiple sessions. Unlike ephemeral context windows, this system creates a persistent "brain" that survives process termination while providing structured retrieval through multiple memory tiers.

The Three-Layer Memory Architecture

Markdown Wiki as the Source of Truth

At the foundation of ai-memory's long-term cross-session memory lies a durable markdown wiki stored under <data_dir>/wiki/. Every piece of knowledge persists as a atomic markdown page that agents can read, write, and link using standard wikilink syntax.

The wiki implements supersession chains for versioning. When an agent updates or deletes a page, the system creates a new version linked to its predecessor rather than overwriting history. This immutable audit trail ensures that crates/ai-memory-wiki/src/lib.rs can reconstruct any prior state while maintaining atomic file operations. All writes follow a strict tmp + rename + fsync pattern to prevent corruption during crashes.

SQLite-Backed Index for Fast Retrieval

While the wiki provides durability, raw filesystem access is too slow for agentic workflows. ai-memory mirrors the wiki in <data_dir>/db/memory.sqlite using several specialized indices as implemented in crates/ai-memory-store/src/lib.rs:

• pages_fts – Full-text search (FTS5) over page titles and bodies
• entities – Lexical entity index for named concept recognition
• links – Wikilink graph for relationship traversal
• page_embeddings – Optional vector storage for semantic similarity

When an agent queries memory, the system performs RRF (Reciprocal Rank Fusion) blending FTS5 results, entity matches, and link-neighbor analysis. An optional LLM reranker in the pipeline can reorder results for higher relevance before returning them to the agent.

Lifecycle Hooks and Auto-Improvement

Agents emit structured lifecycle events (e.g., session-start, post-tool-use) that POST to the /hook endpoint. The hook router in crates/ai-memory-mcp/src/server.rs sanitizes these payloads, assigns an ObservationKind classification, and enqueues write commands to a single-writer SQLite actor.

When sessions terminate, the auto-improve scheduler triggers. This pipeline—implemented in crates/ai-memory-consolidate/src/lib.rs—synthesizes summary pages and runs LLM-driven consolidation steps that rewrite fragmented notes into structured knowledge like decisions, gotchas, and procedures. The sanitizer serves as the sole trust boundary for untrusted text, ensuring that malicious or malformed inputs cannot corrupt the memory store.

Memory Tiers and Decay Formulas

ai-memory doesn't treat all knowledge equally. The system organizes information into distinct tiers with different retention policies:

• Working-session-only – Temporary context cleared after each CLI invocation
• Episodic – Recent events with 30-day to 180-day decay windows
• Semantic – Indefinite vector-based storage for core concepts
• Procedural – Permanent structured knowledge (checklists, API patterns)

As detailed in docs/ARCHITECTURE.md, access counters and decay formulas determine which tier applies to each page. Frequently accessed procedural knowledge receives permanent retention, while transient debugging notes fade according to exponential decay schedules calculated in crates/ai-memory-store/src/lib.rs.

MCP Tool Interface for Agents

Agents interact with long-term memory through 18 built-in MCP tools exposed by crates/ai-memory-mcp/src/server.rs. Below are typical Rust SDK calls for common operations:

// Query the knowledge base using hybrid search
let result = memory_query::call(memory_query::Params {
    q: "rust async file watcher".into(),
    n: Some(5),
    ..Default::default()
})?;
// result.hits contains page IDs, titles, and snippets

// Retrieve full page content when snippets insufficient
let page = memory_read_page::call(memory_read_page::Params {
    path: result.hits[0].path.clone(),
    ..Default::default()
})?;

// Persist new knowledge from agent observations
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 to boost page 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 MCP tool surface defined in the server, enabling any MCP-compatible agent to read, write, and search without understanding the underlying storage mechanics.

Safety and Persistence Guarantees

The architecture enforces strict safety invariants for cross-session reliability. All writes funnel through the wiki writer component, guaranteeing atomic filesystem operations even during power failures. The SQLite database functions as a derived index—if corrupted, it can be rebuilt entirely from the markdown wiki source of truth.

Because hooks operate on a fire-and-forget basis, agents cannot block on write operations. The single-writer SQLite actor serializes concurrent updates while the sanitizer strips dangerous content before it reaches storage. This design ensures that switching between different ai-memory-aware CLIs in the same repository leaves the wiki unchanged and the index instantly reusable.

Summary

• Durable Storage: Markdown wiki with supersession versioning provides immutable history under <data_dir>/wiki/
• Fast Retrieval: SQLite FTS5, entity indices, and link graphs enable hybrid RRF search in <data_dir>/db/memory.sqlite
• Automatic Capture: Lifecycle hooks (session-start, post-tool-use) feed the auto-improvement pipeline for knowledge consolidation
• Tiered Decay: Working, episodic, semantic, and procedural tiers use access counters and decay formulas to manage relevance
• Safety First: Atomic file writes, audit logs, and input sanitization protect memory integrity across process restarts

Frequently Asked Questions

How does ai-memory survive CLI restarts?

The system stores all knowledge as markdown files in the wiki directory and maintains a SQLite index as a cache. Since both reside in persistent storage (<data_dir>/), terminating the CLI process leaves data intact. When a new session starts, the agent reconnects to the existing SQLite database and wiki without reinitialization.

What makes the search multi-tiered instead of simple keyword matching?

According to docs/ARCHITECTURE.md, ai-memory blends FTS5 full-text search, entity recognition, and wikilink graph traversal using Reciprocal Rank Fusion. It optionally reranks results with an LLM and maintains separate decay schedules for different memory tiers (working, episodic, semantic, procedural), ensuring agents retrieve both recent context and foundational knowledge.

Can multiple agents share the same memory store simultaneously?

Yes. The single-writer SQLite actor in crates/ai-memory-store/src/lib.rs serializes concurrent writes while allowing concurrent reads. Since the markdown wiki uses atomic rename operations (tmp + rename + fsync), multiple agents can safely append knowledge without corrupting the underlying files, though they should coordinate through the MCP server to avoid logical conflicts.

How does the auto-improvement process work?

When sessions end, the consolidation pipeline in crates/ai-memory-consolidate/src/lib.rs triggers. It synthesizes session summaries and uses LLM prompts to rewrite fragmented notes into structured knowledge—extracting decisions, procedures, and gotchas. This prevents knowledge base bloat while preserving critical insights indefinitely.

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