Skip to content

Home

Jump to bottom
Rick Hightower edited this page Feb 2, 2026 · 3 revisions

Agent Memory Wiki

Welcome to the Agent Memory documentation wiki.

Agent Memory is a local, append-only conversational memory system for AI coding agents (Claude Code, OpenCode, Gemini CLI, GitHub Copilot CLI). It enables agents to answer questions like "what were we talking about last week?" without scanning through entire conversation histories.

Core Value

Agentic search through Progressive Disclosure Architecture (PDA). Instead of brute-force scanning thousands of events, agents navigate a time-based Table of Contents hierarchy, reading summaries at each level until they find what they need.

Quick Navigation

Getting Started

  • README - Project overview and quick start guide
  • Usage Guide - Starting the daemon, CLI commands, troubleshooting
  • Architecture - Component overview, crate structure, data flow

API & Integration

Project Planning (GSD)

  • Project Overview - Core value, requirements, constraints, key decisions
  • Roadmap - 13-phase development plan with detailed success criteria
  • Current State - Active phase, velocity metrics, accumulated context
  • Requirements - v1/v2 requirements with traceability matrix
  • Milestones - Milestone history and completion records

Phase Documentation

v1.0 Phases (Complete)

Phase Title Description
Phase 1 Foundation Storage layer, domain types, gRPC scaffolding, daemon binary
Phase 2 TOC Building Segmentation, summarization, time hierarchy construction
Phase 3 Grips & Provenance Excerpt storage, summary-to-grip linking, expand capability
Phase 5 Integration Hook handler connection, query CLI, admin commands
Phase 6 End-to-End Demo Full workflow validation from ingestion to query

v1.5 Phases (Complete)

Phase Title Description
Phase 7 CCH Integration Initial hook integration planning
Phase 8 CCH Hook Integration Automatic event capture via CCH hooks
Phase 9 Setup & Installer Plugin Interactive setup wizard plugin with commands
Phase 10 Background Scheduler In-process Tokio cron scheduler for TOC rollups

v2.0 Phases (Complete)

Phase Title Description
Phase 10.5 Agentic TOC Search Index-free term matching via SearchNode/SearchChildren
Phase 11 BM25 Teleport (Tantivy) Full-text search index for keyword-based teleportation
Phase 12 Vector Teleport (HNSW) Semantic similarity search via local HNSW
Phase 13 Outbox Index Ingestion Event-driven index updates for rebuildable indexes
Phase 14 Topic Graph Memory HDBSCAN clustering, LLM labeling, importance scoring

v2.1 Phases (Planned)

Phase Title Description
Phase 15 Configuration Wizard Skills AskUserQuestion-based interactive config wizards

Architecture Overview

                        AI Agent (Claude Code, etc.)
                                    |
                                    | gRPC
                                    v
+---------------------------------------------------------------+
|                        Memory Daemon                           |
|  +-------------+  +-------------+  +-----------------------+   |
|  | Ingestion   |  |   Query     |  |   Scheduler           |   |
|  | Service     |  |   Service   |  |   (Background Jobs)   |   |
|  +-------------+  +-------------+  +-----------------------+   |
|                          |                                     |
|  +-----------------------------------------------------+       |
|  |              Search Layer                           |       |
|  |  +----------------+  +---------------------------+  |       |
|  |  | BM25 (Tantivy) |  | Vector HNSW (usearch)     |  |       |
|  +-----------------------------------------------------+       |
|  +-----------------------------------------------------+       |
|  |              Topic Graph Layer                      |       |
|  |  +----------------+  +---------------------------+  |       |
|  |  | HDBSCAN        |  | LLM Labels & Importance   |  |       |
|  +-----------------------------------------------------+       |
|  +-----------------------------------------------------+       |
|  |                 Storage Layer (RocksDB)             |       |
|  |  +--------+ +----------+ +-------+ +------------+   |       |
|  |  | Events | | TOC Nodes| | Grips | | Topics     |   |       |
|  +-----------------------------------------------------+       |
+---------------------------------------------------------------+

Key Concepts

Table of Contents (TOC)

Time-based hierarchy for navigating conversations:

  • Year - Annual summary with major themes
  • Month - Monthly summary with focus areas
  • Week - Weekly summary with specific topics
  • Day - Daily summary with conversation segments
  • Segment - Individual conversation chunk with grips

Grips (Provenance)

Anchors linking summary bullets to source evidence:

  • Contains excerpt text from original conversation
  • Links to start/end event IDs for verification
  • Enables drill-down from summary to raw events

Progressive Disclosure

Agents navigate the TOC hierarchy level by level:

  1. Read summary at current level
  2. Decide: drill down, move laterally, or expand grip
  3. Only access raw events when verification needed

Technology Stack

Component Technology
Language Rust
Storage RocksDB
API gRPC (tonic)
Summarizer Pluggable (API or local LLM)
BM25 Search Tantivy (full-text indexing)
Vector Search usearch HNSW + Candle (all-MiniLM-L6-v2)
Topic Clustering HDBSCAN (density-based)
Scheduler tokio-cron-scheduler

Quick Links

Last updated: 2026-02-02

Clone this wiki locally