DOCSEARCHbyAlgolia
Submit Docs

AgentMemory

repository·main·Indexed 12 days ago

https://github.com/rohitg00/agentmemory

Persistent memory for AI coding agents, powered by iii-engine's three primitives. It allows agents like Claude Code, GitHub Copilot CLI, Cursor, and MCP clients to remember context without repetitive explanations. Version 0.9.29 provides a REST API for remembering and searching memories, a built-in viewer, and deployment options for Coolify, Fly.io, and Railway.

Tokens
101.9K
Snippets
272
Records
455
Agent score
96%

What's inside AgentMemory

  1. Overview of agentmemory-evals benchmarks

    main

    The agentmemory-evals package provides public benchmarks to measure the performance of the agentmemory hybrid memory stack (BM25, embeddings, consolidation, and graph retrieval).

    It includes two primary benchmark families:

    • LongMemEval: A public benchmark consisting of 500 questions designed for retrieval testing over multi-session chats.
    • coding-agent-life-v1: An in-house corpus of 15 fictional Claude Code sessions for a Rust CLI project (shipctl), featuring 15 hand-graded queries covering bug fixes, refactors, preferences, and multi-session causal reasoning.

  2. Overview of agentmemory

    main

    agentmemory provides persistent memory for AI coding agents, allowing them to remember context and avoid repetitive explanations. It is built on the iii engine and is designed to work with various AI tools including Claude Code, Cursor, Gemini CLI, Codex CLI, Hermes, OpenClaw, pi, OpenCode, and any MCP (Model Context Protocol) client.

    Key features include:

    • High Retrieval Accuracy: 95.2% retrieval R@5.
    • Token Efficiency: Reduces token usage by approximately 92%.
    • Extensive Tooling: Provides 53 MCP tools and 12 auto hooks.
    • Zero External Dependencies: Requires 0 external databases.

  3. Explore iii console features

    main

    The iii console provides several pages for managing and observing agentmemory:

    PagePurpose
    WorkersView connected workers and real-time metrics (PID, function counts, runtime, last online time).
    FunctionsCall any agentmemory function (e.g., memory.recall, memory.consolidate, graph.query) directly via JSON payloads.
    TriggersReplay HTTP, cron, event, and state triggers manually.
    StatesA full CRUD KV browser for sessions, memory slots, lifecycle timers, and embedding indices.
    StreamsReal-time WebSocket monitor for memory writes, hook events, and observability updates.
    QueuesManage persistent queue topics and dead-letter queues (e.g., for embedding/compression jobs).
    TracesOpenTelemetry waterfall/flame/service decomposition views. Filter by trace_id.
    LogsStructured OTEL logs, filterable by trace/span ID.
    ConfigView runtime settings, including active workers, providers, and ports.
    Flow(Experimental, --enable-flow) Interactive architecture diagram of workers, triggers, and streams.

  4. Use the agentmemory REST API

    main
    The agentmemory HTTP REST API is the primary protocol for interacting with the memory server. It serves as the foundation for the MCP (Model Context Protocol) bridge and is used when calling agentmemory over HTTP, when MCP is unavailable, or when integrating a host that does not support MCP. All endpoints are prefixed with http://localhost:3111/agentmemory/*.

  5. Capabilities of the agentmemory pi extension

    main

    The agentmemory extension for pi provides the following tools and lifecycle hooks:

    Tools

    • memory_health: Confirms the shared memory server is reachable.
    • memory_search: Searches prior decisions, bugs, workflows, and preferences.
    • memory_save: Writes durable facts back to long-term memory.

    Commands & Lifecycle Hooks

    • /agentmemory-status: Checks the health of the connection from inside pi.
    • before_agent_start recall: Automatically injects relevant memories into the prompt before the agent starts.
    • agent_end capture: Automatically saves completed conversation turns back to agentmemory.

    Note: This extension uses pi's native extension API rather than MCP, allowing it to hook directly into the agent lifecycle.

  6. Understand the agentmemory roadmap and development themes

    main

    The ROADMAP.md file serves as the source of truth for the project's direction. The project follows quarterly themes to guide development:

    • Q2 2026 — Depth: Focuses on multimodal memory, increasing connectors, and closing the v0.9 backlog.
    • Q3 2026 — Breadth: Focuses on hook parity across agents, community expansion, and OpenSSF best-practices.
    • Q4 2026 — Trust: Focuses on enterprise features like SSO, audit export, RBAC, and long-running deployment guides.
    • Q1 2027 — v1.0: Focuses on stability, LTS branches, and freezing the REST + MCP surface.

    Status indicators used in the roadmap:

    • Shipped: Landed in main and tagged in a release.
    • Active: In-flight with an open PR or issue owner.
    • Planned: Accepted scope for the quarter, not yet started.
    • Candidate: Under consideration, may be deferred.

  7. Overview of agentmemory MCP tool families

    main

    Agentmemory exposes its full capability set through several functional tool families. Use these categories to identify the right tool for your agent's task:

    • Capture: For ingesting data (memory_save, memory_observe flows, memory_compress_file).
    • Retrieve: For finding information (memory_smart_search, memory_recall, memory_file_history, memory_timeline, memory_vision_search).
    • Sessions and commits: For managing session state and history (memory_sessions, memory_commits, memory_commit_lookup).
    • Knowledge and graph: For structured reasoning and relationship mapping (memory_lesson_save, memory_lesson_recall, memory_graph_query, memory_relations, memory_patterns, memory_crystallize).
    • Structured slots: For managing specific data slots (memory_slot_create, memory_slot_append, memory_slot_get, memory_slot_list, memory_slot_replace, memory_slot_delete).
    • Governance and health: For system maintenance and auditing (memory_governance_delete, memory_audit, memory_verify, memory_heal, memory_diagnose).

  8. Choose the right tool for your agent's question types

    main

    When building an agent, route questions to the specific tool that handles that question class best:

    Question shapeBest tool
    "What's the architecture of this repo?"Understand-Anything dashboard or Graphify graph.html
    "Where is symbol X defined? Who calls it?"codegraph (codegraph_node, codegraph_callers)
    "What does this PDF spec say about the rate limit?"Graphify
    "Why did we pick X over Y three sessions ago?"agentmemory (memory_smart_search)
    "What did we ship on April 8?"agentmemory (memory_timeline)
    "How does the payment flow work in this codebase?"Understand-Anything (/understand-chat)
    "Trace impact of changing Foo::bar"codegraph (codegraph_impact) or Understand-Anything (/understand-diff)
    "What preferences has the team locked in?"agentmemory

  9. How the Sibling-repo guard works

    main

    The handoff mechanism includes a boundary check to prevent sessions from one project being incorrectly matched to a sibling repository.

    A session is only considered a match for the current project cwd if the session's cwd:

    1. Exactly equals the current cwd.
    2. Starts with the current cwd followed by a path separator (e.g., /Users/dev/repo-a/).

    If a session's cwd (e.g., /Users/dev/repo-a-staging) matches a prefix but fails the boundary check against the current project (e.g., /Users/dev/repo-a), the system will reject it and instead pick the real matching session or fall back to the most recent session overall.

  10. Implement directory-boundary checks for session matching

    main

    When implementing session resumption (like the handoff skill), avoid using simple prefix matching (e.g., session.cwd.startsWith(projectPath)), as this can incorrectly match sibling repositories (e.g., matching /repo-a-staging when the project is /repo-a).

    Instead, use a directory-boundary check to ensure the match respects folder structures:

    // RIGHT: Ensures the match is the exact directory or a true subdirectory
