agent-memory

A long-term memory runtime for AI agents whose knowledge lives in plain Markdown files, with every index beside them treated as a cache that can be thrown away: rm -rf .index/ && mem rebuild is enforced by a test to lose zero knowledge. One memory is one file, carrying a stable name, a one-sentence abstract, a type with schema fields, timestamps, links, weight and provenance, and a validity interval instead of a status field, so a replaced file stays in the store and recall --as-of can still answer from it. Retrieval is local and ranked — BM25 over an FTS5 index by default, an optional vector index fused in by reciprocal rank — and it answers with paths rather than pasted text: recall returns a one-line list, and the agent opens a hit only as deep as the task needs. Writes fire at conversation boundaries instead of waiting for the agent, the full trace is copied before distillation, and an independent sleep-time layer consolidates on its own clock and files deletion as a proposal. Claude Code, Codex CLI and Hermes share one store, and no API key is needed.

Who built itAn organization account rather than a person: the repository carries MIT copyright to Tigerless Labs, and eight accounts wrote its 154 commits between 2026-09-01 and 2026-09-28. One member dominates the history — the account liruihan000 accounts for 103 of them, committing under three separate addresses and two display names — with faj-design5260 on 33 and importcpp on 7; the other five accounts have one or two each. Ninety of the 154 commits carry a co-author trailer, and every one of those names a Claude model: Opus 5 on 59, Fable 5.1 on 28, Opus 5.5 on 2 and Fable 5 on 1.

1. 01

   Twenty-nine days, 154 commits, and no release

   The repository was created on 2026-09-01, and its oldest commit — logged four seconds earlier the same evening — is titled “Scaffold repo: CLAUDE.md, design tree, roadmap v0.1”: invariants and a plan tree before any code. All 154 commits fall inside that September, the newest being the merge of pull request 46 on 2026-09-28, with the last push recorded on 2026-09-30. There are no releases and no tags at all, and the README says there is no release on PyPI yet, so installation is from a checkout; the version badge still reads 0.1.0. The month produced attention — 1,974 stars, 124 forks, 66 watchers, ten open issues in the metadata — and a burst of work on the front door. Pull requests 21 to 25 all landed on 2026-09-08 and all of them are README or licence work. One added an install section after noticing that mem setup writes a bare mem-hook command into the host configuration while uv sync only puts that executable inside the virtual environment, so a session started outside it recorded nothing. Another added a section demonstrating the read path in three commands and paid for it by cutting a section whose claims were made elsewhere. The licence change records that the repository had been public with no licence file, which leaves it all rights reserved by default, and adds MIT under Tigerless Labs to the root and all six package manifests.

2. 02

   The file is the atom, and the index is disposable

   The design rules are written down in CLAUDE.md as invariants a change must not break: Markdown is the single source of truth and every index is a rebuildable cache; agent writes and management rewrites share one validate, hash-diff and reindex pipeline; reads never mutate truth, so usage statistics go to an index access log and weight is settled back into frontmatter in batch; raw material is append-only; the library core contains no LLM client; management never destroys information; the file boundary is the invalidation atom; and the read path is held fixed across write experiments. A memory is one file: a name, a one-sentence abstract, a type, timestamps, links, weight and provenance in the frontmatter, free Markdown in the body, and a validity interval of valid_from plus optional invalid_at where a status field used to be. The store holds MEMORY.md, the only resident injection, a configuration file that refuses unknown knobs at load, memories at <type>/<group>/<name>.md, append-only archive directories for provenance and session traces, a rebuildable index, and a state directory holding the distillation watermark and the write lock. Pull request 40 simplified the read and management halves together: the deep raw search path, its index, its configuration keys and its adapter arguments were deleted, and limit became the one way to widen a recall.

