Long-Term Memory Is Just a Directory

Talk about long-term memory for AI agents and most people picture vector databases, embeddings, knowledge graphs, automatic summarization, and elaborate policies for what gets written and what gets recalled.

OpenCockpit Bots take a different path:

Long-term memory is a directory of state and context that the model can explore.

A Bot does not try to decide for the model what counts as memory, and it does not ship a separate memory runtime. It provides one small, transparent mechanism: content worth reusing is saved, summoned, and carried forward in any session, with any model.

A Bot is not a prompt

A Cockpit Bot is, first of all, an ordinary directory.

my-bot/
├── BOT.md
├── identity/
│   ├── persona.md
│   └── principles.md
├── relationships/
│   └── user.md
├── memory/
│   ├── facts.md
│   └── procedures.md
├── commitments/
│   └── active.md
└── projects/
    └── project-a/
        └── CONTEXT.md

None of these folders are tables in a platform-defined schema. They are one way a user chose to organize things, and they can be added, removed, or restructured as needs change.

BOT.md is the entry point. It describes who the Bot is, and it also tells the model:

what the Bot is responsible for;
which file holds what;
which files to read for which kind of task;
what may be written;
how to handle corrections, forgetting, and conflicts;
which Skills are available on demand.

So BOT.md is not a persona prompt in the usual sense. It is closer to the index, router, and operating manual for a space of long-term context.

Summoned, not bound

A Bot does not belong to a particular chat, and it is not tied to a particular model.

You summon it with @name from any project and any session. Cockpit hands the model the Bot's entry point together with the current task; the model reads BOT.md and then explores the relevant folders according to the index and rules it finds there.

The whole flow looks like this:

your task
  ↓
summon the Bot
  ↓
read BOT.md
  ↓
locate the folders and files this task needs
  ↓
explore, understand, and assemble the context
  ↓
do the work
  ↓
update long-term state when you authorize it

The same Bot can be used by Claude today and picked up by Codex, GLM, Kimi, or a local model tomorrow. As long as a model can read files and follow BOT.md, the long-term context is never locked inside one vendor's private memory system.

The model is the retriever

Cockpit Bots have no built-in vector search, embeddings, or knowledge graph. That does not mean there is no retrieval. The retrieval is model-driven exploration of a file system.

Modern coding agents already solve this problem well. Dropped into an unfamiliar codebase, they do not stuff every file into context. They read the entry docs, look at the directory layout, search for keywords, follow references into the relevant files, and build up an understanding step by step.

A Bot's long-term context uses exactly the same mechanism. BOT.md provides the high-level index, the directory structure provides information boundaries, file names and headings provide semantic cues, and the model decides where to dig based on the task at hand.

This is retrieval that uses what the model can already do:

no retrieval service to deploy;
no embeddings to precompute;
no copy of your content in a second store;
no need for the platform to know in advance how you will organize memory;
no index to rebuild when the directory layout changes.

To the model, it is not querying an unfamiliar memory API. It is exploring a codebase of context.

You define the Bot's cognitive environment

Cockpit does not impose one memory structure on every Bot.

A research Bot might organize itself around papers, evidence, conclusions, and open questions to verify. A project Bot might use decisions, progress, risks, and commitments. A personal assistant might use relationships, preferences, schedules, and long-term goals.

What you define is not a handful of static memories but the Bot's long-term cognitive environment:

which information is worth keeping long term;
which is only relevant to one conversation;
where each kind of information lives;
what to read when answering which kind of question;
which sources are more trustworthy;
how new facts revise old ones;
what should expire or be forgotten;
which state needs follow-up later.

The platform does not try to design a universal ontology that fits everyone. Files and Markdown are the lowest common denominator, and BOT.md lets each Bot have its own information architecture.

Explicit memory, not automatic absorption

Many automatic memory systems continuously analyze conversations and decide on their own what to keep. That looks convenient, but it brings problems that are hard to avoid:

