BizerBrain — A Reference Implementation of the Cognitive Architecture for AI Agent Memory

A companion paper to A Cognitive Architecture for AI Agent Memory (v1.1) May 2026

By Kelsi Guidry with research and drafting assistance from Claude (Anthropic)

Overview

A Cognitive Architecture for AI Agent Memory (“The Whitepaper”) argues that AI agents need a layered memory architecture modeled on the human multi-store model — sensory ingestion, short-term working memory, a consolidation bridge, long-term memory in coordinated stores, and active retrieval. The paper makes the argument architecturally and leaves implementation to the deployment context.

This paper introduces BizerBrain, a working reference implementation of that architecture. BizerBrain is one realization of the thesis — opinionated, specific, and intentionally narrow in scope for its first release. The whitepaper describes the architecture in its full form; BizerBrain is the first working slice of it. Other implementations of the same thesis are possible and welcome; this is the one I built.

The repository is public at github.com/kelsi-bizer/bizerbrain, licensed Apache-2.0, and runnable on any VM with Docker. The agent skill in the repository works today with Hermes Agent, OpenClaw, and Claude Code.

What BizerBrain Is

BizerBrain is a markdown knowledge base for AI agents and humans, built around plain files on disk. Notes live as .md files in a folder. An AI agent and a web UI both read and write the same files, with live updates between them. There is no database, no proprietary format, and no synchronization layer — the agent and the UI are literally looking at the same files.

The system ships as a single Docker container with four components inside:

• A web UI (packages/notes-app) — a Vite + React markdown editor that gives a human direct access to the same notes the agent is working with.
• A file API (packages/file-api) — a Fastify HTTP service that exposes the brain folder as a tiny REST API used by the web UI.
• A nginx layer (docker/) that runs both inside one container behind a shared port.
• An agent skill (.agents/skills/bizerbrain) in the agentskills.io format, which is what the AI agent loads to interact with the brain.

The container mounts a folder from the host — /srv/bizerbrain/brain — as /brain inside. That mounted folder is the brain. Everything that has ever been written to the brain is in that folder, as plain markdown, organized however the user and the agent have agreed to organize it.

A reader of the whitepaper will recognize this as the canonical store from Section 3.4 — human-readable encoded memories, written to a persistent, version-controllable file system. In BizerBrain, the canonical store is also the only store. The vector index, the consolidation pipeline, and the provenance archive that the whitepaper describes are not yet built. That’s a deliberate v1 scope. The reasoning is below.

How BizerBrain Maps to the Whitepaper

The five-layer architecture in the whitepaper does not all live inside BizerBrain. Some of it lives upstream in the agent that connects to BizerBrain; some of it is intentionally deferred. The mapping is worth being precise about because the boundary between agent and brain is the architectural commitment that makes BizerBrain agent-portable.

Layer 1 — Sensory ingestion

In the whitepaper, sensory ingestion is the brain’s intake surface — every input the agent receives is captured here in raw form with provenance metadata.

In BizerBrain, sensory ingestion happens upstream of the brain. The agent is the one talking to the user, receiving documents, hearing voice transcripts, fetching URLs. By the time something reaches BizerBrain, the agent has already decided it’s worth committing. The brain’s write_note tool is the interface; what the agent commits is the agent’s judgment, not BizerBrain’s.

This is consistent with a separate principle that has surfaced since the whitepaper was published: the agent’s context window is the attention filter, and the brain receives pre-filtered signal. BizerBrain leans into that. The brain is not trying to manage the firehose; the agent is.

Layer 2 — Short-term memory

Short-term memory — the active session, the working set, the LLM’s context window — also lives upstream in the agent. BizerBrain has no concept of sessions. The agent runs sessions; BizerBrain stores what the agent decides to keep.

Layer 3 — The consolidation bridge

The consolidation bridge is the most architecturally important layer in the whitepaper and is not yet built in BizerBrain. There is no asynchronous worker that turns the residue of closed sessions into structured memories, no relevance scoring, no supersession logic, no multi-session synthesis.

What exists today is the simpler case: the agent writes notes directly via write_note, edits them via subsequent write_note calls, and the user can edit them by hand through the web UI. Supersession is handled by overwriting. Relevance is implicit in what the agent chose to write. Consolidation in the rich sense the whitepaper describes is on the roadmap, not in the v1.