3. 03

   Recall answers with paths, and the ranking fights behind that

   Recall does not paste text into a context window. It answers with an L0 list — one-line abstract, file path, anchor and score, eight entries by default — and the agent opens a hit at the depth the task needs: mem read <name> --level outline, or abstract, or full, with mem context doing both in one call and mem trace reaching the cited raw messages. Each rung costs an order of magnitude more than the last, and a long file adds two free rungs: the anchor and an outline computed at read time. Three read tracks sit behind it: deterministic injection of MEMORY.md at session start, BM25 over an FTS5 index with a vector plugin fused in by reciprocal rank, and the plain directory tree that ls and grep can still walk. One change made scope match complete path components, because a scope of user was matching username/settings.md. Another moved the scope filter ahead of the candidate-pool limit: recall used to take the global top matches and then discard the out-of-scope ones, so a narrow scope could return nothing while a matching memory existed. Vector recall arrived as an optional plugin — install the extra, switch it on, BAAI/bge-small-en-v1.5 by default, SQLite with exact cosine search — and measured 79.0% to 86.6% Recall@5 on a fixed 120-query set, against a median retrieval latency rising from 5.1 ms to 139.2 ms; it stayed off by default.

4. 04

   What the sleep-time layer is allowed to do

   Management is an independent layer on its own clock, with authority tiers. T0 is rule-only — dates, weight, links and directories — and applies directly; T1 is decided by the library executor and only creates new files or marks old ones invalid, filing a proposal instead of acting. Each kind of operation is capped per sleep and one sleep is one git commit. A dream report records what moved, what was proposed and the evidence pointers, and a decision ledger holds the verdicts; the repository argues that the ledger is truth rather than cache, because a lost rejection verdict means the operator’s refusal is forgotten and the same proposal returns on the next sleep. Pull request 36 found that ledger append was an unlocked read-modify-write where two concurrent appenders could each write back only their own line, and put it under the store lock with the new content staged into a sibling pending file. Deletion only arrives as a proposal confirmed with mem decide, and physical removal is a human-run command management cannot reach. Reversibility, rate limits and audit are named as what keeps an unattended run safe, because memory poisoning is treated as a persistent attack surface — there is a red-team test file for poisoning payloads. The weight of that layer shows in the code: manage.py at 31 KB and prompts.py at 17 KB are the two largest files in a core package of 212 KB.

5. 05

   A fresh install that recorded nothing, and 340 sessions in three minutes

   The best-written entry is a pull request that fixes several defects found while preparing a demo, each reproduced by a test that failed first. On a fresh install no conversation became a memory and no new session recalled anything: the hook launched mem distill --store …, but the store flag is a top-level argument, so the parser refused the command and the error was discarded. The default reasoning executor was a hosted model on a private project inside the organization, so outsiders got nothing; it became the firing host’s own command-line interface. That host reasoner’s claude -p then fired the same lifecycle hooks and distillation recursed — the pull request records roughly 340 sessions in three minutes — so executor runs now carry an environment variable the hook stands down under. A second entry is a model echoing what it had just been told: the reasoner added a group value restating a schema field, the store refused it as an unknown field, the repair round repeated the mistake, and the conversation sat pending; reconciliation now drops such an echo. The last defect is that the rule-only tier’s token-set fingerprint contributed no tokens for non-ASCII text, so a sleep could invalidate unrelated Chinese memories; the replacement is an exact identity over parsed text, type, semantic fields, validity start, author, links and provenance.

6. 06

   The month the outside fixes arrived

   The record reads thirty issues and pull requests, numbered 21 to 50, seven still open. The Windows port came from outside: core/locking.py imported fcntl at module level, so every entry point — mem, mem-hook and mem-mcp — died with an import error before doing anything; the fix switches on the platform and locks one byte at position zero with the Windows call, catching the plain operating-system error it raises rather than the narrower subclass. Another outside contributor sent a pair about concurrency: a correction that read a record with no lock and then wrote it under a second lock, so a concurrent writer’s edit and provenance could be lost, and a delete path with the same shape. A third filed an issue and a pull request within a minute: frontmatter did not round-trip, because double-quoted values were never un-escaped and every rewrite added a backslash, while strings such as true, null, 42 or 1e3 were written unquoted and read back as another type. The same defect reached two people three weeks apart, and one noticed the other’s pull request had already merged the fix they had written, closed their own and credited the test covering the boundary case. The suite grew with it: 388 passing tests at 90.91% coverage on 2026-09-10, 426 in a re-validation the next week, and 544 with the linter and type checker clean across 69 source files by 2026-09-23.