Memory and knowledge

Shared Brain Memory

Shared Brain Memory is the vault-native remember, recall, and answer layer.

Recall is tiered by default: typed Agent Memory first, then relevant Markdown from the whole vault when the top memory hit is weak. Use --scope agent-memory for typed memory only, or --scope full-vault to force broad recall. detail (abstract, overview, or the default full) controls how much of each memory comes back, and mode: "hierarchical" scores folders before notes. Neither changes ranking.

The prompt hook runs hive-brain answer for each prompt, returns Claude’s additionalContext JSON, and fails closed if recall is unavailable. It never writes memory. Each prompt is searched together with the words of Claude’s previous reply, so a short follow-up such as “do all 3” finds what it refers to. With Turbo mode on, notes that are clearly about something else are left out, whether or not the desktop app is open. When a program saves one note per run (for example one per paper trade), an answer includes at most one of them; hive-brain consolidate --apply-rollups replaces a long run of them with one summary and archives the rest, which stay readable.

Recall finds notes by meaning as well as by their words, so a past conversation that answers a question in other words can still come back. Conversations are added to that search a minute or two after they go quiet, and hive-brain consolidate adds any older ones. For a question where the order of the results matters, hive-brain recall "question" --rerank has the top results read again against the question and puts the best first. It takes about a second longer and uses your OpenRouter account; with Turbo mode off it does nothing. hive-brain can also save a memory while the desktop app is closed; if the write cannot finish, it stays pending and the command says so.

hive-brain answer "what does the user prefer here?"
hive-brain recall "BYOK Agent Calls" --scope full-vault --limit 5
hive-brain remember --type preference --title "Short title" --content "Durable memory body" --memory-key "preference/project/short-title"
hive-brain evolve --memory-id mem-... --content "Updated durable memory body"
hive-brain get --memory-id mem-...
hive-brain update --memory-id mem-... --title "Corrected title" --status archived
hive-brain delete --memory-id mem-... --confirm
hive-brain batch --file ./memories.json
hive-brain browse --path Projects --detail overview
hive-brain record-operation --title "Provider request" --content "Request timed out" --operation-key "provider/request" --failure-key "provider/timeout" --outcome failure --task-id task-123
hive-brain mine-patterns
hive-brain repair-conflicts --confirm
hive-brain generations
hive-brain replay "what did we know about Atlas?" --generation <generation-id>
hive-brain compare "Atlas launch" --from-generation <generation-id>

• update fixes wording, tags, project, confidence, or archived status in place. When the underlying truth changed, use evolve so the history records it.
• delete is permanent, needs --confirm, and refuses to break an evolution chain unless you pass --force.
• batch writes up to 25 records under one lock and one published generation; each record passes the same duplicate and sensitive-content checks.
• browse reads short folder summaries (about 100 or 2,000 tokens) built during each index rebuild, so an agent can find the right area before opening notes. Folder-first recall only re-ranks; it never hides a note.

API actions

/api/brain/memory supports:

• remember, evolve, get, update, delete, and batch: write and manage typed memory.
• recall: search by query, type, tags, project, optional scope, optional temporalMode, optional asOf, optional includeOperational, and optional usage tracking.
• answer: return a grounded context pack from matching memories and notes.
• browse-directories: return folder summaries.
• record-operation: log an operational event without writing durable memory. remember-action is a compatibility alias and returns durableMemoryWritten: false.
• mine-patterns: return review candidates from operational events; enqueueProposals: true adds them to Brain Review.
• record-usage: log retrieved or final-answer usage for memory ids.
• rebuild-index, repair-index-conflicts, list-generations, and compare-generations: maintain and inspect generated indexes.
• export-capsule, open-capsule, search-capsule, preview-capsule-import, and propose-capsule-import: portable capsules.
• proof: true or proof: "auto": attach a hash-only GitLawb memory receipt.

A chat request to remember or “teach the hive” creates a Brain Review proposal with conversation evidence. A reviewer approves and applies it before typed Agent Memory changes.

Memory layers

