brethof-brain docs

Quickstart

Three steps, one of them optional

One account powers every agent you run, on every machine you run it on.

1

Get a key

Create your account at brethof.ai/account, choose where your memory lives — local (your own machine) or hosted (our cloud, encrypted, in Germany) — set your passphrase, start the free plan, and create an API key. No credit card. The local-or-hosted choice is made once; plans and packs can change any time.

2

Connect your agent

Pick your platform below. Most of them are one line — and on any of them you can simply say “install brethof-brain” and let the agent do it. Local edition: Docker or Podman on the machine and about 3 GB of disk, including the memory model, downloaded once; no elevated privileges.

3

Check it, if you want to

Ask your agent to search memory for anything, even something trivial. A well-formed answer — even “no results” — means you are connected. That is the entire test.

a plugin — installed in one step, no clone, no pip

Proven on Linux and Windows

# In Claude Code:
/plugin marketplace add BrethofAI/brethof-brain-client
/plugin install brethof-brain@brethof
# Then the plugin's connect window opens on your screen: paste your key
# (hosted: and your passphrase). Your agent never sees either.
# Recommended: add the memory block from the plugin README to
# ~/.claude/CLAUDE.md, so "remember this" lands in the Brain.
# Done — briefed at session start, recall on every prompt, every
# exchange archived and learned from.

Installed but seemingly unused? Where a platform takes hooks, memory is pushed to your agent and nothing needs teaching. Where it does not, the setup writes a memory section into the platform's own context file, so the agent knows to pull. If memory looks connected but the agent never reaches for it, that file is the first thing to check.

What it writes on Claude Code

On Claude Code, the pip install (brethof-brain install-hooks) keeps one managed block in your CLAUDE.md, rewritten at every session start. It is a pointer, not a copy of the teaching — it tells your agent that memory is the Brain, how to reach it, and that when you say “remember this” it goes to the Brain, not to Claude Code’s own memory files on one machine. The real teaching arrives at session start. It never touches anything outside the block: your own conventions stay yours. To turn it off, set BRETHOF_BRAIN_NO_CLAUDE_MD=1. The plugin never writes it: with a plugin install, paste the block from the plugin’s README into ~/.claude/CLAUDE.md, or ask your agent to.

Commands and versions

The Claude Code plugin ships three commands: /recall (search now), /onboard (a project’s first minute) and /curate (close a session). There is nothing to run by hand — the memory curates and tidies as records land.

Keys & projects

Two things to know before you start

🔑

Keys

Hosted keys are created, edited and revoked in the account panel; creating one needs two-factor authentication or a sign-in with GitHub or Google. One key can serve many agents on many machines. A hosted key can be scoped: limited to chosen projects, read-only or read-write. That is the right shape for a contractor or a single-purpose agent. The local edition has one full-access key, made by its installer.

Projects

Just names. Pass a project when saving or searching and it exists from that moment — no setup, no limit on how many, on any plan including Free. Use one per codebase, client or venture. Your agents can search inside one project or across all of them, and a shared layer above them holds the few facts true everywhere.

How it works

It learns without being asked

Nobody summarizes sessions here, and you never run a “save my context” ritual. When you correct your agent on Tuesday, every agent knows on Tuesday.

A curator that reads the conversation, not the message

Correct your agent once and you never correct it again — that agent’s next session knows it, every other session knows it, on every machine. The memory reads your conversation in stretches of five exchanges, so it keeps what the conversation settled, not each half-thought on the way: decisions saved, outdated claims retired. A record may land a few exchanges behind you — the last exchanges of a session become memory when you compact or when the next session in that project starts. You never file anything. When you do want something kept on the spot, say so — your agent saves it directly, which is useful when precision matters or a fact belongs to another project.

Two stores: the truth and the recording

Saved memory is the current truth — curated, dense, up to date. Conversation history is the complete raw recording of everything ever said. When your agent needs what the team believes now, it searches memory; when it needs the exact error message from three weeks ago, it searches history. Old statements in history are snapshots of their moment. Memory is what is true today.

The graph is the memory of decisions

The decision graph gives every move a dated line — decided, tried, rejected, dropped — each with its reason, in the words of the conversation. A reversal is a new line; the old way stays on record as the old way. So when a search touches the topic, the line saying the idea died in March comes back with the day and the reason, and your agent does not re-propose it. This is what the pile of AGENTS.md and CLAUDE.md files can never do: they don’t know an idea died, so it sits there as current truth, waiting for a fresh agent to walk into it. The graph reaches back to the day your memory started reading, and it is part of every plan, on both editions.

Recall is never metered and never stops at a limit. Searching, session-start context, per-prompt recall and the graph’s history lines are not counted against an allowance and you are never billed by the search — on any plan, Free included. Plans meter two things and only two: how much your memory holds, and how much it learns each month. Spend either and what pauses is new recording or new learning — your stored memory goes on answering.

