Skip to main content
Version 1.0.0 (2026-11-15) · on Maven Central · What’s New → Long agent tasks drown in their own history. Every turn re-sends earlier tool results, the context fills with stale detail, costs climb and the model loses the thread. Agent Memory keeps what the agent has learned, gives each request a token-budgeted slice of it, and has a model condense the backlog once it grows past a threshold. It is one Spring AI advisor: add it to a ChatClient and the agent carries a bounded, dense memory from turn to turn.
memory-advisor brings memory-core with it. Java 17 or later, Spring AI 2.0.1.

What you get

A drop-in Spring AI advisor

CompactionMemoryAdvisor is a BaseAdvisor. It works with blocking and streaming calls: a streamed response is aggregated before it is stored.

A hard token budget

Each request gets at most memoryTokenBudget tokens of memory, compacted summaries first and then the newest entries, so the prompt stays bounded however long the task runs.

Compaction written by a model

Once the uncompacted entries reach budget × ratio, a ChatClient you choose, typically a cheaper model, writes one summary with the task’s status and its learnings.

Nothing is thrown away

Compacted originals stay on disk, marked compacted, beside the summary in patterns/. The MemoryIndex can list entries by topic or by compaction state.

Safe with code and JSON

Stored memory and system instructions are substituted literally, so braces, JSON and template-like text in them do not break the prompt template.

Plain files you can read

Entries live under iterations/ and patterns/ with an _index.json; ProgressFileMemoryStore keeps a single progress.txt instead.

How it works

On each request, the advisor retrieves accumulated learnings within the token budget and injects them into the system message. After each response, it appends the assistant’s text to the store; it does not store the user’s messages or the conversation history. When the uncompacted entries reach budget × ratio, the compactor sends all of them to the compaction model, writes the summary as a new entry and marks the originals compacted. Compaction runs inside the advisor’s after() step, on the calling thread. Two parameters control it: Token estimation is a characters÷4 approximation, not a tokenizer.

Compatibility

Operating boundary

The filesystem store is local, plaintext, and single-writer. Read this before putting it in front of anything shared.
  • Memory is written to the local filesystem in clear text. It is not encrypted and is not shared storage.
  • There is no locking, no atomic index replacement, and no crash recovery. A second concurrent writer, or a crash during an index write, can corrupt or truncate _index.json — the only source of truth for the index.
  • Stored memory is injected verbatim into the model’s system prompt, so only trusted content should be written to it.
  • Multi-process or concurrent-writer use requires external coordination.
Locking, atomic index replacement, and crash recovery are backlog items, not shipped functionality.

Research background

The measurements below come from wiggum-memory, the research project Agent Memory was extracted from. They were produced by that project’s RalphMemoryAdvisor, not by the CompactionMemoryAdvisor published here, and this repository ships no live-model benchmark of its own. Treat them as the origin story for the design, not as performance claims for the library.

One research run on a 12-story PRD

A single research run (n=1) compared unbounded memory against token-budgeted retrieval plus compaction on a 12-story e-commerce PRD, with Anthropic Haiku 4.5 on both sides and the compaction step also using Haiku 4.5. Measured configuration: memoryTokenBudget 4,096, compactionRatio 0.5. The 8,192 / 0.75 defaults shown above were a recommendation for unstructured conversation and were never measured on this suite. Caveats that belong with the numbers:
  • n=1. In an earlier run of the same suite at a 2,048 budget, unbounded memory scored 11/12 and the budgeted configuration scored 7/12. The 9/12 figure above is one draw from a noisy distribution, and the write-up itself attributes the difference to ordinary LLM variability.
  • Pass/fail is self-reported by the run’s own judge, not an independent evaluation.
  • Cost is an estimate derived at a $6/MTok rate, not a billed amount.
  • The same write-up found that a 2,048 budget destroyed critical details (table names, endpoint signatures, auth token formats) and caused a five-story failure streak. Budget selection dominates the result.
Token growth without compaction was linear (~800 tokens/story, reaching 9,000+ by story 12). With compaction it plateaued around 4,600 tokens after the first compaction cycle. Loopy is a separate Spring AI agent CLI. Its AgentLoopAdvisor applies a related idea — threshold-based triggering with model summarization — but operates on conversation messages rather than accumulated learnings. It is a different implementation and is not this library. A code-coverage experiment there recorded: The model differs across the rows, so this is not a controlled comparison: the failing unbounded run used Haiku and the passing compacted run used Sonnet. No quality measurement was held constant, and the run that logged far fewer input tokens cost slightly more in dollars. The honest reading is narrow — in that experiment, compacting earlier was what let the run finish inside its cost cap. It is not evidence that this library reduces token use at equal quality.

Roadmap

Modules

The on-disk shape — iterations/, patterns/, _index.json, or a single progress.txt — is unversioned and carries no forward-compatibility guarantee.

GitHub

Source code at v1.0.0

1.0.0 release notes

First 1.x release

Origin

Extracted from wiggum-memory, a private research project that explored the Ralph Wiggum pattern for context management in AI agent loops. The memory subsystem proved to be the most broadly useful component, so it was promoted to a standalone library as part of the AgentWorks stack.