# How ai-memory Provides Long-Term Memory for AI Coding Agents: A Technical Deep Dive

> Discover how ai-memory delivers long-term memory for AI coding agents using a three-layer architecture: wiki storage, SQLite indexes, and auto-improvement pipelines. Boost agent performance now.

- Repository: [Fabio Akita/ai-memory](https://github.com/akitaonrails/ai-memory)
- Tags: deep-dive
- Published: 2026-09-10

---

**ai-memory gives AI coding agents persistent, searchable memory through a three-layer architecture: markdown-based wiki storage, SQLite-backed retrieval indexes, and lifecycle-driven auto-improvement pipelines.**

The `akitaonrails/ai-memory` open-source project solves a critical gap in AI agent tooling—how to retain knowledge across CLI restarts, sessions, and even agent replacements. Rather than treating memory as ephemeral context, ai-memory builds a durable knowledge infrastructure that agents can query, write to, and refine automatically. According to the project's architecture documentation, this system combines file-based persistence with high-performance search and LLM-driven consolidation to create what the authors call a "persistent brain" for coding agents.

## Markdown Wiki: The Immutable Source of Truth

At the foundation of ai-memory's long-term memory system is a plain-text markdown wiki stored under `<data_dir>/wiki/`. Every unit of knowledge exists as a standalone `.md` file, making the entire memory corpus human-readable, version-controllable, and portable.

### Supersession-Based Versioning

Unlike traditional databases that overwrite records, ai-memory uses **supersession chains** to preserve complete history. When an agent edits or deletes a page, the system creates a new revision without destroying the previous version. This design enables:

- **Full auditability** of how knowledge evolved
- **Safe experimentation**—agents can modify pages without fear of data loss
- **Rollback capability** to any prior state

The wiki layer handles atomic writes through a tmp-rename-fsync pattern, ensuring durability even if the agent crashes mid-operation. As implemented in [`crates/ai-memory-wiki/src/lib.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-wiki/src/lib.rs), this guarantees that the filesystem state remains consistent regardless of external failures.

## SQLite Index: Multi-Modal Retrieval at Scale

While the markdown wiki serves as the authoritative store, ai-memory maintains a companion SQLite database at `<data_dir>/db/memory.sqlite` for fast, structured queries. This dual-storage approach separates durability concerns from performance optimization.

### Core Index Structures

The database contains four specialized tables working in concert:

| Table | Purpose |
|-------|---------|
| `pages_fts` | FTS5 full-text index spanning page titles and bodies |
| `entities` | Lexical entity extraction for concept-based matching |
| `links` | Wikilink graph for relationship-aware navigation |
| `page_embeddings` | Optional vector embeddings for semantic similarity |

### Hybrid Search with RRF Ranking

The `memory_query` MCP tool executes a **Reciprocal Rank Fusion (RRF)** search combining three signals:

1. **FTS5 text matches** for keyword relevance
2. **Entity matches** for concept alignment
3. **Link neighborhood** for relational proximity

An optional LLM reranker can further refine results for higher-quality retrieval. This multi-tiered approach ensures agents find relevant knowledge whether they search by exact terminology, related concepts, or contextual relationships.

The decay math and access-counter tracking live in [`crates/ai-memory-store/src/lib.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-store/src/lib.rs), which also implements the single-writer SQLite actor pattern for safe concurrent access.

## Lifecycle Hooks: Continuous Knowledge Capture

ai-memory doesn't rely on agents to manually save state. Instead, it exposes a **fire-and-forget hook system** at `/hook` that captures agent activity automatically.

### Event Vocabulary and Routing

Agents emit standardized lifecycle events:

- `session-start` — Initializes context for a new working session
- `post-tool-use` — Records tool invocations and outcomes
- `session-end` — Triggers automatic summarization

The hook router sanitizes all payloads and assigns an `ObservationKind` before queuing writes to the SQLite actor. As documented in the architecture, the sanitizer serves as the **sole trust boundary** for untrusted text, ensuring agents cannot corrupt the memory store through malformed input.

### Auto-Improvement and Consolidation

When sessions terminate, the auto-improve scheduler (implemented in [`crates/ai-memory-consolidate/src/lib.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-consolidate/src/lib.rs)) performs several LLM-driven operations:

- **Synthesizes summary pages** from session activity
- **Rewrites existing pages** for clarity and completeness
- **Extracts structured concepts** into decisions, gotchas, and procedures
- **Boosts salience** based on agent feedback via `memory_feedback`

This pipeline transforms raw observational data into curated, reusable knowledge without requiring manual agent intervention.

## Memory Tiers and Decay Formulas

Not all memories deserve equal priority. ai-memory implements a **tiered retention system** that blends multiple time horizons:

- **Working session** — Immediate, high-priority context
- **Epodic (30→180 days)** — Recent but decaying relevance
- **Semantic (indefinite)** — Evergreen conceptual knowledge
- **Procedural** — How-to knowledge with usage-based boosting

Decay formulas and access counters determine retrieval ranking, ensuring agents surface timely information while preserving critical long-term knowledge. This balances **recency bias** against **importance accumulation** in a principled, configurable manner.

## MCP Tool Surface: 18 Built-In Operations

Agents interact with ai-memory through a standardized Model Context Protocol (MCP) interface. The complete tool surface exposes 18 operations for querying, reading, writing, and managing knowledge.

### Essential Agent Workflows

```rust
// Query long-term memory for relevant pages
let result = memory_query::call(memory_query::Params {
    q: "rust async file watcher".into(),
    n: Some(5),
    ..Default::default()
})?;

// Fetch full content when snippets are 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()
})?;

// Provide feedback to improve future retrieval ranking
memory_feedback::call(memory_feedback::Params {
    path: "concepts/async_file_watcher.md".into(),
    kind: FeedbackKind::Helpful,
    ..Default::default()
})?;

```

These calls map directly to handler implementations in [`crates/ai-memory-mcp/src/server.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-mcp/src/server.rs), which translates MCP requests into core library operations.

