Koog Agent Memory: Persist and Retrieve Useful Context

Koog is JetBrains' open-source framework for building AI agents in Kotlin. It provides a structured way to define agents, tools, and execution pipelines in the Kotlin ecosystem. Memory in Koog covers conversation history management within a session and the storage patterns available for carrying state across runs.

Like most agent frameworks, Koog' default memory is in-process: it clears when the JVM process exits. For context that must outlast a run, you connect external storage. Project context, reviewed lessons, and decisions about the work belong outside the framework entirely. Tools like fenbs keep that record separate from execution state and available to any tool that connects to the project.

Conversation memory in Koog

Koog manages conversation history as a sequence of messages passed to the language model. The agent appends each exchange to the history and includes it in subsequent calls so the model can refer to earlier turns. This is the same pattern most agent frameworks use, grounded in how the model itself handles context.

The history grows with each turn. Koog provides mechanisms to manage history length, including capping it at a token limit. When the limit is reached, older messages are removed or summarized. Test this boundary explicitly by running a long conversation and asking the agent about an early detail.

Persistence patterns

For state that must survive a process restart, Koog agents can write to any storage accessible from Kotlin: a relational database through JDBC, a key-value store, a file, or a cloud API. The framework does not prescribe a storage backend. You choose the persistence layer and integrate it through tools or lifecycle hooks.

A common pattern is to serialize the conversation history or a structured summary at the end of each run and load it at the start of the next. This keeps the persistence logic explicit and testable rather than embedded in framework behavior that might change between versions.

Choosing a storage backend for Koog persistence

Koog's persistence is explicit: you choose the backend, write the serialization code, and decide when the write happens. A file-based store is the simplest starting point for development. A relational database gives you query capabilities and transactional writes for production. Redis works well when you need fast reads at the cost of higher operational complexity.

Whichever backend you choose, test that the write and read operations are symmetric. Serialize a Koog conversation history, clear the in-memory state, deserialize from the backend, and run the agent with the restored history. If the agent's first response assumes facts that were in the earlier session, the serialization round-trip is working correctly. Any deviation points to a serialization bug or a field the backend does not preserve. Run this test after every significant update to the Koog version or the storage library to catch incompatibilities before they affect production runs.

Restart and correction tests

Run a Koog agent, stop the JVM, and restart it. Ask the agent a question whose correct answer depends on what was said in the previous run. If the answer is empty or incorrect, the state is not persisting through your current storage configuration.

Then test a correction. Record a fact in one session, correct it in a second session, and ask in a third. The third session should return the corrected version. If it returns the original, the storage layer is not updating correctly or the retrieval is pulling a stale copy.

For general patterns in building and validating agent memory, see how to build agent memory and agent memory vs context.

What to keep outside execution state

Execution state is what happened in a run: the messages, the tool calls, the intermediate results. Project context is what the work is, what people decided, and what the next session should do. These two categories have different owners, different lifespans, and different audiences.

Execution state lives inside the agent. Project context belongs to the team and should be readable without running an agent. Mixing them makes the project context dependent on the agent runtime being available and configured correctly.

Lessons learned are worth particular attention. If a Koog agent session reveals a problem with how a task was specified, or a pattern that made the agent fail, that lesson belongs in a shared record where people and future sessions can read it before starting similar work.

How to do this with fenbs

1. Create a free account and add the project your Koog agents support.
2. Add the decisions and standing rules to fenbs with the person who set each one.
3. After sessions where the agent surfaces something worth remembering, add it as a Lesson in fenbs with what happened and what to do differently.
4. Before starting a new Koog session on the same project, check fenbs for the current task state and any lessons relevant to the work.
5. Connect a supported AI tool over MCP from Integrations to load the project context automatically at session start.

For the MCP connection pattern that agents use to read from external memory, see agent memory MCP. For security questions about what to store and what not to, see agent memory security.