Typed memory has three layers, in one index:

An agent keeps its own lessons, environment quirks, and procedures in its private layer, so one agent’s wrong conclusion stays with that agent instead of becoming what every agent believes. Recall returns the shared layer plus the caller’s own private and task layers. Running inside Claude Code or Codex, or with HIVE_AGENT_ID set, hive-brain remember saves to that agent’s private layer; --memory-scope hive asks for shared memory instead.

Every HivemindOS agent keeps to these layers. They are enforced against an agent that ignores them only when each agent signs in with its own identity (HIVEMINDOS_AGENT_SCOPED_PERMISSIONS=1); then an agent can read and change only its own private memory, and maintenance actions such as consolidate are yours alone.

A private memory can name a shared one in overrides, and then replaces it for that agent only. It can never replace an instruction, preference, or decision you stated yourself; that pair is reported as a conflict instead.

Knowledge moves up by promotion. When two or more agents learn the same thing separately, or answers keep using one agent’s lesson, the app queues it for Brain Review once a day. You decide what becomes shared. hive-brain consolidate --propose-promotions runs the same pass on demand, and hive-brain health counts memories per layer.

Core memory

Every agent session starts with core memory, instead of hoping a keyword search finds it:

• Memory/Core Memory.md: who you are, how you work, and rules that always apply. Setup seeds a short template; keep it under about 3,000 characters.
• The agent’s own Agents/<agent-id>/Core Memory.md, if it has one.
• Standing rules drawn from typed memory: shared instructions, preferences, and decisions you stated or that answers keep using, plus the agent’s own most-used lessons.

Claude Code receives it through the hive-brain-hook SessionStart hook; app chats receive it with each turn’s recall. hive-brain core prints it.

Canonical memory and evolution

Every durable record carries a canonical memoryKey, derived from type, project, and title unless the caller supplies one. remember refuses a second active record with the same key. When reviewed truth changes, hive-brain evolve (or action: "evolve") writes the new note and marks older ones superseded in one journaled transaction. Current recall returns the newest active head and includes prior versions as evolutionChain evidence when relevant. A memory that an active note names in supersedes stays superseded even if sync brings back an older copy of its own note.

Temporal intent is conservative. “Used to,” “previously,” and “historical” ask for history; “as of ," "before ," and relative periods set a cutoff. A date in a memory title or the word "before" in a procedure does not change current recall.

Ranking combines exact, title, tag, and content matches, query coverage, question intent, BM25-lite lexical scoring, entities and aliases, confidence, time fit, recency, status, optional semantic similarity, full-vault evidence, and usage signals, reported in scoreDetails. Long notes, such as saved conversations, also score by their best-matching passage, so the few lines that answer a question are not drowned by the rest of the note. Longer questions need proportional term coverage, so answer mode can abstain instead of stitching together unrelated fragments, and answer mode drops notes that score far below the best match.

Operational events and pattern mining

Routine completions, handoff receipts, and retries go to a bounded local journal outside the vault:

~/.hivemindos/brain/operational-events.jsonl

It rotates to one .1 file at 8 MB, so receipts never crowd durable recall. Legacy action memory notes are kept but hidden from default recall.

Pattern mining groups events by operation and failure keys across distinct tasks, rejects test noise, and suggests recurring failures, workflows, and routines. It is a dry run by default; --enqueue only creates Brain Review proposals. Run pnpm benchmark:agent-memory-pattern-mining to reproduce the fixture benchmark.

Generated files

Indexes are built on each device from the notes and kept outside the vault, in ~/.hivemindos/brain/state/<vault-id>/Operations/Brain Services/. Sync carries only notes, so two devices never fight over an index file, and a new device builds its own on first use.

Typed memory notes live in Memory/Distillations/Agent Memory/; they stay the durable source. Every index can be rebuilt from Markdown. When a note is edited, archived or deleted on another device, this device’s index follows within a few seconds of its next recall. Usage history and embeddings are per device too: a device keeps what it had when it upgraded, and from then on counts its own use and embeds new memories itself. Search handles accented and non-Latin text, including Chinese and Japanese. Set HIVEMINDOS_BRAIN_STATE_DIR to keep device state somewhere else.

