Berry Brain

Pick up where your AI agent left off.

Berry Brain keeps task progress, checked results, and tested lessons in one private memory store. Use it with Codex, Claude Code, or another client that supports MCP, the Model Context Protocol.

For example, start a bug fix in Codex. Save what failed, what passed, and the next step. Later, Claude Code can recall that state and continue after checking that the facts still hold. Both clients must connect to the same brain and have access to the project. Each new installation starts empty.

How it works

Your prompt goes to the agent. The agent calls Brain when saved progress or past lessons could affect its next decision. Recall and saves are explicit tool calls; they do not happen automatically on every message.

Open the full-size diagram · Editable Excalidraw source

The agent can save during work, before a hand-off, or after a checked outcome. It does not need to wait until its final answer. Brain stores the submitted fields, not the whole conversation. Access rules limit which project records each client can read.

Related MCP server: tashevos

How memory becomes reusable knowledge

Saving a result does not make it a lesson. An agent must propose a lesson, or a configured host worker can draft one. The proposal stays a candidate until agents test it on later tasks and report the outcomes.

Open the full-size lesson diagram · Editable Excalidraw source

For example, an import fix can produce a checkpoint: “Validation passes; deployment next.” An experience records the cause, fix, and test evidence. A proposed lesson might say, “When an import fails, check required inputs before retrying.” It becomes active only after helpful reports from two fresh tasks with distinct evidence. The source tasks and evidence do not count. Harmful feedback retires the lesson.

Normal work can run these tests. With model selection on, recall can offer one candidate that the model judged relevant. It is marked untested. When the agent later saves an experience for that task, the response lists each lesson shown for the task that still needs a report. The model can suggest an outcome. The agent checks the result and sends its own report with feedback. A suggestion is never counted as a report.

Brain checks these evidence rules when feedback arrives. It does not independently verify reported outcomes. In local mode, there is no background worker: learning happens when an agent calls the tools.

Memory changes the context given to the model. It does not train the model or ensure better answers. Saved text is evidence. It cannot grant permission or replace instructions.

Where Jev fits

A keyword match can find a lesson that no longer fits. For example, a lesson about waiting for a running job is not useful when current facts say the job is complete.

The same optional lesson selector works with local storage and server setups. It asks an evaluation model, such as Jev, whether each matched lesson fits the task and current facts. You choose the provider endpoint, model, and private credential reference. No Berry server is required.

For a candidate lesson, only Keep shows it, and recall shows at most one. After the agent saves an experience, Jev can suggest whether each shown lesson helped, harmed, or made no difference. The agent confirms or corrects that suggestion in its own report.

If selection is off, fails, or returns an invalid reply, normal recall remains available. If saved state changes during the check, the brain uses fresh normal recall. Jev cannot grant access, promote a lesson, or find lessons that keyword search missed. The agent still needs to check current facts.

Configure once, use one selection path. The built-in HTTP adapter supports the TypeSafe-compatible evaluation API, including TypeSafe and Vercel AI Gateway. Other APIs connect through the same small evaluator interface. Berry's own setup uses its LLM Gateway adapter; provider keys stay in that Gateway.

Follow model setup to enable selection. Without model configuration, local Brain makes no network requests.

When selection is enabled, matched lesson texts and conditions, the query, supplied current context, and saved checkpoint go to your configured evaluator. After a saved experience, that experience and the lessons shown for its task also go to it. This adds a network call and model usage. It does not guarantee better answers, lower cost, or faster tasks.

Set it up

You need Python 3.11 or later with SQLite FTS5 support. Install your AI clients first. The Codex command must be on your PATH.

Download or clone this repository. Open a terminal in its directory.

On Linux or macOS:

python3 -m venv .venv
.venv/bin/python -m pip install .
.venv/bin/berry-brain-configure codex --local
.venv/bin/berry-brain-configure claude --local

Run the setup command for each client you use. For Windows commands, see Setup and data.

Reopen the client sessions. Ask an agent to recall a task, then save a checked result. Both clients use the same local database.

Setup adds the brain tools and a short reminder to the client's global instructions. Basic memory needs no separate brain account, model key, or server. Optional model selection uses your own provider configuration.

Keep .venv at this path. After an update, run the install and setup commands again. Saved data stays outside the source directory.

Read more

Local mode makes no network requests unless you configure model selection. The AI client can send recalled text to its model provider. Keep private data and credentials out of Git.

Released under the MIT license.