This is a real gap and worth naming clearly. The whitepaper argues that consolidation is the layer that separates “memory as a process” from “memory as a database.” BizerBrain v1 is closer to the database side of that line than the process side. Future releases will build out the consolidation pipeline; today’s BizerBrain is the substrate that consolidation will eventually run on top of.

Layer 4 — Long-term memory

This is where BizerBrain does the most work. The whitepaper describes long-term memory as three co-located stores: the canonical store (markdown), the retrieval index (vectors and metadata), and the provenance archive (raw inputs).

BizerBrain ships the canonical store fully and defers the other two:

• Canonical store: implemented as .md files in /srv/bizerbrain/brain. Each note is a plain markdown file, hand-editable, grep-able, git-able, migratable. The format is intentionally simple — no required frontmatter schema, no proprietary syntax beyond standard markdown and wiki-style links. The folder structure is whatever the user and agent agree on; a typical layout is daily/ for one note per day and pages/ for people, projects, and topics.
• Retrieval index: not yet present as a vector store. The agent searches the brain via search_notes, which performs text-based search across filenames and content. This is the layer most likely to be added next, as a vector index that supplements (not replaces) the text search.
• Provenance archive: not yet present. Notes carry no automatic link back to the conversational moment that produced them. When the agent writes a note, the source context is implicit in what the agent chose to write, not stored as a separate provenance record. This is a real limitation for agentic deployments that need to answer “where did this fact come from?”

The whitepaper’s argument for separating canonical from index is that the canonical store outlives any specific index. BizerBrain honors this in advance. When the vector index is added in a future release, the markdown files will not change. Re-indexing will be a matter of running an indexer over the existing brain folder, not a migration.

Layer 5 — Retrieval as active cognition

The whitepaper describes retrieval as a hybrid operation with three modes: semantic similarity, exact recall by filter, and cue-based bridging across associated memories. BizerBrain’s retrieval today is the recall-by-filter case: search_notes does text search; read_note fetches a specific file; list_notes browses the folder. Semantic and bridge modes require the vector index that hasn’t shipped yet.

The agent itself does some of the cognitive work that the whitepaper assigns to the retrieval layer. When the user asks “what did we decide about X last week,” the agent decides which tools to call, in which order, and how to synthesize the results into an answer. The brain provides the surface area; the agent does the active cognition. In a fuller implementation, more of that work would shift into the retrieval layer itself.

The Agent-Portable Boundary

The defining architectural commitment of BizerBrain — the thing that distinguishes it from a knowledge app that happens to integrate with an AI — is that the brain knows nothing about the agent.

The brain exposes four tools through the agent skill:

• list_notes — list the contents of the brain folder
• search_notes — text search across notes
• read_note — read a specific note by path
• write_note — write or overwrite a note at a given path

That’s the entire contract. The brain does not know which agent is calling. It does not know which LLM is behind the agent. It does not store the agent’s identity or configuration anywhere. Hermes Agent calls these four tools and writes notes. OpenClaw calls the same four tools and writes notes. Claude Code calls the same four tools and writes notes. None of them can tell that the others have been there, except by reading the notes that were written.

This is the agent-portable brain thesis made concrete. The brain is the durable entity. Agents are stateless consumers that authenticate (or in v1, simply have file access to) the brain folder. The knowledge survives a change of agent the way a filesystem survives a change of editor — because there is no semantic coupling between the storage and the tool that uses it.

For a small business or a knowledge worker operating an agent today, this means the choice of agent is no longer permanent. If a better Hermes ships next year, or OpenClaw becomes the better fit, or a new agent appears that doesn’t exist today, the user’s accumulated notes move with them at zero cost. The agent is the renter. The brain is the house.

What the Web UI Is For

A reader of the whitepaper might ask why BizerBrain ships a web UI at all. The whitepaper is about agent memory; the agent should be doing the work.

The UI exists for the cases where the agent is not the right interface:

• Reading what the agent captured. Sometimes the user wants to scan the brain directly, not have it summarized.
• Fixing things the agent got wrong. Typos, names, facts the agent misheard or misinterpreted. The user can correct them in the file and the agent reads the corrected version next time.
• Writing things the user doesn’t want to say to an agent. Drafts, private thoughts, sensitive notes that should be in the brain but didn’t come from a conversation.
• Browsing how notes connect. Wiki-style links between notes are visible in the UI, and the user can trace ideas backward through backlinks.
• Curating. Renaming, restructuring, deleting — operations that an agent could do but that a human often wants to do directly.

