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

> Discover how ai-memory grants AI coding agents persistent long-term memory across sessions and machines using versioned markdown, an FTS5 SQLite index, and automatic knowledge consolidation.

- Repository: [Fabio Akita/ai-memory](https://github.com/akitaonrails/ai-memory)
- Tags: how-to-guide
- Published: 2026-09-12

---

**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`](https://github.com/akitaonrails/ai-memory/blob/main/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`](https://github.com/akitaonrails/ai-memory/blob/main/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`](https://github.com/akitaonrails/ai-memory/blob/main/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`](https://github.com/akitaonrails/ai-memory/blob/main/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`](https://github.com/akitaonrails/ai-memory/blob/main/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`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-mcp/src/server.rs). The following examples demonstrate typical integration patterns:

```rust
// 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:

```rust
// 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`](https://github.com/akitaonrails/ai-memory/blob/main/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`](https://github.com/akitaonrails/ai-memory/blob/main/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`](https://github.com/akitaonrails/ai-memory/blob/main/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`](https://github.com/akitaonrails/ai-memory/blob/main/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`](https://github.com/akitaonrails/ai-memory/blob/main/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`](https://github.com/akitaonrails/ai-memory/blob/main/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`](https://github.com/akitaonrails/ai-memory/blob/main/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`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-core/src/page.rs), while [`crates/ai-memory-wiki/src/lib.rs`](https://github.com/akitaonrails/ai-memory/blob/main/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`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-store/src/lib.rs). The high-level design is documented in [`docs/ARCHITECTURE.md`](https://github.com/akitaonrails/ai-memory/blob/main/docs/ARCHITECTURE.md).