DOCSEARCHbyAlgolia
Submit Docs

ai-memory

repository·main·Indexed 21 days ago

https://github.com/akitaonrails/ai-memory

A long-term memory system for AI coding agents that uses a plain-markdown git-based wiki to maintain context across sessions and tools. It includes the ai-memory-importer for importing external corpora like OMC wikis, an auto-improvement evaluation system for custom scorers, and the ai-memory-eval harness for A/B testing LLM providers on consolidation prompt quality.

Tokens
156.2K
Snippets
375
Records
690
Agent score
70%

What's inside ai-memory

  1. Overview of ai-memory

    main

    ai-memory provides long-term memory for AI coding agents. It solves the problem of context loss when an LLM session ends by creating a shared, persistent wiki compiled from sanitized lifecycle observations.

    Key characteristics:

    • Persistent Wiki: The memory is stored as plain markdown in a git repository, making it grep-able, compatible with tools like Obsidian, and easy to back up with rsync.
    • No Infrastructure Overhead: It does not require a vector database or manual write_note ceremonies.
    • Seamless Handoffs: When a session ends, relevant observations are summarized into a coherent handoff that the next agent can consume.
    • Cross-Harness Continuity: Using ai-memory run allows for higher-fidelity continuity when switching between different coding agents (e.g., moving from Claude Code to OpenAI Codex).

  2. Overview of ai-memory-importer

    main

    The ai-memory-importer is a standalone companion tool designed to import external memory corpora into a running ai-memory server. It is isolated from the main workspace and uses only crates.io dependencies.

    Currently, the primary supported source is the OMC wiki directory (oh-my-claudecode), which reads top-level *.md files. By default, it skips index.md and session-log-* files, mapping the remaining content to deterministic destination paths under omc/<slug>.md.

  3. What is ai-memory and its core purpose

    main

    ai-memory is a Rust-based system designed to provide long-term, shared memory for coding agents (such as those in the Support Matrix) and other MCP-capable clients. It enables seamless continuity across different CLI sessions: you can quit one task mid-way and resume in a different tool within the same directory without manual note-taking or copy-pasting summaries.

    Instead of a traditional database, it builds a Karpathy-style LLM wiki: a git-versioned tree of markdown files on disk. This wiki is 'compiled' over time through appending and supersession. While the markdown files serve as the source of truth, a companion SQLite index provides retrieval capabilities via FTS5, lexical entity matching, and link-neighbor analysis, with optional vector support.

  5. How ai-memory interacts with Architecture Decision Records (ADRs)

    main

    ai-memory operates with a strict separation between your repository files and its own internal wiki.

    1. Repository Files: ai-memory never touches files in your repository. If you maintain a docs/adr/ directory in your repo using external tools (like joshrotenberg/adrs), ai-memory will not modify them. You can run ADR tools and ai-memory side-by-side: the ADR tool manages the canonical log in your repo, while ai-memory manages cross-session recall in its wiki.

    2. Wiki-based ADRs: For decisions recorded directly within the ai-memory wiki, use the managed durable-pages Agent Skill. This skill follows a specific recipe to ensure high-quality retrieval via memory_query:

      • Path: decisions/<slug>.md
      • Structure: Status / Context / Decision / Consequences (including rejected alternatives).
      • Immutability: Set pinned: true in the page metadata.
      • Versioning: Use a supersede-by-new-page pattern instead of editing historical pages.

    To record a decision, simply ask an agent to "record this as an architectural decision."

  6. Understand the Basic Memory storage model

    main

    Basic Memory uses a local-first, Markdown-on-disk model where Markdown files are the single source of truth. A SQLite or Postgres database acts as a derived index to enable fast searching and knowledge graph traversal.

    Data Primitives

    • Entity: Represented by a single Markdown file with YAML frontmatter. It contains metadata like title, note_type, permalink, and tags.
    • Observation: Semantic snippets within a note, formatted as - [category] text #tag (context).
    • Relation: Links between entities, formatted as - relation_type [[Other Entity]]. These can be 'unresolved' (where the target entity doesn't exist yet) and are automatically resolved during synchronization.

    Search Capabilities

    Search is a dual-stack system configured via database_backend:

    • SQLite: Uses FTS5 for text search and sqlite-vec for semantic vector embeddings.
    • Postgres: Uses tsvector GIN for text and pgvector for semantic search.
    • Hybrid Search: Combines semantic and text search. Defaults include semantic_vector_k=100 and a similarity threshold of 0.55 using the bge-small-en-v1.5 model.
    ---
title: Coffee Brewing Methods
type: note
permalink: coffee-brewing-methods
tags: [coffee, brewing]
---

  7. Understand the target page structure for durable knowledge

    main

    The auto-improvement loop targets specific directory structures to organize knowledge. When reviewing or creating pages, follow these conventions:

    TargetUse for
    gotchas/<topic>.mdReproducible pitfalls, root causes, and tool quirks requiring a fix.
    decisions/<topic>.mdArchitectural, workflow, or policy choices and their rationale.
    concepts/<topic>.mdStable domain or project architecture knowledge.
    procedures/<topic>.mdReusable, multi-step workflows and operating procedures.
    _rules/<topic>.mdExplicit always/never instructions for future agents.
    _slots/current-focus.mdMutable short-term project state (overwrite, don't append).
    notes/<topic>.mdUseful facts that don't fit other categories.
    _pending/auto-improve/<id>.mdStaged, human-reviewable proposals (not durable truth).

    Warning: Do not create new session pages from the auto-improvement loop; session pages are handled by session-end consolidation.

  8. The Three-Layer Architecture of an LLM Wiki

    main

    A faithful implementation of the LLM Wiki pattern uses a three-layer architecture to separate raw data from synthesized knowledge:

    1. Raw Sources: Immutable files that the LLM reads but never modifies.
    2. Wiki: A collection of markdown files that the LLM owns and maintains entirely. This is the structured, interlinked knowledge base.
    3. Schema: Convention files (such as CLAUDE.md or AGENTS.md) that define the rules and discipline for the LLM to act as a wiki maintainer.

    This architecture ensures that the 'source of truth' remains intact while the 'knowledge artifact' evolves.

  9. Implement a Capability-flag-driven Storage Facade

    main
    Instead of using scattered conditional logic to handle different database types, use a unified facade that checks for specific capabilities. For example, using a method like UnifiedStoreEngine.has_capability(HYBRID_WRITE) allows the same pipeline to target different backends (e.g., Kuzu, LanceDB, or a fused Postgres+pgvector) seamlessly.

  10. How Cross-Agent Handoffs Work

    main

    Cross-agent handoff requires both the Ending Side and the Starting Side to be configured correctly.

    1. The Ending Side

    The agent must signal the end of a session.

    • Automatic: Supported by Claude Code, Devin CLI, Cursor, Gemini CLI, Grok Build CLI, Zero, Kimi Code, OpenClaw, OpenCode, and OMP.
    • Manual: For agents like Codex or Antigravity CLI (which don't have reliable session-end events), you must run:
      • ai-memory finalize-session (defaults to Codex)
      • ai-memory finalize-session --agent antigravity-cli

    2. The Starting Side

    The agent must receive the handoff data.

    • Automatic (Context Injection): Supported by Claude Code, Codex, Devin CLI, Cursor, Gemini CLI, Antigravity CLI, Kimi Code, OpenClaw, OpenCode, and OMP. These clients consume startup-hook stdout or equivalent to inject context.
    • Manual (Proactive Call): For Grok and Zero (which discard SessionStart stdout), the model must proactively call the memory_handoff_accept tool on its first turn.
    ClientAutomatic Handoff?Method
    Claude CodeYesSessionEnd hook
    CursorYessessionStart hook
    CodexNoManual finalize-session required
    GrokNoMust call memory_handoff_accept
    OMPYesTypeScript extension

  11. How managed skill markers protect user files

    main

    Every ai-memory-managed SKILL.md file contains an ownership marker:

    <!-- ai-memory-managed: routing-skill -->

    To prevent accidental overwriting of user-authored skills, installers and uninstallers must only overwrite or remove files that contain this exact marker. If a file with the same name exists but lacks this marker, the process should skip it and provide an actionable message to the user. The only exception is if the user provides an explicit force option.

  12. How ai-memory manages storage and durability

    main

    ai-memory ensures data integrity and prevents corruption by using a single-writer model. It utilizes SQLite in WAL (Write-Ahead Logging) mode with foreign keys and migrations.

    Key durability features include:

    • Single Writer Thread: All mutations are serialized through a single WriterHandle to prevent parallel SQLite deadlocks.
    • Atomic Page Writes: Operations like Wiki::write_page or Wiki::apply_batch update both the store rows and FTS (Full-Text Search) triggers simultaneously.
    • Avoidance of Multi-Store Complexity: Unlike other systems that use uncoordinated vector/relational stores, ai-memory keeps the substrate simple to avoid index corruption.