## Safety, Persistence, and Multi-Agent Collaboration

The architectural decisions in ai-memory prioritize **operational safety** alongside functionality:

- **Atomic file writes** (tmp + rename + fsync) prevent corruption
- **Single-writer SQLite actor** eliminates race conditions
- **Audit logging** of all mutations for accountability
- **Git-native storage** enables branching, merging, and collaborative workflows

Because knowledge lives in plain files and standard SQLite, agents can share memory across CLI runs, IDE sessions, and even distinct tool implementations. Switch from one ai-memory-aware agent to another in the same repository—the wiki remains unchanged and the index instantly reusable.

## Key Source Files and Their Roles

| File | Responsibility |
|------|--------------|
| [`crates/ai-memory-core/src/page.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-core/src/page.rs) | Page data model—the atomic memory unit |
| [`crates/ai-memory-wiki/src/lib.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-wiki/src/lib.rs) | Atomic writes, file watching, git integration |
| [`crates/ai-memory-store/src/lib.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-store/src/lib.rs) | SQLite operations, FTS5, decay mathematics |
| [`crates/ai-memory-mcp/src/server.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-mcp/src/server.rs) | MCP protocol tools and request handling |
| [`crates/ai-memory-consolidate/src/lib.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-consolidate/src/lib.rs) | LLM-driven consolidation pipeline |
| [`docs/ARCHITECTURE.md`](https://github.com/akitaonrails/ai-memory/blob/main/docs/ARCHITECTURE.md) | Comprehensive system design documentation |

## Summary

- **ai-memory** combines markdown wiki storage, SQLite indexing, and lifecycle hooks to give AI coding agents durable, queryable long-term memory
- **Supersession versioning** preserves complete edit history without sacrificing current-state performance
- **Hybrid RRF search** merges FTS5 text, entity, and link-graph signals for robust knowledge retrieval
- **Auto-improvement pipeline** automatically distills session activity into structured, reusable knowledge
- **Tiered decay system** balances recency and importance for intelligent prioritization
- **MCP tool surface** provides 18 standardized operations for agent integration

## Frequently Asked Questions

### How does ai-memory differ from simple vector databases for agent memory?

ai-memory treats the markdown wiki as the source of truth rather than embeddings alone. Vector storage in `page_embeddings` is optional and complementary, not primary. The system preserves complete human-readable history through supersession chains, supports structured relationships via wikilinks, and implements explicit lifecycle management—capabilities that pure vector databases typically lack.

### Can multiple agents share the same ai-memory instance?

Yes. The SQLite-backed index and file-based wiki enable concurrent read access across agents. The single-writer actor pattern in [`crates/ai-memory-store/src/lib.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-store/src/lib.rs) serializes writes safely, while git integration supports branching workflows for experimental agent behaviors. All agents in the same repository see consistent, immediately updated knowledge.

### What happens if the ai-memory server crashes during a write?

The atomic write protocol in [`crates/ai-memory-wiki/src/lib.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-wiki/src/lib.rs) uses tmp-rename-fsync semantics: content writes to a temporary file, gets synced to disk, then renamed to the final path. This guarantees that the filesystem never contains partially written pages. The SQLite actor similarly batches and confirms transactions before acknowledging hook events.

### How does the auto-improve consolidation step decide what to change?

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) uses LLM prompts guided by access patterns, feedback signals from `memory_feedback`, and explicit salience metrics. It prioritizes frequently accessed but poorly structured content, extracts recurring themes into concept pages, and elevates procedural knowledge that agents repeatedly need.