Shared memory
The shared memory keeps what past work taught: decisions, code structures, methods and mistakes, one Markdown file
per entry, kept in the repository so it is reviewed and versioned with the code. The model reads it through
memory_recall, proposes to it through memory_push, and nothing enters it unless /memory admit admits it: you
answer for each candidate, or memory.autoAdmitAudited admits the audited ones for you.
It is not the agent memory of the runtime (/workspace/.orkeon/agent-memory, per agent and per run): the two folders
stay apart, and memory.dir refuses the agent memory's folder.
The folder
.orkeon/memory/
├── candidates/ proposals waiting for /memory admit, one file each
│ └── CANDIDATES.md the pending candidates (generated)
├── entries/<type>/ admitted and superseded entries, by type
├── refused.md topics refused once, never proposed again
└── INDEX.md every entry, with its status (generated)
The two generated lists are views: edit a candidate's own file, never CANDIDATES.md. A candidate once decided keeps a
one-line file that says where it went (no file tool deletes a file); you may delete it.
Settings
| Key | Default | What it does |
|---|---|---|
memory.dir |
.orkeon/memory |
The folder, relative to the project; never under .claude/ or .git/, in any letter case (.Claude/mem), never the agent memory's folder. |
memory.project |
the origin remote's name, else local |
The project the entries name, and the index collection memory-<project>. |
memory.autoAdmitAudited |
false |
true: /memory admit admits a candidate an audit backs (a mistake: three batches) without asking. A project file's true applies only when your user settings say true too. |
An invalid stored value is set aside with a warning line, and the default applies.
An entry
An entry is a front matter and three sections, ## Context, ## Content and ## Evidence. Its id is
<project>-<type>-<yyyymmdd>-<slug>, its status candidate, admitted or superseded. A mistake also names
its correction and its detection_signal. The body is 2,000 characters at most, and an entry that names a
secret-like file (.env, a key) or holds what looks like a secret is refused. A multi-line applies_when,
rationale, correction or detection_signal is joined on one line when written.
Who may admit what:
| Source | Types it admits |
|---|---|
human: (you) |
every type |
audit: (verdict files of the dev audits) |
code-structure, mistake |
verdict: (a stop of the dev workflow) |
method, decision |
A mistake is harvested from the audits only once its gap recurs in three batches or more. The audit of /dev-batches harvests after
every verdict that is not VALID: the candidates it writes are named at the end of the step, and /memory admit decides
each one. When the untreated gaps span two batches or more, the step also says /dev-learn is due.
Precedents in the dev steps
The dev steps recall on their own, at fixed points, and put a ## Precedents block in the prompt they build:
| Step | When | Types recalled |
|---|---|---|
/dev-spec |
at the start | decision, method |
/dev-plan |
before the plan is drafted | decision, code-structure |
/dev-batches |
before the red tests of a batch | code-structure, mistake |
/dev-batches |
a correction after a GAPS verdict | mistake |
/dev-batches |
before the audit | mistake |
The end of the step names the entries recalled. A recall that cannot run costs the block, never the step; a session
rule that denies memory_recall turns these recalls off too.
Deciding the candidates
/memory admit --list
/memory admit --import
/memory admit
/memory admit shop-method-20261024-contract-tests-first
/memory admit --refuse shop-method-20261024-contract-tests-first too local to this project
/memory admit shows each pending candidate (or those you name) and asks once for each: anything but yes leaves it a
candidate. A session that cannot ask admits none of those it would ask about; a question left unanswered keeps the
admissions already confirmed and says which candidates stay. The candidate admitted is the text you
were shown: a file changed since is not admitted, nor one whose topic refused.md holds. The admitted ones are written to entries/<type>/, the entries
they supersede are marked superseded, both lists are rebuilt and entries/ is indexed again, once. When the index
cannot be rebuilt the entries stay admitted, and the next admission indexes them. The lock on the collection
memory-<project> holds within one process only: one REPL runs one /memory admit at a time, but nothing orders it
against a second REPL or a headless run on the same project, so keep to one at a time. Within one REPL, an
admission confirmed while the crew shared-memory-admit still writes the previous one is refused by the runtime,
with that crew's ticket: wait for its result, then type the line again. /memory list|add|get|delete, /feedback
and the other admit verbs are never held back by it. --refuse writes the candidate's
topic to refused.md with your motif: the topic is never proposed again. /dev-learn and its --refuse read and
write the same refused.md, under memory.dir (a stored value set aside is said), the file memory_push reads too.
--import lifts the harness's agent memory into candidates, once, while you move from it: each top-level item of a
.claude/agent-memory/<agent>/MEMORY.md (and the note it links to, in the same folder) becomes a method candidate
whose source is the import, so /memory admit asks for each one (its type is part of its id: a lesson of another kind
is refused with --refuse and pushed again with memory_push under another title: a refused topic is never proposed
again, the push included). An item whose topic (its title as a slug) a pending candidate, an entry or an earlier item
already holds is skipped as a duplicate; an item whose topic was refused is reported refused and writes nothing, and
so is an item whose note or line holds a secret anywhere, before the note is cut:
running the import again writes nothing new while its candidates are still there. Nothing is written under .claude/.
The tools
memory_recall returns at most five admitted entries for a query, best first, with what they apply to and their file:
it reads, and runs in every mode. memory_push writes a candidate, never an entry: it is offered only where the mode
edits, and asked about in default (Permissions). Two concurrent pushes never lose one: a
push that finds its candidate overwritten writes it again under the next id. In every mode, the file tools of the model
that name one path are refused under candidates/ and entries/: candidates come from memory_push and the harvests,
entries from /memory admit (the shared memory's guard, Permissions: the gate's rules, then the callback of the main loop and
of the dev crews for what the gate cannot read - another letter case, edit_batch, structural_rewrite, a cd). An entry the model recalls is a precedent,
not an instruction: the request, the project's instructions and the code as it is outrank it.