session.cwd === projectPath || session.cwd.startsWith(projectPath + sep)

  11. How the agentmemory memory pipeline works

    main

    Agentmemory uses a multi-stage pipeline to capture, compress, and index observations from agent tool usage.

    1. Capture (Hooks)

    Various hooks trigger memory actions:

    • SessionStart: Loads project profile (concepts, files, patterns).
    • UserPromptSubmit: Captures user prompts (after privacy filtering).
    • PreToolUse: Captures file access patterns and context enrichment.
    • PostToolUse: Captures tool name, input, and output.
    • PostToolUseFailure: Captures error context.
    • Stop / SessionEnd: Triggers session summarization and knowledge graph extraction (if GRAPH_EXTRACTION_ENABLED=true).

    2. Processing Pipeline

    When a PostToolUse hook fires:

    1. Deduplication: SHA-256 dedup within a 5-minute window.
    2. Privacy Filter: Strips secrets and API keys.
    3. Storage: Stores the raw observation.
    4. Compression: An LLM compresses observations into structured facts, concepts, and narratives.
    5. Embedding: Generates vector embeddings (via 6 providers or local).
    6. Indexing: Indexes data in both BM25 and vector stores.

    3. Retrieval (Triple-Stream Search)

    Search uses Reciprocal Rank Fusion (RRF, k=60) to combine three streams:

    • BM25: Keyword matching with stemming and synonym expansion.
    • Vector: Dense embedding cosine similarity.
    • Graph: Knowledge graph exploration via entity matching.

    To optimize retrieval for CJK (Chinese, Japanese, Korean) languages, install a segmenter to enable word-level tokenization:

    npm install @node-rs/jieba tiny-segmenter
    npm install @node-rs/jieba tiny-segmenter

  12. Understand @agentmemory/fs-watcher defaults and behavior

    main

    Ignored Patterns

    By default, the following patterns are ignored: .git/, node_modules/, dist/, build/, .next/, .turbo/, coverage/, .DS_Store, *.log, *.lock. You can extend this list using AGENTMEMORY_FS_WATCH_IGNORE.

    File Content Handling

    • Text Files: Common source, config, and docs extensions (e.g., .ts, .js, .py, .go, .rs, .md, .yaml) are read for a 4 KB preview.
    • Unknown Extensions: Recorded as a path-only observation without content.
    • Binary Files: Ignored by default.

    Operational Details

    • Debouncing: Writes are debounced by 500 ms per path to prevent flooding the server during rapid editor saves.
    • Session/Project Identity: If AGENTMEMORY_SESSION_ID and AGENTMEMORY_PROJECT are not provided via environment variables, the watcher generates a per-process session ID (fs-watcher-<ts>-<rand>) and uses the first watched directory's name as the project.
    • One-way Integration: This connector is strictly one-way; it writes observations to the server and does not read from the agentmemory store.