agentlore

Repo memory for coding agents — committed to your repository, reviewed in the pull request that motivated it, and gated so it cannot silently rot.

Coding agents forget everything between sessions, and the facts worth keeping — decisions, dead ends, house rules — end up in someone's head or in a chat log nobody will read again. agentlore gives them somewhere to live: typed markdown in .memory/, versioned with the code, compiled into the AGENTS.md your agent already reads, and checked in CI.

One file. Python standard library. No dependencies, no service, no account, nothing to configure.

Current release v0.9.1 · site · changelog · what it does not do yet

The failure it exists for

An agent fixes a bug, and records the dead end it just disproved. The note is true when written and false the moment the fix lands — and it now reads as a live warning to every future agent. Real output, from one change:

$ agentlore add --type dead-end \
    --title  "The refund window rejects credit notes too" \
    --body   "Routing credit notes through refund() fails: the vendor rejects them." \
    --anchor "src/billing/**" --evidence "PR #4821 - double charge"

$ agentlore check --since "$BASE_SHA"        # in CI: github.event.pull_request.base.sha
MEMORY-HEALTH: 17/18 BROKEN  (1 memories, 0 stale, billing)
  ...
  FAIL dead-ends-settled  -- 1 unsettled

dead ends that rode the change that settled them:
  DEAD-2026-09-29-95f7  The refund window rejects credit notes too
    anchored to src/billing/**, changed in this same change: src/billing/gateway.py
    -> this memory now reads as a live warning about a condition your change removed.
    -> state it: agentlore verify DEAD-2026-09-29-95f7 --resolved-by "<what settled it>"
    -> or retype it as a decision and write the title about the CURRENT rule.

2 finding(s) -> fix before merging

The agent's body hedged ("before the fix"); the heading did not — and the heading is the first thing the next agent reads. So the tool rewrites it rather than trusting the agent to:

$ agentlore verify DEAD-2026-09-29-95f7 --resolved-by "vendor supports credit notes as of v3.2"
verified DEAD-2026-09-29-95f7 @ b5c646d

$ grep '^## ' .memory/dead-ends.md
## The refund window rejects credit notes too (settled)

$ agentlore check --brief
MEMORY-HEALTH: 17/18 BROKEN -- compile-current     # the file your agent reads is now stale
$ agentlore compile
$ agentlore check --brief
MEMORY-HEALTH: 18/18 GREEN

Three states, three honest outputs: the memory stopped being true, the record was corrected, and then the compiled file your agent actually loads was caught lagging behind it. That last one is a check most tools do not have — memory that is recorded but never delivered is invisible in every direction. The accuracy gate, in full →

Install

One 89 KB Python file with no dependencies, so there is nothing to install in the package-manager sense — you pick how much of it you want to own.

Requirements: Python 3.9+ (CI runs 3.9 and 3.12) and git. That is the whole list: no virtualenv, no lockfile, no build step. There is nothing to resolve, pin or audit — the tool is a single stdlib file. The canonical artifact is that one file; a package-index install is a managed copy of it, not a different thing.

1. As a GitHub Action — nothing to install

Usually the right answer, because the gate is the part that has to run on every PR:

      - uses: actions/checkout@v4
        with:
          fetch-depth: 0        # only so an annotation can name the file that drifted
      - uses: Rudra5417/agentlore@v1
        with:
          since: ${{ github.event.pull_request.base.sha }}

GitHub fetches the tool for you. Nothing in your repo changes, and there is no version to track — @v1 is a moving tag, so you get fixes without editing workflows.

2. Vendored into your repo — self-contained, no third-party action

The opposite trade: you own the file, so CI needs no network fetch and no action dependency. Some organisations require this.

mkdir -p tools
curl -fsSL -o tools/agentlore https://raw.githubusercontent.com/Rudra5417/agentlore/v0.9.1/agentlore
chmod +x tools/agentlore
git add tools/agentlore
python3 tools/agentlore check --brief          # runs with no install at all

Pin the tag (as above) for reproducibility, or use main to track HEAD. Then wire it into a job the same way the action does it — see docs/using.md for the three commands.

3. On your PATH — for local use, and for an agent to call

Worth it if you want an agent to run agentlore itself, or to check memories before pushing:

mkdir -p ~/.local/bin
curl -fsSL -o ~/.local/bin/agentlore https://raw.githubusercontent.com/Rudra5417/agentlore/v0.9.1/agentlore
chmod +x ~/.local/bin/agentlore
agentlore --version                            # agentlore 0.9.1

If ~/.local/bin is not already on your PATH, add it (export PATH="$HOME/.local/bin:$PATH"). Prefer git clone? The tool is just the file at the repo root — copy it wherever you like; nothing depends on its location, and it runs from any working directory.

4. From a package index — pip, pipx or uv

A managed copy of the same file, for when you would rather not vendor or curl it:

uv tool install agentlore        # or: pipx install agentlore   /   pip install agentlore
agentlore --version              # agentlore 0.9.1

The package ships the identical single, zero-dependency file — installing it resolves nothing.

Check it before you wire it in

$ agentlore init && agentlore check --brief
MEMORY-HEALTH: 18/18 GREEN

An empty .memory/ is green on purpose: there is nothing to be wrong about yet.

Quick start

agentlore init          # 1. create .memory/, gitignore the derived index
                   # 2. your agent (or you) records what it learns:
agentlore add --type decision \
    --title "Refunds close at 90 days" --body "Vendor contract; enforced in gateway.py." \
    --anchor 'src/billing/**' --evidence "PR #4821"
agentlore compile       # 3. deliver it — writes a block into AGENTS.md
agentlore check         #    exit 1 when a memory has stopped being true

(Using the vendored copy from option 2? Every command below is python3 tools/agentlore … instead.)

Commit the .memory/*.md and the AGENTS.md block. That is the whole model: the markdown is the source of truth, the index is derived, and the memory rides the pull request that motivated it, where a teammate reviews it like code.

Then add the gate. No vendored copy, nothing to keep in sync:

      - uses: actions/checkout@v4
        with:
          fetch-depth: 0        # only so an annotation can name the file that drifted
      - uses: Rudra5417/agentlore@v1
        with:
          since: ${{ github.event.pull_request.base.sha }}

since is the one input worth setting: without it dead-ends-settled cannot tell what your change touched, and a silent check is a disabled check. Action inputs and the CI wiring →

What the gate catches

Eighteen checks. A failure names the broken thing and the fix, and prints on the line of the memory that is wrong.

One softer signal is reported but never breaks the build: a notice when anchored files were only reformatted — bytes changed, meaning identical. All eighteen, in detail →

Honest status

The part most tools do not have. The memory mechanism is proven; the memory's benefit is not. Nothing here asks you to believe a claim that is not on this table.

unproven means the experiment has not been run, or it came back null — not that the result was inconvenient. preliminary means it ran and points somewhere, but the sample is too small to claim. The full table, the agent trials, and how they were measured →

How it differs

• AGENTS.md / CLAUDE.md — plain prose, hand-written, loaded in full every session, and it rots silently. agentlore compile feeds it: typed fragments are the source, AGENTS.md is a build target, so nothing has to change its read path.
• mem0 / claude-mem / OpenMemory — auto-capture into an opaque store. Not reviewable, not shared ground truth, not versioned with the code.
• ADRs — reviewable and versioned, but too much ceremony per decision and no agent write path. Nothing in an ADR tells you it has stopped being true.
• fiberplane/drift (the most-adopted tool here, ~146★) — AST-symbol anchoring, which is better at decay than a content hash, but it watches docs, with no typed decisions, no supersession and no accuracy check.
• gitmem, stalebrain, agent-memory, sverklo, lore — each owns a piece. Nobody composes it into one loop that also refuses to hand over memory it suspects is wrong, and nobody binds a memory to the control that enforces it.

The unclaimed property is accuracy: every tool in this space checks whether memory is stale. None checks whether it is true. Prior art and the evidence behind that line →

Docs

python3 run_tests.py       # 115 tests, ~40s, stdlib only — same as the tool

CI runs the suite on Python 3.9 and 3.12, then puts the shipped example through its own memory gate on every pull request using the published tag.

Contributing

The most valuable thing you can send is a case where it does the wrong thing — a false failure, a missed staleness, a gate that went green when it should have gone red. See CONTRIBUTING.md. Security issues: SECURITY.md, privately.

MIT — LICENSE. Release history: CHANGELOG.md.