tigerless-labs/agent-memory

What it is

agent‑memory is a lightweight, file‑based long‑term memory system that AI agents (Claude Code, Codex CLI, Muse Code, etc.) can read from and write to without needing any API keys or external services. Each “memory” is a single Markdown file stored in a directory tree; an SQLite/FTS5 cache indexes those files for fast BM25 or optional vector search. The system automatically records writes at conversation boundaries, consolidates them on a background “sleep” pass, and keeps a full audit trail so that past states can be queried (recall --as‑of).

---

Core ideas

Idea	Why it matters
Filesystem as source of truth	Memories are plain Markdown files – you can ls, grep, version‑control them, and delete the index without losing data.
Three‑track retrieval	1️⃣ Plain directory walk (fallback) 2️⃣ BM25 over an FTS5 SQLite index 3️⃣ Optional dense‑vector search (FastEmbed) – the system picks the best candidates and can fuse results.
Write‑coverage handled by the runtime	Agents only need to call mem record …; the library guarantees the memory is persisted and later indexed, even if the agent forgets.
Time‑based consolidation	A “sleep” step runs on its own clock, merges duplicate entries, proposes deletions, and writes a dream‑report describing what changed.
No embedded LLM client	All reasoning about what to write or delete is delegated to the host agent’s own CLI, so there are zero API‑key requirements and no billing surface.

---

How you use it

# install (requires Python 3.12+ and uv)
git clone https://github.com/tigerless-labs/agent-memory.git
cd agent-memory
uv sync --all-packages   # builds the `mem` CLI
export PATH="$PWD/.venv/bin:$PATH"

# initialise a store (defaults to ~/agent-memory-store)
mem init

# record a memory
mem record \
  --type decision \
  --field project=agent-memory \
  --abstract "Markdown files are the single source of truth" \
  --body "Indexes are rebuildable caches."

# retrieve candidates (L0 list only)
mem recall "single source of truth"

# read a hit at the desired depth
mem read 2024-10-08-why-files.md --level outline   # headings only
mem read 2024-10-08-why-files.md --level full      # whole file

# run the background consolidation
mem sleep --reason host
mem proposals               # see pending changes
mem decide <id> --accept    # apply a proposal

---

Integration with agents

• mem setup --host <host> registers the store with a specific agent host (Claude Code, Codex CLI, Muse Code, etc.). The command installs lifecycle hooks that automatically inject MEMORY.md at session start, record writes at session end, and run the sleep‑pass.
• For hosts that speak the MCP protocol you can add --mcp so the agent can call memory functions (memory_recall, memory_record, …) via a local MCP server instead of the CLI.
• The same store can be shared across multiple hosts – a write made by Claude Code is instantly searchable by Codex CLI.

---

Optional vector search

# install the extra vector dependencies
uv sync --extra vector   # or pip install agent-memory-core[vector]
# enable in the store config
echo "vector_enabled = true" >> $AGENT_MEMORY_STORE/config.toml
mem rebuild               # rebuild the SQLite cache with vectors

Vector recall is fused with BM25 using reciprocal‑rank fusion; it improves recall at the cost of higher latency (≈5 ms → 140 ms on the authors’ benchmark).

---

Evaluation snapshot

The authors evaluated the system on the LongMemEval‑S benchmark (120 episodes, bounded haystack). Results:

• agent‑memory achieved 52.9 % pooled accuracy (127/240) – a statistically significant improvement over the prior MemCore baseline (35.8 %).
• Adding vector fusion raised Recall@5 from 79 % to 86.6 % but did not change end‑to‑end answer accuracy.
• The system works across three hosts (Claude Code, Codex CLI, Muse Code) with a net contribution of 13 % over a “no memory” condition.

---

Who might find it useful?

• Researchers building multi‑step agent pipelines who need a reproducible, version‑controlled memory that survives agent restarts.
• Developers of autonomous coding assistants who want a zero‑cost, local knowledge base that can be queried with plain shell commands.
• Experimenters who need a deterministic audit trail (the dream‑reports and trace commands) for reproducibility.

---

Quick checklist

✅	Feature
✅	Plain‑text Markdown memories (git‑able, grep‑able)
✅	SQLite + FTS5 BM25 index (zero‑API)
✅	Optional dense‑vector index (FastEmbed)
✅	Automatic write consolidation (“sleep”)
✅	Time‑travel recall (--as-of)
✅	Multi‑host support (Claude Code, Codex CLI, Muse Code)
✅	MCP server for tool‑calling agents
✅	Full provenance (trace) and audit logs
✅	No external API keys required

---

Where to go next?

• Try the inter‑host interoperability demo: mem‑exp interop … as described in the README.
• Explore the optional vector path if you need higher recall on larger corpora.
• Contribute a new host integration or improve the sleep‑consolidation policies – the project is at version 0.1.0 and welcomes extensions.

---

Bottom line: agent‑memory gives you a deterministic, file‑centric long‑term memory that agents can read and write without any cloud dependencies, while still offering fast BM25 or optional vector retrieval and a full audit trail.