Durable writes, generations, and replay

Writers share a cross-process lock and stage each multi-note change in the transaction journal. Source notes are promoted first, then a verified index generation is published under the device’s Index Generations/agent-memory/ or full-vault/, and the current pointer moves last. After a crash, the next writer finishes staged files and rebuilds from Markdown. If the current generation is corrupt, readers fall back to the newest verified older one.

Generations are stored as periodic checkpoints plus content-addressed deltas, each with a SHA-256 receipt.

Pruning removes only generated history, never Markdown notes, and only at a verified checkpoint. Each index writes coverage.json after its first prune. hive-brain generations shows the policy and the earliest generation that can still be replayed. hive-brain replay answers from one retained snapshot as it was, and hive-brain compare shows what changed between two. If coverage data is damaged, pruning pauses instead of guessing.

Exact duplicate memories are blocked by content hash. Optional embeddings are tied to their exact model and settings, and stale vectors are ignored rather than compared.

Portable brain capsules

A capsule is one file with selected memories, optional Compiled Knowledge, provenance, checksums, and a small read-only search index. Export needs an explicit project or memory-id scope. Capsules can expire and can be encrypted with AES-256-GCM using a passphrase from a named environment variable. Plain checksums catch corruption but do not prove the sender; encrypt when tampering or expiry matters. Only you can lock a capsule with a passphrase or open a locked one; agents and apps use unlocked capsules of shared notes. Importing only creates Brain Review proposals.

hive-brain capsule-export --project atlas --compiled-domain atlas
hive-brain capsule-export --memory-ids mem-... --passphrase-env HIVEMINDOS_CAPSULE_PASSPHRASE
hive-brain capsule-open --capsule <file>.hivebrain
hive-brain capsule-search "launch decision" --capsule <file>.hivebrain
hive-brain capsule-import --capsule <file>.hivebrain --enqueue

Open Knowledge Format export

HivemindOS can export memory and conversation notes as an Open Knowledge Format v0.1 bundle for outside tools, without changing your vault. The bundle holds shared memory only: an agent’s or a task’s private notes stay out, for you and for agents alike, because the bundle sits in your vault, where every agent and device can read it. It holds current notes only: a note that was replaced or archived stays out, and its replacement is in. Each file is named after its note’s title plus a short code, so notes that share a title each keep their own file, under the same name every export. Use POST /api/brain/okf with action: "export" (optional include: "agent-memory" | "conversations" | "all", outputPath, clean) or action: "validate". The default output is Operations/Brain Services/OKF Export/.

The bundle is a snapshot. A note or chat you delete, and a note that is archived or replaced, leaves the bundle in Operations/Brain Services/OKF Export/ straight away, but new notes appear only at the next export. A bundle written to another folder is not kept up to date; export again to refresh it.

Conversation notes

When the shared vault is enabled, each finished chat is saved as one redacted note under Memory/Conversations/<agent>/. Automation transcripts and sessions without a reply are skipped. Because these are normal vault notes, “check our conversations about X” works for every agent.

Questions asked of memory on purpose (hive-brain answer, the brain_answer_memory MCP tool, or recall) return whole matching conversations, oldest first, up to 60,000 characters. Phrases like “two weeks ago” or “last Saturday” find conversations from those dates, and each one is labeled with its date.

Full-vault recall includes normal Markdown in Memory/, Projects/, Synthesis/, Ideas/, Operations/, Skills/, and templates. It includes Operations/Secure/ status notes so agents know which key names are set, never their values. Content search uses the generated index first, then rg, then grep.

Local-First Memory Benchmarks

Typed recall reads a local index inside the vault, so it needs no network call. When memory is weak, full-vault recall uses the generated BM25-lite lexical index and loads only the top candidate notes.

Synthetic scale fixture, 200 queries per size, local embeddings off:

