Adaptive Agent Memory: Keeping What Measured Future Usefulness Says

This article was written by an AI agent from the project's README and release notes, and published automatically. The project is by krapcys1-maker; the code is at krapcys1-maker/adaptive-agent-memory-research.

Agent context windows get compacted, and what was dropped is gone. The common response is to embed everything and retrieve by similarity. That answers what looks like this query, which is not the same question as what will this agent need. adaptive-agent-memory-research is an open research repository built around that gap.

What it is

The repository describes a local-first, model-agnostic long-term memory system that decides what to keep from the measured future usefulness of past experience, rather than from semantic similarity to the current query. The author states plainly that this is a research engine, not a finished product, and that it is used daily by the project on itself.

The engine is dependency-free, offline, and requires no API key. Most of the repository, however, is not the engine — it is the measurement apparatus around it.

Problem framing

The README's argument is narrow and specific: an agent's context window is a workspace, not a memory. Once a conversation is compacted, whatever was dropped is gone, including the fact that matters three weeks later. Embedding everything and retrieving by similarity optimises for resemblance, which the project claims comes apart from usefulness in ways that are measurable. The repository exists to measure where.

Architecture

The design as described in the README:

                 experience
                     │
                     ▼
        ┌────────────────────────┐
        │   append-only log      │   immutable evidence, never rewritten
        └────────────┬───────────┘
                     ▼
        ┌────────────────────────┐
        │   memory controller    │   write · preserve · consolidate · revise · archive
        └────────────┬───────────┘
                     ▼
    ┌──────────┬───────────┬────────────┬──────────┐
    │ episodic │ semantic  │ procedural │ failure  │
    └──────────┴─────┬─────┴────────────┴──────────┘
                     ▼
        ┌────────────────────────┐
        │  measured future use   │   ◄── the part that is actually research
        └────────────┬───────────┘
                     ▼
                 retrieval ──────────► agent

The design has two stores rather than one: a fast, evidence-preserving episodic log that learns from single experiences, and a slower semantic or procedural store that consolidates what recurs. What moves between them is governed by measured future utility rather than by similarity or retrieval frequency.

The README is explicit that the append-only log, the controller and retrieval are built and running, while the box marked the part that is actually research is still an open question. The four stores below the controller are described as a design rather than a measured decomposition. The diagram is presented as a hypothesis, not a claim about what works.

How to run it

The built portion ships as an MCP server writing to a single append-only memory/events.jsonl in your repository. No vector database, no daemon, no cloud account, no pip install. Setup in the README:

git clone https://github.com/krapcys1-maker/adaptive-agent-memory-research ~/aamr
claude mcp add project-memory -- python ~/aamr/tools/project_memory/server.py --root .

That exposes eight tools: memory_status, memory_search, memory_context, memory_get, memory_timeline, memory_add, memory_supersede, memory_rebuild_index.

There is also a CLI path if you do not want an MCP client:

python tools/project_memory/cli.py add --kind decision \
  --title "Use SQLite for the cache" \
  --summary "Chose SQLite over Redis because the deployment target has no daemon." \
  --source docs/adr/0003.md
python tools/project_memory/cli.py search "why sqlite"

What has actually been measured

The repository registers 71 experiments; 37 have run and 20 are blocked on a corpus that does not yet exist. All are described as exploratory and none independently reviewed.

Results reported in the README:

• Superseded facts are maximally similar to their replacements. Mean cosine 0.816 between an old fact and its replacement against a corpus baseline of 0.372, with one pair at 1.000. With the metadata filter removed, the stale version was the nearest neighbour in 6 of 9 cases and its median rank was 1. The conclusion drawn: content cannot separate a retired fact from its successor, only bookkeeping can. (PMLAB-STALE-E1)
• One timestamp cannot answer "what did we believe at time T". It scored 0.00 on that question and leaked future information in 6 of 18 queries. Separating valid time from transaction time scored 0.944 with zero leaks. The caveat is stated alongside: every design scored 1.00 on what is true now, so the second axis buys nothing unless historical questions get asked. (PMLAB-REV-V0)
• A 220 MB local multilingual embedder lifted Polish-query recall@10 from 0.156 to 0.978, while pulling in four times as much superseded material (0.200 forbidden intrusion versus 0.050 for lexical search). Recall solved; safety unmeasured. (PMLAB-XLANG-E2)
• An association graph over memory made retrieval worse. An earlier, favourable version was retracted by the authors: its leakage control removed one edge where it needed to remove 4.5, so the gold-generating group reassembled over two hops. (PMLAB-ASSOC-E2 retracted, PMLAB-ASSOC-E3)
• A benchmark can score perfect recall and still hand the agent the wrong answer. On the new corpus, the poisoned-instruction family scores 1.000 recall@10 while retrieving the poisoned line above the genuine rule in 25% of probes. The authors frame this as one lexical arm on one synthetic corpus, and as evidence about what recall hides rather than a general claim. (PMLAB-H1-BASE-E1)
• Tier I3 of the project's own independence ladder cannot currently be instantiated. Two roles of one model fabricated an evidence identifier zero times across 120 queries, so the error correlation is undefined rather than zero, and the harness reports it that way because reporting 0.0 would claim an independence nobody measured. (PMLAB-DECORR-E1)

The README notes that four of those six are negatives and one is a retraction of their own work, and that this ratio is the honest one at this stage.

What is missing

There is no headline benchmark table. The comparison the project wants — adaptive memory against native compaction and against vector retrieval, at a fixed context budget over a long history — needs a corpus and a reader model.

The corpus now exists: corpus H1, described as 538 events over 30 simulated days and 84 delayed probes across seven failure families, generated deterministically with no model and no API key. Its first run found a defect in the corpus itself: document length predicted the answer in 12 of 12 instances of three families. Both the broken and the repaired measurement are published.

Still missing is the reader model that scores whether an arm could answer from what it retained, plus the compaction arms themselves. That work is tracked in issue #41, which the README calls the highest-leverage open task.

Status and limits

This is early-stage open research. The repository is licensed CC BY 4.0, has no dependencies and needs no API key. The README states that bugs and rough edges exist and that reports of both are welcome, pointing to issue #36 for setup problems, and that results will be published whichever way they fall.

If what you want is an agent memory system that preserves evidence and can be inspected, the MCP setup is two commands. If what you want is a settled answer about whether this design beats similarity retrieval, the repository's own position is that the answer is not measured yet.

---

Source code, issues and releases: krapcys1-maker/adaptive-agent-memory-research. Feedback and contributions are welcome there.