Day to day

The honest answer: you don’t

Once the plugin is in, there is no ritual to learn and no command to remember. The best sign it is working is that you stop thinking about it.

What changes is how you talk to your agent. You can now say things like “what did we decide about the payment retries?” or “remember that the staging box is the one with the old certificate” — in plain language, mid-conversation. Your agent picks the right tool; you never name one.

What your agent can reach for

You do not need this list. It is here so you know what is possible when you ask for something specific.

Find things — search your curated memory, or the raw conversation history when you need the exact words from a past session.
Remember things — save a fact to a project, or to the shared layer that spans all of them.
Teach things — save a rule, or start a project with a sentence describing what matters in it.
Inspect things — list your projects, list what a project knows, list its rules, or read one record.
Remove things — delete a single record. Redacting an exact phrase or deleting a whole project happens in the account panel.
Review the ledger — see a project’s pile of undecided intentions, remove rows as you decide them.
Keep playbooks — save a procedure once, account-wide; fetch and run it from any project; list what exists; delete what is dead.

One thing an agent deliberately cannot do: delete an entire project. That single act reaches the raw archive, so it lives in your account panel, where a human types the name.

The Brain Ledger

Nothing you said gets lost

As your conversations are archived, the Brain watches them for intentions — things you said you’d do and didn’t. Each becomes one row in that project’s ledger: undecided, waiting for you. No statuses, no archive. A row waits, gets dropped, or becomes work.

The review

Say “check the ledger” in any session. Your agent brings the rows up one by one and you answer in single words. Decided rows are removed on the spot. Rows the later work shows done, dropped or overtaken have already left by themselves.

🏃

From rows to the plan

A row that still matters becomes one line in the project’s plan — Next or Parked — and leaves the Ledger; the rest dies. The plan opens the next session, so the work is in front of your agent when it starts. How the plan works.

Two habits make it sing. Review often — a pile visited daily stays a handful of rows. And delete brutally — nothing is lost, because an idea that still matters will be said again, get re-filed, and be judged fresh against the project as it is then.

Brain Playbooks

Procedures every agent shares

A playbook is a procedure written as a markdown document and stored once for your whole account. Any of your agents, in any project, on any machine, can fetch it and run it in its own environment — the Brain stores and serves; your agent executes.

✍

Writing one

Ask your agent to save a playbook, and shape it like a runbook: headings for the stages, fenced code blocks for the exact commands, and a one-line annotation saying what it does — that line is what shows up when agents browse the list. Saving under the same name replaces the previous version, so a playbook is always exactly one current document.

▶

Running one

“Run the deploy playbook” is the whole interface: the agent fetches it and follows it where it stands. Pair it with a schedule for the full effect — an agent that runs “fetch the weekly-report playbook and execute it” on a cron becomes a job you wrote once in plain English and never look for again.

Rules

Teaching your memory

Everything else your memory holds is found when searched. A rule is different: a standing instruction that loads into every session automatically, without anyone looking it up.

Rules are how you stop repeating yourself — the conventions, constraints and hard-won corrections your agents must never forget. Good ones sound like laws: “never deploy on Friday,” “this project uses tabs, not spaces,” “the client’s name is spelled Brethof, never Brefoth.” Short, absolute, and still true next month.

Ask your agent to save a rule and it asks you one thing: is this for everything you do, or just this project?

🌎

Every project

A law that binds all your work, everywhere it happens.

📌

This project only

A law for one codebase, client or venture.

💡

Neither — it’s knowledge

Useful, but it does not need to be in front of you at all times. Still saved, still found the moment anyone searches for it.

That third option is the important one, and it is chosen more often than the other two. A rule is expensive: it occupies room in every session forever, and it teaches the curator what matters. Filing ordinary knowledge as a rule is exactly how a memory silts up until nothing stands out.

Rules teach the curator, not just the agent

A project with a handful of sharp rules remembers noticeably better than one with none — because the rules tell its curator what matters there. Save one and, within minutes, that project’s memory has re-learned what the project is.

Keeping them sharp

A rule should be short enough that you would still say it out loud — if it does not fit, it is probably knowledge wearing a rule’s clothes. Merge duplicates into one, and delete rules that have gone stale; nothing prunes them for you, because nothing else should be allowed to decide what your laws are. A dozen rules you believe in beat fifty you have stopped reading.

Projects in practice

The only real decision is how you slice them: one per codebase, client or venture is the pattern that works. Too few and unrelated work bleeds together; too many and context scatters. Starting a project with a one-sentence purpose — what it is and what should be remembered there — is the single highest-value minute you can spend. It teaches the curator from day one instead of leaving it to infer your intent from fragments.

Space & usage

What a limit stops — and what it never touches

