Skip to main content
What’s New → Latest — 0.5.1. 0.4.0: first Business Source License 1.1 release. Jackson floors raised for standalone consumers, an aggregate CycloneDX SBOM published on the parent artifact, hosted OWASP/NVD scanning removed in favour of a local offline procedure, and the operating boundary documented. Tier-1 compaction behaviour is unchanged from 0.1.0.

​
Overview

Agent Memory gives AI agents a way to manage conversational context. Without memory management, every prior tool result is re-sent every turn — on long tasks, context fills with stale noise, costs climb, and the model loses focus. Agent Memory stores accumulated learnings on the filesystem, injects a token-budgeted subset into each request, and summarizes older entries with a cheaper model once the uncompacted set crosses a threshold. The library starts with context compaction and progressively adds structured retrieval, reflection, and autonomous memory management — eventually reaching MemGPT-level capabilities. Each tier is independently useful. Tier 1 is what ships today; tiers 2–4 are planned. Agent Memory ships as a Spring AI BaseAdvisor — plug it into any ChatClient pipeline with one line:
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 output to the store. When uncompacted entries exceed budget × ratio, compaction summarizes them via a cheap model and replaces them with dense summaries.

​
Compatibility

​
Operating boundary

The 0.4.0 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.

​
How Compaction Works

When accumulated context exceeds a token budget, older entries are summarized by a cheap model (e.g., Haiku) and replaced with a compact summary. The agent continues with dense, relevant context instead of an ever-growing prompt. Two parameters control it: Token estimation is a characters÷4 approximation, not a tokenizer.

​
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 (0.5.1 on Maven Central)

​
Origin

Extracted from wiggum-memory — a 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.