The principle behind keeping the UI in the same container as the brain folder is that the UI and the agent must never see different worlds. Both read and write the same files. A note the agent just wrote shows up in the UI within a second. A note the user just edited is visible to the agent’s next read_note call. There is no sync, no export, no risk of the two diverging because they are not two systems — they are two windows into one folder.

What’s in the Container

The Docker container packages the entire system into one runnable image:

docker run -d \
  --name bizerbrain \
  --restart unless-stopped \
  -v /srv/bizerbrain/brain:/brain \
  -p 127.0.0.1:8080:80 \
  ghcr.io/kelsi-bizer/bizerbrain:latest

Inside the container, nginx serves the web UI on port 80 and proxies API calls to the Fastify file-api service, which has direct access to the mounted /brain volume. The agent skill is also bundled in the image at /opt/bizerbrain/.agents/skills/bizerbrain so an agent running on the same host can symlink it into its skills directory.

The port is bound to 127.0.0.1 deliberately. The web UI is not meant to be exposed to the public internet. Access to the UI is via SSH tunnel:

ssh -L 8080:localhost:8080 user@your-vm

This is a security-and-simplicity decision for v1. There is no authentication on the API or the UI, because there is no notion of multi-user access in this release. Whoever can reach the brain folder can use it. For a single user dogfooding the system on a VM they control, that’s appropriate. For multi-user deployments — the eventual platform direction — auth will be added at the appropriate layer.

What Comes Next

BizerBrain v1 is the substrate. The architecturally interesting layers that the whitepaper describes — consolidation, hybrid retrieval, provenance — sit naturally on top of this substrate and will arrive in subsequent releases.

The next likely additions, in rough order:

1. A vector index alongside the markdown files. Embeddings of each note’s content, queryable for semantic retrieval. The markdown stays canonical; the index is derived and rebuildable.
2. A consolidation worker that runs on a schedule, processes recent notes, and produces structured memory artifacts — supersession of older notes, abstractions across related notes, relevance scoring of what the agent has been writing.
3. A provenance layer that tracks which agent wrote which note and when, and ideally links each note back to the conversational context that produced it.
4. An MCP server interface in addition to the agent skill, so agents that speak MCP can connect to the brain through their native protocol.
5. Multi-user and authentication for deployments where more than one person uses the same brain or where multiple brains coexist on the same host.

Each of these is its own real work and will arrive when it’s ready. The v1 release is not waiting on any of them. The point of shipping the substrate first is that the substrate is what every later layer depends on, and shipping it lets real use begin while the layers above are built.

How to Use It

The repository is at github.com/kelsi-bizer/bizerbrain. The README covers installation on a VM, agent integration for Hermes, OpenClaw, and Claude Code, and the four-tool reference.

For someone wanting to try BizerBrain today:

1. Stand up a small VM with Docker installed.
2. Run the container as shown in the Docker invocation above.
3. SSH-tunnel to the UI to verify the web side works.
4. Install the agent skill in your agent of choice using the symlink pattern in the README.
5. Start talking to your agent and ask it to capture, recall, or organize things.

The brain will be at /srv/bizerbrain/brain on the VM. It is a folder of markdown files. You can ls it, cat the files, edit them in vim, back them up by copying the folder. The brain is yours and it is just files.

The Reference and the Body of Work

This paper exists alongside the whitepaper as the second piece of a longer body of work. The whitepaper makes the architectural argument. BizerBrain demonstrates one implementation of it. Future pieces in the body of work will dig deeper into specific architectural questions — agent portability as its own thesis, the storage levels above markdown, the forgetting question, importance ranking, and the larger framing of how individual brains relate to organizational and ecosystem-scale knowledge.

The whitepaper and BizerBrain are mutually reinforcing. The whitepaper without an implementation is theory. BizerBrain without the whitepaper is another markdown notes app. Together they are an architectural argument with a working artifact attached.

The body of work will continue. Subsequent papers will be published on a monthly cadence at bizer.ai, and BizerBrain will continue to develop as the reference implementation that the architecture is tested against.

BizerBrain is Apache-2.0 licensed and intended to be useful to anyone building in this space, whether they adopt BizerBrain itself or implement the whitepaper architecture in their own way. The thesis is what matters; the code is one demonstration of it.