Reproduce it with pnpm benchmark:agent-memory-scale -- --calls 200, and the full-vault search benchmark with pnpm benchmark:shared-brain-search (add --vault <vault> for a live vault). In smoke tests, raw Claude and raw Hermes recalled both a typed memory and a project note outside Agent Memory, Projects/Agent Calls - BYOK vs HivemindOS Cloud.md. See Shared Brain Memory Benchmarks for all results, sample sizes, and limits.

Obsidian Native Brain Pack

Setup installs four shared skills so agents write files Obsidian opens natively: obsidian-markdown, obsidian-bases, json-canvas, and defuddle (curated from kepano/obsidian-skills). Fresh vaults also get these views in Operations/Brain Services/:

Compiled Knowledge

Compiled Knowledge turns reviewed sources and conclusions into topic wikis under Synthesis/Compiled Knowledge/<domain>/. Each domain has raw/ inputs and a wiki/ with entities/, concepts/, summaries/, index.md, and log.md.

Agents use it through /api/brain/knowledge or hivemind-mcp tools such as compile_brain_knowledge, brain_search_knowledge, brain_graph_overview, brain_get_node, brain_get_backlinks, scan_brain_wiki_health, fix_brain_wiki_issue, and shared_brain_contract. A page an agent compiles waits in Brain Review until you approve it; your own are written straight away.

For shared brains with several people, contributors write to their own domains and a synthesis step rebuilds the shared shared-* mirror. Direct writes to that mirror are refused in collaborationMode: "human-collective". Agent-to-agent work is unaffected.

Compiled Retrieval Snapshot

Synthetic 720-page wiki with 1,440 links (pnpm benchmark:compiled-knowledge). Real timings depend on your vault and disk.

Queen Bee control plane

Queen Bee coordinates one logical assistant identity across many machines. Its state lives in Operations/Brain Services/Queen Bee/. It reuses existing tools rather than replacing them: tasks stay on the Work Board, memory stays in Agent Memory, machine capability comes from fleet discovery, and handoffs use .hivemindos-transfers/.

When a request arrives, Queen Bee ranks online agents across all machines and creates or reuses a Work Board card for the best available agent and machine. For code work it checks the project registry: collectors can report version.projects entries for each checkout, and routing prefers the machine whose checkout matches, is up to date, or holds local changes. Route reasons show the evidence, for example GitLawb project registry matched .... If no suitable agent is online, the card waits for Queen Bee.

Context index

The context index helps agents find the right code, tools, skills, apps, and commands without loading huge files. Connector entries show key names only. For example, /swarm-goal <build request> is indexed as the path for build requests that Queen Bee should split across parallel agents.

Optional services

• Brain Graph reads vault links and access logs to show how notes relate and what agents used.
• GBrain adds optional semantic search and graph tools. Service note: Operations/Brain Services/GBrain.md.
• Syntho compiles reviewed Synthesis/ material. Raw-source access stays denied unless you change it. Service note: Operations/Brain Services/Syntho.md.
• Trading Brain is a domain add-on for selected runtimes.

QMD

QMD is an optional local Markdown search service. From Brain Services, HivemindOS can install the @tobilu/qmd CLI, add the vault as a collection, refresh its index and vectors, and run BM25, vector, or hybrid search. Its generated files stay in your local QMD cache; the vault gets only its service note, Operations/Brain Services/QMD.md.

Implementation: src/lib/services/brain/qmd.ts and /api/brain/qmd/*.

Neo4j

Neo4j is an optional derived graph. Agent Memory in your vault stays canonical. HivemindOS connects to your existing database using key names only (NEO4J_URI, NEO4J_USERNAME, NEO4J_PASSWORD, NEO4J_DATABASE), syncs derived nodes with MERGE, and runs read-only Cypher queries. Sync never deletes your own Neo4j data; any future cleanup touches only nodes marked source: "hivemindos-derived". Service note: Operations/Brain Services/Neo4j.md.

Service notes

Service notes may record status, install mode, command names, policy, required key names, and repair tips. They must never contain secrets, private keys, tokens, Tailnet addresses, or machine-only paths.