Your stored memory keeps answering, whatever else is capped. Recall is the one thing a limit never takes away — and so are the brief that opens every session, the rules and records that arrive on every prompt, the full chat history, the graph, notes and playbooks.

Three different things are metered differently, and it is worth knowing which is which. Recording is limited by storage. Learning is limited by your monthly allowance. Recall is limited by neither — searching, session briefings and per-prompt recall keep working for as long as your memory is on our live systems.

When the month’s learning is spent

Your history keeps being recorded, and all of it stays searchable. Recall keeps working — briefed at session start, matching memory on every prompt, the graph. What stops is learning: no new memories are distilled from your conversations, and the graph stops growing. A top-up pack or an upgrade starts it again.

🗃

When storage is full

Nothing new is saved — that is what full means. Recall keeps working across everything already stored, so your agent is still briefed and still remembers what it knew yesterday. Add storage or move up a plan, and recording resumes where it left off.

⏹

When both bite at once

No recording, no learning — and recall still works. If you hear that your Brain is off, it is off for new memory only. Everything already in it answers exactly as it did before, and your agent goes on using it.

If the subscription lapses

The Brain pauses immediately — there is no grace period. Your memory is archived after day 7, you are warned around day 23, and it is removed on day 30. A paid, active account is never touched. The full schedule, and the emails that come with it, are in the Privacy Policy.

The gap a limit leaves, and why we never fill it in

While a limit is biting, no new memories are distilled. That leaves a gap in your memory covering that period, and we do not go back and fill it in afterwards. That is a deliberate design law, and you should know it.

A memory is only ever made from a conversation as it happens. A record written later, from material already weeks old, would overwrite what has been true since — and your memory would start confidently asserting things that stopped being true. We would rather leave a hole than manufacture a confident lie.

So, plainly: the gap is permanent as memory. Your raw conversation history from that period is still there and still searchable, so the record is not lost — only the distilled layer has the hole. The longer a limit runs, the further your memory drifts from the work you are actually doing. And it does not repair itself when you resume: your agent corrects outdated memories as it meets them, and the memory reconciles new records against old ones as they land, retiring the ones your newer memories contradict. Both of those run forwards, never backwards.

Nobody is cut off quietly. You get an email as you approach a limit and another when it bites, a notice inside your agent’s session when it starts, and a short line on every prompt while a limit is active.

Cleaning up old history

Your raw history stays protected where it matters: recent history cannot be removed by anyone, and individual messages cannot be quietly deleted — but you can redact an exact phrase, delete a single record through your agent, or remove a whole project from the account panel, where a human types the name. Deleting anything is free.

⇆

Changing plans

Upgrades apply immediately. Downgrades apply once your memory fits the smaller plan — prune, or keep the add-on until it does. Nothing is ever deleted by us, on any plan change.

FAQ

Frequently asked questions

Hosted, your memory is encrypted under a passphrase only you hold: while locked, it is ciphertext to everyone, including us. It is stored and searched in Germany; the processing pass runs on secure compute in Switzerland; and one model pass goes, transiently, to a provider contractually committed not to retain or train on what passes through — we state that as their commitment. Local, your memory lives on your machine. Our hub processes pieces of it as they are sent up and stores none of it — the only things it holds are your standing rules and one line per project. The memory and the search stay on your machine.

That is the point. Every agent using your keys reads and writes the same memory, kept consistent turn by turn — five agents on one project see one truth. On hosted memory, scoped keys let you give a person or an agent access to only chosen projects, read-only or read-write.

Claude Code, Codex, Qwen Code, OpenClaw, DeepSeek Harness (dsh), Cline, OpenCode, Kilo Code and Hermes Agent. A platform is listed only when the whole loop works there — briefed at session start, matching memory pulled in on every prompt, and the conversation archived. There is no half-supported tier, because a half-working platform would be somebody’s only platform. More are wired and waiting on vendor accounts; they appear here the day they are proven, not before.

No. One brethof-brain key is all any agent needs, and your agent can install the whole thing itself — say “install brethof-brain” and it is done. Hosted, we run everything. Local, it runs in one container on your machine.

Yes — ask your agent, or use your account panel. Those are the two doors into your memory, and deletion works through both: export the whole history, delete a project, redact an exact phrase, or delete the account — from the panel, behind your own identity, even without your passphrase. Some of it is deliberately limited: the protections that stop an agent erasing your past apply to you as well, and the Security page sets out exactly where the lines are.

Each project’s pile of undecided intentions — things you said you’d do in conversation but didn’t. Ask your agent to “check the ledger”, decide each row in a word, and move the keepers into the project’s plan. The section above has the detail.

Stay in the loop

Hear it when it ships

New releases, real benchmarks and the occasional deep-dive. No spam, unsubscribe in one click.

The Brethof network

Docs