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 reachbudget × 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.
Research background
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.
A related experiment in Loopy — different implementation, different models
Loopy is a separate Spring AI agent CLI. ItsAgentLoopAdvisor 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.
Quick Links
GitHub
Source code at v1.0.0
1.0.0 release notes
First 1.x release