tigerless-labs/agent-memory

agent-memory gives AI agents a persistent memory that survives from one session to the next. Instead of an agent forgetting everything it learned when a session ends, this system stores memories as plain Markdown files, indexes them for fast search, and lets the agent retrieve exactly what it needs at whatever level of detail is appropriate.

The core idea

Most AI assistants (like Claude Code, Codex, or Muse) forget everything when a session closes. Agent-memory fixes that by keeping a store of memories on disk. Markdown files are the single source of truth — the agent can read them directly with tools like ls and grep. An index (SQLite) sits next to those files purely as a cache, so you can delete the index and rebuild it without losing any actual memory.

How retrieval works

Instead of pasting a big blob of text into the agent's context, agent-memory returns a short list of paths to relevant Markdown files. Each hit includes a one-line abstract and a score. The agent then opens the file at the depth it wants: just the abstract, only headings, the full body, or even the raw source messages that led to that memory. This way, the agent only pays for what it actually needs.

Key features

• Three ways to find memories – a deterministic MEMORY.md injected at session start, a ranked BM25 search (with optional vector search), and the plain file system itself. If one method misses, another will catch it.
• Write coverage is automatic – the system takes care of saving memories at natural boundaries (like when a session ends), so the agent doesn't have to remember to do it. A full copy of the session is archived first, so nothing is ever lost even if the distiller misses something.
• Files are the truth, indexes are just caches – you can wipe .index/ and rebuild it (mem rebuild) without losing any knowledge. This is enforced by a test, not just promised.
• An independent “Manage” layer – during idle time (like overnight) the system consolidates, updates, and proposes deletions, but deletions only happen if you confirm them. It also supports time-traveled recall (what did I know as of last Tuesday?).
• No API keys, no LLM calls inside the library – judgement comes from the host agent's own CLI, so every write is visible in the transcript and there's no billing surface.

The store layout

Everything lives in one directory (default ~/agent-memory-store). It contains:

• MEMORY.md – root index with one line per memory
• config.toml – all tunables
• decision/ – actual memory files, one per memory, organized by type and group
• archive/ – append-only copies of raw sessions and provenance evidence
• .index/ – rebuildable search index and access log
• .state/ – runtime bookkeeping (like write locks and distillation watermarks)

Getting started

Requires Python 3.12+ and uv. Install from a checkout:

git clone https://github.com/tigerless-labs/agent-memory.git
cd agent-memory
uv sync --all-packages

Then initialize a store and write your first memory:

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

You can also connect it to Claude Code, Codex, or Muse with a one-liner:

mem setup --host claude-code

Does it work?

The README includes a benchmark on LongMemEval‑S (a standard memory evaluation). With a bounded haystack, agent-memory got 52.9% pooled accuracy versus 35.8% for MemCore and 5.8% with no memory. It also passes cross-host tests: memories written by one host (e.g., Claude Code) are found by another (e.g., Codex) with specific details intact.

A note on honesty

The benchmark numbers are not directly comparable to published LongMemEval scores because the test setup uses a smaller haystack – it’s a write strategy study rather than a scale study. The project also ships its full experiment protocol and raw data in the repository, so you can check the results yourself.

In short: agent-memory makes AI agents remember things across sessions, using plain files you own, without needing a cloud service or API keys.