the model can write a misunderstanding down as a fact;
a passing thought can be stored as a lasting preference;
untrusted web pages or tool output can contaminate memory;
you cannot tell which memory influenced a given answer;
after deleting a memory, it is hard to confirm it no longer survives in some summary, index, or derived data.

Cockpit Bots lean toward explicit authorization. Ordinary work is read-only by default. A Bot changes its long-term state only when you explicitly ask it to remember, update, correct, or forget something. What may be recorded, where it goes, and how older content is handled are decided by the Bot's own rules.

That gives up some of the convenience of "it remembers everything for you" in exchange for a much clearer boundary of control:

what the long-term state is — open it and look;
why something was recorded — the source can be kept alongside it;
what was written wrong — fix it directly;
what you do not want kept — delete it, for real;
when things changed — trace it through diffs and version history.

The file system is the interface

Plain files come with capabilities that elaborate memory systems tend to underestimate.

Readable. You do not need an admin console to check what a Bot knows.
Editable. Memory is not a black box that can only be changed indirectly through the model.
Diffable. Git and file diffs show exactly what a task changed.
Portable. Copy a directory and you have moved or backed up the Bot's identity and context.
Model-agnostic. The content is not hidden state owned by one vendor.
Extensible. Full-text search, embeddings, knowledge graphs, or other indexes can be layered on top later — as optional accelerators, not as a precondition for memory to exist.

Even if every add-on service disappears, the contents of the directory remain complete, readable, and recoverable.

Minimal, but not left to sprawl

The obvious worry about memory-as-a-directory is that it only grows: more files, older facts, until exploring it becomes slow and unreliable.

Cockpit's answer is not a retrieval service bolted on top. It is having the Bot review itself:

@product review its memory

A review is the one time the whole directory is read. It looks for:

stale entries — expired, or time-bound numbers, versions, and status confirmed long ago;
contradictions — classified first: a change over time, a difference in scope, a clash of authority, or a genuine conflict only you can settle;
dangling commitments, missing sources, duplicated information, and broken Skills;
orphaned conclusions — still marked active, though what they rested on has been superseded or disputed;
oversized context — the directory has outgrown the read rules in BOT.md.

Size is handled with files too. An oversized file is split by subject, each split directory gets an INDEX.md with one line per entry, and BOT.md is rewritten to read the indexes first and open individual entries on demand. No budget arithmetic, no retrieval layer — the information architecture simply grows with the content.

The findings are saved as a report under .reviews/ and returned as a numbered list; nothing in long-term memory changes until you pick the rows to apply. Housekeeping follows the same rule as everything else: the model proposes, you decide, the files record.

What remains is a genuine trade-off. Retrieval and write quality still depend on each model's tool use and instruction following. And low-latency processing of huge event streams is simply not the problem a directory is meant to solve. If it ever needs to be, caches or search can sit on top as rebuildable accelerators, with plain files still the source of truth.

The key is not to invert that relationship: a vector database, a private schema, or one model's hidden state should never become the only place a Bot's memory lives.

Not a memory platform, but a memory substrate

Judged as a complete memory platform that learns, organizes, and recalls automatically, Cockpit Bots would look like they are missing a lot of features. But that is not what they are trying to be.

They provide a more basic layer:

A way for long-term context to outlive any single session and any single model, persisting as an ordinary directory.

Cockpit makes a Bot findable, summonable, and hand-off-able to different sessions. BOT.md describes how the context is used. You define the structure that fits you. The model finds, understands, and updates the relevant content the way it would explore a codebase.

The value of the design is not that it decides how you should remember. It is that the memory you define always belongs to you, and any suitable model can keep using it.

The ideal long-term memory may not be an ever more complex, ever less visible intelligent database. It can just be a directory.

A directory you can understand, a model can find its way around, a session can carry with it, and you will still be able to open years from now.

Read the Bots documentation, or the previous post: Bots: Persistent Subagents You Can Tag into Any Task.

Try it: npm i -g @surething/cockpit · GitHub · Try Online