brain-memory

v0.4.0

Published

6 days ago

A brain-inspired hierarchical memory system for AI coding agents. Deep nested file structure that mimics human memory with time-decay and strength-based recall.

Downloads

604

0High
0Medium
0Low

onurkarali

claude-code gemini-cli openai-codex opencode memory ai-agent context-engineering hierarchical-memory neuroscience spaced-repetition file-based slash-commands

A hierarchical, file-system-based memory plugin for AI coding agents. Inspired by human neuroscience — memories are organized into deep nested life-domain categories, connected via associative networks, strengthened through spaced recall, and naturally decay over time.

One hosted MCP connector reaches every major agent and chat app — Claude Code, OpenAI Codex CLI, OpenCode, GitHub Copilot CLI, Kilo, the Claude.ai apps, ChatGPT, Google Antigravity (Gemini CLI's successor), OpenClaw / NVIDIA NemoClaw, Hermes Agent, and Goose. Prefer a free, local-first install? The native plugin runs entirely from ~/.brain/ on Claude Code, Codex, OpenCode, Copilot CLI, Kilo, and Antigravity — and dedicated native integrations plug the same brain into OpenClaw and Hermes as their memory engine.

~/.brain/
├── professional/
│   └── companies/
│       └── acme-corp/
│           └── projects/
│               └── alpha-launch.md        ⚡ 0.88
├── personal/
│   └── education/
│       └── typescript-generics.md         ⚡ 0.72
├── social/
│   └── communities/
│       └── open-source-contrib.md         ⚡ 0.65
└── family/
    └── events/
        └── annual-reunion-planning.md     ⚡ 0.55

Why Brain Memory?

Existing AI memory solutions use flat databases with tag-based retrieval. Brain Memory is different:

The directory tree IS the semantic structure — professional/companies/acme/projects/ tells the agent everything about context without vector search
Human-inspectable — Browse your "brain" in any file explorer
Git-friendly — Full version history of how memories evolve
Strength + decay — Recalled memories get stronger, forgotten ones fade. Just like your brain
Recall receipts — Memory that visibly fires: every answer shaped by a memory ends with a one-line attributable receipt (◉ memory: "<title>" (<type>, <age>)), minted by the engine so it can't be hallucinated
Provenance-bounded trust — Every memory records where it came from (user, agent-inferred, tool-output, external), and recall weighs it: a fact planted by a web page or tool output is down-ranked, flagged low_trust, marked ⚠ on its receipt, and can never outrank what you said directly — no matter how many copies of it get written. And because memories are plain files, Brain records a SHA-256 baseline of each one at write time — so brain audit also catches a memory edited outside any write path, the one poisoning route every write-path defense is blind to
Bitemporal — it knows when a fact was true — Every memory separates record time (when the brain learned it) from valid time (valid_from / valid_until, when it was actually true). So "we deploy to Fly.io" and "we deploy to Render" aren't a contradiction to guess between — they're one fact with a boundary. brain recall "deploy target" --as-of 2026-03-01 answers what was true in March; --as-known-of answers what the brain knew then. Facts that stopped being true are demoted and marked ⌛ expired, never silently served as current
Deterministic recall — every agent ranks identically — Scoring is arithmetic over files, not a model call: TF-IDF/BM25 relevance, decayed strength, spreading activation, context match, salience. Claude, Codex, and Gemini asking the same question of the same brain get the same ranking, in the same order, offline. No embedding-model version can silently reshuffle what your agent remembers
Associative network — Memories link to each other with weighted connections. Recalling one activates related ones automatically
Context-dependent recall — Memories encoded in a similar context to the current session are scored higher
Spaced reinforcement — Memories recalled after longer intervals get bigger boosts, cramming produces diminishing returns
Cognitive types — Episodic, semantic, and procedural memories each decay differently, just like in the brain
Always-present knowledge — Pin critical conventions and preferences so they load every session, bypassing recall and never decaying — the facts your agent must never miss
Procedural skills — Reusable how-to workflows with progressive disclosure, learned automatically from repeated experience and exportable to your agent's native skills
On-demand depth — Subcategories are created as needed, not pre-defined
Consolidation — Weak related memories merge into stronger combined knowledge
Zero dependencies — and measured, not assumed — Pure file I/O: no database, no server, no embedding model. That is a deliberate result, not a shortcut. On our hardest retrieval scenario (1,021 memories, 1,000 plausible distractors) a real embedding model ranked the target memories worse than BM25 — see the retrieval-only pilot

Install

There are two ways to give an agent its brain. They are complementary — most people end up with both:

| Path | Reaches | Storage | Cost | Best for | |------|---------|---------|------|----------| | Hosted MCP connector | Every MCP-capable host (Claude Code, Codex CLI, OpenCode, Copilot CLI, Kilo, Claude.ai apps, ChatGPT, Antigravity, OpenClaw, Hermes, Goose) | Brain Cloud (hosted) | account | One connector, everywhere — including web & mobile chat | | Local-first native plugin | The current CLIs (Claude Code, Codex CLI, OpenCode, Copilot CLI, Kilo, Antigravity) | ~/.brain/ on your machine | free | Zero-config ambient memory, no account, files you own | | Assistant integrations | OpenClaw / NVIDIA NemoClaw (memory-slot plugin), Hermes Agent (memory provider) | ~/.brain/ on your machine | free | Your always-on personal assistant sharing one brain with your coding agents |

1. Universal path — the hosted MCP connector

Brain Cloud exposes a single remote MCP server (streamable-HTTP + OAuth) at https://mcp.brainmemory.ai/mcp. Add it once per host and that host can recall, memorize, pin, and check status — no local install, no per-project setup. It works everywhere MCP does, including the chat apps that can't run a native plugin.

# Claude Code
claude mcp add --transport http brain https://mcp.brainmemory.ai/mcp

# OpenAI Codex CLI
codex mcp add brain --url https://mcp.brainmemory.ai/mcp

Codex CLI (config file) — add to ~/.codex/config.toml:

[mcp_servers.brain]
url = "https://mcp.brainmemory.ai/mcp"

OpenCode — add to opencode.json:

{
  "mcp": {
    "brain": { "type": "remote", "url": "https://mcp.brainmemory.ai/mcp" }
  }
}

Claude.ai / ChatGPT — Settings → Connectors → Add custom connector, paste https://mcp.brainmemory.ai/mcp, and complete the OAuth sign-in. (ChatGPT requires a paid plan or Developer Mode.)
Google Antigravity — add to mcp_config.json under the serverUrl key. (Legacy Gemini CLI used the httpUrl key in settings.json.)

GitHub Copilot CLI — add to ~/.copilot/mcp-config.json (OAuth via /mcp auth brain in-session):

{
  "mcpServers": {
    "brain-memory": { "type": "http", "url": "https://mcp.brainmemory.ai/mcp", "tools": ["*"] }
  }
}

OpenClaw — openclaw mcp add brain-memory --url https://mcp.brainmemory.ai/mcp --auth oauth, then openclaw mcp login brain-memory. (Inside NVIDIA NemoClaw, allowlist the endpoint first — see integrations/openclaw.)

Hermes Agent — add to ~/.hermes/config.yaml:

mcp_servers:
  brain: { url: "https://mcp.brainmemory.ai/mcp", auth: oauth }

Goose — add a remote extension (streamable-HTTP) pointing at https://mcp.brainmemory.ai/mcp.

Kilo — add to kilo.jsonc (OAuth starts automatically):

{
  "mcp": {
    "brain-memory": { "type": "remote", "url": "https://mcp.brainmemory.ai/mcp", "enabled": true }
  }
}

The first time a host connects you'll complete an OAuth sign-in with the Google account that holds your cloud brain; the connector then syncs to every client on that account. See Use Brain in Claude apps for the full walkthrough.

2. Local-first path — the native plugin

npm install -g brain-memory
brain

The first command installs the package globally — this gives you both the interactive setup wizard and the brain CLI (brain recall, brain memorize, brain reinforce, …) that agents rely on for deterministic scoring.

The second command runs the setup wizard, which asks which runtime(s) to configure and whether to install globally or for the current project. Each runtime gets its instructions file plus the brain commands/skills:

| Runtime | Instructions file | Commands land at | |---------|-------------------|------------------| | Claude Code | CLAUDE.md | ~/.claude/commands/brain/ (plugin slash commands) | | OpenAI Codex CLI | AGENTS.md (~/.codex/) + hooks in ~/.codex/hooks.json (SessionStart, UserPromptSubmit, SessionEnd — trust once via /hooks) | ~/.agents/skills/<name>/SKILL.md | | OpenCode | AGENTS.md | ~/.config/opencode/commands/ | | GitHub Copilot CLI | copilot-instructions.md (~/.copilot/), repo-local AGENTS.md | ~/.agents/skills/<name>/SKILL.md (shared with Codex) | | Kilo | rules/brain-memory.md + kilo.jsonc instructions entry (~/.config/kilo/), repo-local AGENTS.md | ~/.config/kilo/commands/ | | Google Antigravity | GEMINI.md | ~/.gemini/skills/ (experimental — verify paths against a live install) |

Plugin install — Claude Code, Codex, ChatGPT workspaces

This repository is also a plugin marketplace. Installing the brain plugin gives Claude Code and Codex the same /brain:* commands plus deterministic hooks: SessionStart injects the budget-bounded brain session-start payload as context (no prompt file to edit, nothing for the model to remember to run) and SessionEnd records the session boundary in ~/.brain/contexts.json. The plugin bundles the CLI, so no npm install is required for the hooks.

# Claude Code
claude plugin marketplace add omelas-tech/brain
claude plugin install brain@brain-memory          # local-first: hooks + /brain:* commands
claude plugin install brain-cloud@brain-memory    # optional: the hosted MCP connector

# Codex CLI — same repo, same two plugins (Codex reads the Claude manifests)
codex /plugins                                    # then add marketplace omelas-tech/brain

ChatGPT Business / Enterprise / Edu: a workspace admin imports the marketplace once (Admin → Plugins → Add → Import marketplace → https://github.com/omelas-tech/brain) and the workspace picks up new versions daily. brain (skills + hooks) serves Codex users in the workspace; brain-cloud (the MCP connector) serves ChatGPT desktop. Import does not grant access by itself — each user completes the connector's OAuth sign-in on first use.

Non-interactive

brain --claude --global    # Claude Code, global
brain --codex --global     # OpenAI Codex CLI, global
brain --opencode --global  # OpenCode, global
brain --copilot --global   # GitHub Copilot CLI, global
brain --kilo --global      # Kilo, global
brain --antigravity --global  # Google Antigravity, global (experimental)
brain --all --global       # All runtimes, global

For the deepest Copilot CLI integration — deterministic session-start context injection via its sessionStart hook — install the Copilot plugin from the brain marketplace:

copilot plugin marketplace add omelas-tech/brain
copilot plugin install brain-memory@brain

Kilo gets the same treatment via its runtime plugin — deterministic session-start injection, session tracking, and BRAIN_AGENT labeling (details):

mkdir -p ~/.config/kilo/plugin
cp integrations/kilo/plugin/brain-memory.js ~/.config/kilo/plugin/

3. Personal-assistant integrations — OpenClaw, NemoClaw, Hermes

Always-on personal assistants get deeper, first-class integrations that make ~/.brain/ their actual memory engine — the same brain your coding agents read and write:

OpenClaw / NVIDIA NemoClaw — a native memory-slot plugin (openclaw plugins install openclaw-brain-memory + plugins.slots.memory: "brain-memory") that replaces memory-core with deterministic brain recall, session-start context injection, and model-driven capture. Also ships a slot-neutral hook pack, a ClawHub skill, and a NemoClaw egress-policy preset.
Hermes Agent — a native memory provider (plugins/memory/brain/) implementing the full MemoryProvider lifecycle: session-start prompt block, pre-turn prefetch, brain_recall/brain_memorize/brain_reinforce tools, and session-context logging. Plus lightweight hook-script glue if you keep another provider active.

Both are backed by the same brain CLI the coding-agent installs use — one memory, every agent.

Update

npm install -g brain-memory
brain update

The first command updates the package and the brain CLI. The second command refreshes the slash command prompts for your installed runtimes. Target specific runtimes with --claude, --codex, --opencode, --antigravity, or --all.

Upgrading from an older version? The separate binaries (brain-recall, brain-memorize, brain-reinforce, brain-cloud, brain-memory) were unified into a single brain dispatcher — use brain recall, brain memorize, brain reinforce, brain cloud <…> instead. Run brain update to refresh your runtime prompts to the new command surface.

Why not npx? npx runs the setup wizard in a temporary directory that is discarded after execution. The brain CLI (brain recall, brain memorize, brain reinforce) won't be available in your PATH, which means agents will fall back to less reliable manual file operations. Always use npm install -g to ensure everything works correctly.

Uninstall

brain uninstall
npm uninstall -g brain-memory

The first command removes slash commands and prompt sections from your agent configs. The second removes the package and CLI tools. Your ~/.brain/ directory (memories) is preserved by default. Add --delete-data to the uninstall command to remove it too. Use --yes to skip confirmation prompts.

Manual Install

If you'd rather wire up the native plugin by hand, copy the brain commands into your agent's folder, then append the matching prompt file to its instructions file.

# Claude Code — flat slash commands
cp -r commands/brain/ ~/.claude/commands/brain/

# OpenCode — flat slash commands
mkdir -p ~/.config/opencode/commands/brain
cp -r commands/brain/. ~/.config/opencode/commands/brain/

# OpenAI Codex CLI — each command becomes a skill under the cross-tool skills dir
for f in commands/brain/*.md; do
  name=$(basename "$f" .md)
  mkdir -p ~/.agents/skills/brain-"$name"
  cp "$f" ~/.agents/skills/brain-"$name"/SKILL.md
done

# Google Antigravity (experimental — verify paths) — skills under ~/.gemini/skills/
for f in commands/brain/*.md; do
  name=$(basename "$f" .md)
  mkdir -p ~/.gemini/skills/brain-"$name"
  cp "$f" ~/.gemini/skills/brain-"$name"/SKILL.md
done

Then append the contents of the corresponding prompt file to your agent's instructions file:

prompts/claude.md → CLAUDE.md
prompts/openai.md → AGENTS.md (Codex, in ~/.codex/)
prompts/opencode.md → AGENTS.md (OpenCode)
prompts/antigravity.md → GEMINI.md (experimental)

AGENTS.md collision (local scope): Codex and OpenCode both read a project-local AGENTS.md. If you install both for the same project, point only one at the local file (or install one globally) so their brain sections don't conflict. Globally they're separate (~/.codex/AGENTS.md vs OpenCode's own config dir).

Commands

The everyday loop is ambient — remember and memorize run automatically at session start/end, so you rarely type a command. The surface is a small core plus a background maintenance job:

| Command | Description | |---------|-------------| | /brain:remember [query] | Recall relevant memories with spreading activation and context matching | | /brain:memorize [topic] [--sync] | Store memories from current session context (add --sync to auto-push) | | /brain:status | Dashboard with brain health metrics and recommendations | | /brain:pin [id\|query] | Pin a memory to the always-present tier — loads every session, never decays. Toggles: also unpins (--off) | | /brain:forget [target] | Decay, archive, or remove memories. --deep performs forensic erasure — traces and removes every reference | | /brain:import [--project P] [--since 30d] | Cold-start a new brain from transcripts your agents already wrote. Incremental — safe to re-run | | /brain:sync [subcommand] | Sync via Brain Cloud, Git remote, or export/import (auto-initializes the brain on first run) | | /brain:skills [list\|show\|add\|use\|remove\|export] | Manage procedural skills — reusable how-to workflows with progressive disclosure | | /brain:sleep [scope] | Full maintenance cycle — 9 neuroscience-inspired phases (replay, consolidation, review reinforcement, pruning, dreaming, …). Usually runs automatically/in the background |

Cold Start

A new brain is empty, and an empty brain is worth nothing until something fills it. But your agents have been keeping local transcripts for months — decisions, preferences, corrections, conventions. /brain:import reads them.

brain import --sources          # what history exists on this machine
brain import --project my-app   # digest that project's past sessions
brain import --since 30d        # or scope by time

The split matters. The CLI harvests — deterministic, budget-bounded, no model call: it extracts session titles, user prompts, projects, branches, and edited files, filters out harness noise and subagent traffic, and interleaves across projects so one busy repo can't eat the budget. The agent then distills that digest into memories through the ordinary brain memorize path.

That split is deliberate. Extracting meaning is a semantic judgement, and doing it in the CLI would mean shipping an embedding model or calling an LLM — the two things Brain exists to avoid. So the harvester reports facts and never infers, and every imported memory lands as agent-inferred provenance: it inherits the existing ceilings for free, and an import can never pin, entrench, or outrank something you said directly.

Import is incremental. A cursor in ~/.brain/.import/state.json records which sessions have been read, so re-running only offers new ones (--all overrides). Nothing is written without you — brain import only ever reads and prints.

Session Lifecycle

Brain Memory works automatically in the background — no commands needed for basic context awareness.

Session Start

When a session begins and ~/.brain/ exists, the agent makes a single brain session-start call. This aggregator returns one deterministic, token-budget-bounded payload so the brain can never bloat the context window (the budget lives in ~/.brain/config.json):

Pinned memories — always-present conventions and preferences, injected verbatim regardless of recall score
Skills index — the name + description of each available procedural skill (~100 tokens each; full instructions are loaded only when a task matches)
Context recall — the top memories relevant to the current project
Review queue + low-confidence alerts, then a brief status line:

◉ Brain active — 42 memories loaded (8 in current project context)
📋 3 memories due for review — reinforced automatically during /brain:sleep

The agent treats pinned facts as active constraints, notes which skills exist, silently internalizes relevant memories, and references them naturally during the session — no information dump.

Ambient Session Tracking

Throughout the session, the agent maintains a running mental log of notable events — decisions made, things learned, insights realized, significant experiences. This is purely internal awareness with no file writes. It ensures that early-session events aren't forgotten by the time the session ends.

Periodic Memory Checkpoint

Every ~10 substantive interactions (file edits, architecture decisions, debugging breakthroughs), the agent evaluates whether memorizable content has accumulated. If so, it appends a brief reminder to its next response:

◉ Notable decisions and learnings this session — /brain:memorize when ready

This never interrupts your flow — it's a one-liner appended to an existing response, at most once per ~10 interactions. The counter resets after you run /brain:memorize.

Session End

When a session ends, the agent performs two steps in order:

Saves session context to ~/.brain/contexts.json — always, even for trivial sessions. This includes a notable_unsaved field listing items you didn't memorize, so future sessions can reference what happened.
Suggests memorization if the session contained meaningful decisions, learnings, or insights:

💡 This session contained notable decisions and learnings.
   Would you like to store them as brain memories?
   Run /brain:memorize to capture them before this context is lost.

The agent never auto-memorizes without user consent. Context is saved proactively — the agent doesn't wait for an explicit goodbye signal.

How It Works

Memory Lifecycle

Create → Store → Decay → Recall → Reinforce → Review → Sleep → Archive
                                      ↑                   │
                                      └── Associations ────┘

Create — When you use /brain:memorize, the agent analyzes the session and extracts significant decisions, learnings, insights, or experiences
Store — Each memory is filed into the hierarchy at the appropriate depth, with YAML frontmatter tracking metadata. Association edges are created to related memories.
Decay — Memories naturally weaken over time: effective_strength = base_strength * (decay_rate ^ days_since_access)
Recall — /brain:remember searches, scores with spreading activation and context matching, and returns the best memories. Archived memories are searched as a fallback.
Reinforce — Each recall applies spaced reinforcement (longer gaps = bigger boosts) and improves the memory's decay resistance
Review — SM-2 spaced repetition surfaces memories at optimal intervals for long-term retention; reinforcement runs automatically during the sleep cycle
Sleep — /brain:sleep performs a 9-phase maintenance cycle inspired by real neuroscience (replay, consolidation, review reinforcement, pruning, dreaming, …), usually run automatically/in the background
Archive — Fully decayed memories move to _archived/ (recoverable and searchable) or can be permanently deleted

Neuroscience Foundations

Brain Memory is grounded in peer-reviewed neuroscience research. Here's how each mechanism maps to the brain:

| Brain Mechanism | Implementation | |-----------------|---------------| | Spreading activation | Recalling memory A automatically surfaces linked memories B and C via weighted association graph | | Hebbian learning | "Neurons that fire together wire together" — memories recalled together strengthen mutual links | | Context-dependent recall | Memories encoded in a similar context (project, task type) are scored higher at retrieval | | Spacing effect | Longer intervals between recalls produce larger strength boosts; cramming yields diminishing returns | | Ebbinghaus decay | Exponential forgetting curve with per-memory decay rates | | Episodic → Semantic | Event-specific memories crystallize into abstract principles during sleep | | Synaptic homeostasis (SHY) | Global strength downscaling during sleep prevents inflation, then selectively re-boosts important memories | | REM dreaming | Creative cross-domain association discovery via analogical reasoning | | Memory reconsolidation | Recent knowledge updates and reshapes older related memories during sleep | | Cue-dependent forgetting | Archival preserves availability — memories aren't deleted, just moved to _archived/ | | Targeted forgetting | Deep erasure that traces and removes all references, like how the brain can selectively erase specific memory traces |

Memory Types

| Type | Base Strength | Daily Decay | Use Case | |------|:---:|:---:|---| | insight | 0.90 | 0.997 | Deep realizations, patterns discovered | | decision | 0.85 | 0.995 | Choices made and their rationale | | goal | 0.80 | 0.993 | Objectives and aspirations | | experience | 0.75 | 0.985 | Notable events or processes | | learning | 0.70 | 0.990 | New knowledge acquired | | relationship | 0.70 | 0.997 | Connections between people/things | | preference | 0.60 | 0.998 | User style and preferences | | observation | 0.40 | 0.950 | Casual facts or notices |

Cognitive Types

Each memory is also classified by how the brain processes it:

| Cognitive Type | Strength Modifier | Decay Behavior | Example | |----------------|:-:|---|---| | Episodic | +0.10 | Faster decay — event details fade | "The deploy failed Tuesday because of X" | | Semantic | default | Standard decay — stable knowledge | "React hooks must follow rules of hooks" | | Procedural | -0.10 | Very slow decay — skills persist | "Steps to debug memory leaks" |

During sleep, frequently-recalled episodic memories are crystallized into semantic memories — the specific event fades but the lesson persists. This mirrors how humans extract general principles from repeated experiences.

Always-Present Memories (Pinning)

Recall is probabilistic — a stored preference only applies if scoring happens to surface it. For the facts an agent must never miss (coding conventions, standing decisions, hard constraints), that's not good enough. Pinning fixes it:

pinned — the memory is injected at every session start regardless of recall score, and is decay-exempt (it never fades). Scope it global (loads everywhere) or project:<name> (loads only in that project).
stable — an independent flag that exempts a memory from decay and pruning without forcing it to always load — for timeless facts you recall on demand but don't want to fade.

brain pin <id> --scope global --priority 1   # or: /brain:pin always use tabs

Pinned and stable memories are skipped by sleep-cycle homeostasis and pruning, and /brain:memorize proactively proposes pinning durable conventions. The always-present set is budget-capped (pin_budget_tokens) so it can't crowd out the context window. This maps cleanly to the semantic memory type in the CoALA agent-memory model — knowledge that is always in context — decomposed into two orthogonal properties (always-loaded vs. non-decaying).

Procedural Skills

Procedural memory is how to do things — reusable, step-by-step workflows stored as ~/.brain/_skills/<name>/SKILL.md. To keep them from flooding the context window, skills use three-level progressive disclosure:

| Level | When | What loads | |-------|------|------------| | L0 | Every session start | Only each skill's name + description (~100 tokens) | | L1 | A task matches a skill | The full SKILL.md step-by-step instructions | | L2 | A step needs them | Referenced resources/ (templates, scripts) |

brain skill list                       # advertised skills (L0)
brain skill show structured-code-review # full instructions (L1)
brain skill use structured-code-review  # record outcome (--failed weakens it)
brain skill export structured-code-review --target claude  # → native .claude/skills/

Skills strengthen on successful use and weaken on --failed — one that fails too often demotes itself out of the advertised L0 index. And they aren't only hand-authored: during sleep, Brain crystallizes recurring task-solving patterns from repeated experience into new skills (user-confirmed). Finally, brain skill export emits a skill in your agent's native format so it becomes directly executable.

Memory File Format

Each memory is a Markdown file with YAML frontmatter:

---
id: mem_20260213_a3f2c1
type: decision
cognitive_type: semantic
created: 2026-02-13T14:30:00Z
last_accessed: 2026-02-13T14:30:00Z
access_count: 3
recall_history: ["2026-02-13T14:30:00Z", "2026-02-13T18:00:00Z", "2026-02-14T09:00:00Z"]
strength: 0.92
decay_rate: 0.995
salience: 0.8
confidence: 0.9
# Valid time — when the fact was TRUE, as distinct from `created` above (when
# it was recorded). Optional and half-open [from, until); omit for facts that
# are simply true. Superseding stamps `valid_until` on the old memory for you.
valid_from: 2026-02-13T14:30:00Z
tags: [architecture, microservices, scaling]
related: [mem_20260210_b4e5d6]
source: project-alpha-session
encoding_context:
  project: project-alpha
  topics: [architecture, scaling, kafka]
  task_type: designing
---

# Chose Event-Driven Architecture for Project Alpha

We decided to use event-driven architecture with Kafka instead of synchronous
REST calls between services, because the traffic analysis showed 10x burst
patterns that would overwhelm synchronous endpoints.

## Context

Sprint planning for Q2, evaluating scaling strategy for the notification system.

## Key Details

- Kafka chosen over RabbitMQ for its replay capability
- Event schema registry added to prevent breaking changes
- Estimated 3-week implementation vs 1-week for REST (but REST would need rework at scale)

## Connections

Related to the capacity planning decision (mem_20260210_b4e5d6) where we
identified the 10x burst pattern in notification traffic.

Scoring Formula

When recalling memories, each candidate is scored using a 6-factor formula:

score = 0.38 * relevance
      + 0.18 * decayed_strength
      + 0.08 * recency_bonus
      + 0.14 * spreading_bonus
      + 0.14 * context_match
      + 0.08 * salience

relevance (0.38) — How well the memory matches the query
decayed_strength (0.18) — Base strength after time decay
recency_bonus (0.08) — Linear bonus that fades over one year
spreading_bonus (0.14) — Activation received from linked memories in the association graph
context_match (0.14) — How similar the encoding context is to the current session
salience (0.08) — Emotional/motivational significance

Relevance is calibrated in absolute terms: BM25 scores are scaled by IDF-weighted query coverage, so a memory matching one term of a four-term query cannot claim relevance 1.0 just for being the best available match. Explicit-query recall also applies a relevance floor — memories that are neither query-relevant nor activated by a relevant associate are excluded rather than padding the results on strength alone. A query about things the brain doesn't know returns few results with honestly low scores (or none), instead of confident-looking noise. Context-mode recall (session start) is exempt, where strength-ranked topical padding is the intended behavior.

The agent then decides the response strategy:

Single strong match (top score > 0.7) → Return the full memory
Multiple related (2-5 candidates > 0.4) → Synthesize a consolidated response
Many weak (>5, all < 0.4) → List candidates for the user to choose
No active matches → Search the archive, then suggest alternatives

Associative Network

Memories are connected via weighted edges in ~/.brain/associations.json:

{
  "edges": {
    "mem_20260213_a3f2c1": {
      "mem_20260210_b4e5d6": {
        "weight": 0.45,
        "co_retrievals": 3,
        "last_activated": "2026-02-14T09:00:00Z",
        "origin": "co_retrieval"
      }
    }
  }
}

Spreading activation: When you recall memory A, activation spreads along weighted edges to surface related memories B and C — even if they didn't match the query directly. Activation decays by 50% per hop, up to 2 hops deep.

Hebbian learning: When multiple memories are recalled together, their mutual edge weights are strengthened: new_weight = min(1.0, weight + 0.10 * (1.0 - weight)). Memories that fire together wire together.

Link dynamics: Edges decay over time (weight * 0.998^days) and are pruned below 0.05 during sleep. New links are created automatically when memories share 2+ tags (weight 0.10) or are explicitly related (weight 0.20).

Spaced Reinforcement

Spaced reinforcement rewards optimal recall timing:

spacingMultiplier = min(3.0, 1.0 + log2(1 + daysSinceLastAccess))
diminishingFactor = 1.0 / (1.0 + 0.1 * recallCount)
boost = 0.05 * spacingMultiplier * diminishingFactor

| Scenario | Boost | |----------|:---:| | 1 day gap, first recall | +0.05 | | 7 day gap | +0.08 | | 30 day gap | +0.10 | | Same day, 20th recall (cramming) | +0.02 |

Each recall also improves the memory's decay rate: new_rate = rate + 0.10 * (0.999 - rate). Memories become progressively more forgetting-resistant with each retrieval.

Salience & Confidence

Salience (0.0-1.0) captures emotional/motivational significance. High-salience memories (>= 0.7) are never auto-pruned — they must be explicitly forgotten via /brain:forget. They also serve as anchors during consolidation.

Confidence (0.0-1.0) tracks epistemic certainty. Set at encoding based on source quality, reduced when contradictions are found during Knowledge Propagation (-0.20), boosted during validations (+0.10). Low-confidence memories are flagged during recall.

Sensitive Topics (Consent)

Every memory carries a consent tier: standard (default), sensitive (health, race, ethnicity, religious beliefs, politics, gender identity or sexual orientation, and similar), or blocked (government ID numbers, criminal history, immigration status — never stored). Classify honestly when memorizing ("sensitivity": "sensitive"). Sensitive memories are stored only when the user has opted in (sensitive_topics: true in ~/.brain/config.json); otherwise they wait quarantined and hidden until the user approves them (brain verify approve <id>), and their receipts carry ⚠ sensitive. Opting in is never retroactive, and the CLI refuses blocked content outright.

Consolidation

When memories decay below the threshold (default: 0.3), they become candidates for consolidation. The agent groups related weak memories by path proximity, tag overlap, and temporal closeness, then merges them into a single stronger memory:

consolidated_strength = max(source_strengths) + 0.15   (capped at 1.0)
consolidated_decay    = min(source_decay_rates)         (slowest decay wins)

The highest-salience memory in each group serves as the anchor — its framing and key details take priority in the synthesis. Original memories are moved to _archived/ (recoverable and searchable).

Sleep Cycle

/brain:sleep is the brain's overnight maintenance — inspired by how human brains reorganize memories during sleep. It runs nine phases:

Replay — Scans all memories and computes current decayed strengths, categorizing into tiers (Strong / Moderate / Weak / Fading)
Synaptic Homeostasis — If mean strength exceeds 0.5, proportionally scales down ALL strengths to prevent inflation, then selectively re-boosts high-salience, recently-accessed, and frequently-recalled memories. Based on Tononi & Cirelli's SHY hypothesis.
Knowledge Propagation — Evaluates recent memories against the hierarchy (ancestors, descendants, siblings, tag-related, association-linked) and updates existing memories through enrichment, contradiction detection, validation, obsolescence marking, and cross-referencing. Based on memory reconsolidation research.
Semantic Crystallization — Finds frequently-recalled episodic memories and extracts generalizable principles into new semantic memories. The event details begin fading but the lesson persists.
Reorganize — Detects flat clusters (3+ related memories at the same level) and restructures them into deeper sub-categories automatically
Consolidate — Merges weak related memories into stronger combined knowledge with salience anchoring
Prune — Archives memories that have faded below 0.1 strength (salience-protected memories are exempt)
REM Dreaming — Selects random memories from different categories and discovers creative cross-domain connections via analogical reasoning. Scored by novelty, utility, and surprise.
Expertise Detection — Identifies dense knowledge areas and generates expertise profiles, then populates the spaced repetition review queue

| Expertise Level | Score | Meaning | |-------|:---:|---------| | Awareness | 0.2 - 0.4 | Surface familiarity | | Working Knowledge | 0.4 - 0.6 | Competent with reference | | Deep Knowledge | 0.6 - 0.8 | Strong command, can reason about trade-offs | | Expert | 0.8 - 1.0 | Mastery — dense, frequently-recalled, long-standing |

Each expertise area gets an _expertise.md profile documenting what you know well, knowledge gaps, and contributing memories. Sleep can target a specific subtree (e.g., /brain:sleep professional/skills) or process the entire brain.

Spaced Repetition Review

Brain Memory implements the SM-2 algorithm to surface memories at optimal intervals for long-term retention. The review queue is generated and reinforced during /brain:sleep, and tracks:

Interval — Time until next review (grows exponentially with successful recalls)
Ease factor — How easily the memory is recalled (adjusts based on recall quality 1-5)
Review count — Total number of review sessions

Failed recalls reset the interval to 1 day. Successful recalls extend the interval by the ease factor. This ensures you spend time on memories that need reinforcement, not ones you already know well.

Cross-Agent Memory Sharing

~/.brain/ is a single global directory in the user's home folder. All memories are shared across every project and every supported agent automatically. A decision stored by Claude Code in one project is immediately available to OpenAI Codex CLI, OpenCode, or Google Antigravity in any other project — no configuration, no export, no per-project setup. The format is agent-agnostic: plain Markdown files with YAML frontmatter, readable by any tool.

Brain Memory is model-agnostic as well as agent-portable: because memory is plain files rather than embeddings welded to a particular model, the LLM underneath your agent can be anything — GPT, Claude, Gemini, or any model routed through a gateway — and your memory is unaffected. Switch your model or switch your agent, and you keep remembering and pick up exactly where you left off.

To share memories across different machines, use /brain:sync (see below).

Portable Sync — your memory, no lock-in

Your brain is plain files in a folder — sync it however you already sync files. No account or cloud provider is required.

Any synced folder — Point BRAIN_DIR at a folder your existing tools already sync, and you're done:

export BRAIN_DIR="$HOME/Google Drive/brain"   # or Dropbox, iCloud Drive, OneDrive, Syncthing…

Git remote — /brain:sync push/pull ~/.brain/ to any private Git repository (GitHub, GitLab, Codeberg, or self-hosted), using your existing Git/SSH auth.

Export/Import — Pack the entire brain into a single encrypted file for manual transfer via USB, email, or any file-sharing service.

Brain Cloud (optional) — A hosted, zero-config hub if you'd rather not run your own. Entirely optional — everything above works without it.

Key features:

Manual push/pull — No background watchers, no auto-sync. You control when data moves.
Optional encryption — AES-256-GCM encryption with a user-provided passphrase. When enabled, all files are encrypted before committing or exporting.
Merge mode — Import supports merge mode (only import newer files) or overwrite mode.
Zero dependencies — Uses Node.js built-in crypto and the system git binary.

Setup:

Create a private Git repo (e.g., gh repo create brain-data --private)
Run /brain:sync setup [email protected]:you/brain-data.git
Use /brain:sync push and /brain:sync pull to keep memories in sync

For one-off transfers, use /brain:sync export and /brain:sync import <path>.

Restore — an undo button for your whole brain. Every push is a restore point, and the CLI can roll the entire brain back to any of them:

brain restore --list                      # list restore points (the Git sync history)
brain restore --to <commit>               # roll ~/.brain/ back to that point
brain restore --list --from cloud         # list Brain Cloud's pre-push snapshots
brain restore --to <version> --from cloud # restore from a cloud snapshot

Before touching anything, restore preserves your current state — the Git path commits it as a safety snapshot, the cloud path writes a local backup under ~/.brain/.cloud/ — so a restore is always undoable, even for work you never pushed. (Brain Cloud also snapshots the brain it's about to replace on every push, server-side.) The append-only audit.log is carried forward through restores (never rolled back), and every restore is itself logged there. Restore granularity follows push frequency: push often for finer-grained history.

Sync state is stored locally in ~/.brain/.sync/ and is never pushed to the remote.

Brain in Claude apps (web & mobile) — beta

Beyond the CLI, you can use your brain from the Claude apps (web, desktop, and your phone) via the Brain connector — a remote MCP server hosted by Brain Cloud. Add it once on claude.ai (Settings → Connectors → Add custom connector → https://mcp.brainmemory.ai/mcp), sign in with the Google account holding your cloud brain, and it syncs to every Claude client on your account. Read and write: recall + status, plus memorize / pin / unpin (writes prompt for confirmation) — so you can capture a memory on your phone and recall it on your laptop.

→ Full guide: Use Brain in Claude apps

Your data, protected. Brains synced to Brain Cloud are encrypted at rest (AES-256-GCM, per-user key); the connector holds working copies in RAM only (never on disk); all traffic is TLS; sessions use rotating, revocable tokens with reuse detection (log out one device or all); and every request is isolated to your account. Prefer the server never sees plaintext? Stay local-only (the default) or use Git/export sync with a passphrase. See SECURITY.md.

File Structure

~/.brain/
├── index.json              # Memory inventory — fast lookup for all memories
├── config.json             # Working-memory token budgets (session-start injection)
├── associations.json       # Weighted associative network between memories
├── contexts.json           # Session context snapshots for context-dependent recall
├── review-queue.json       # Spaced repetition scheduling
├── pinned.json             # Always-present tier manifest (pinned memory IDs + scope)
├── skills-index.json       # Advertised procedural skills (L0 — name + description)
├── _skills/                # Procedural skills
│   └── <skill-name>/
│       ├── SKILL.md        # Advertised description + step-by-step instructions
│       └── resources/      # Optional templates/scripts (loaded only at execution)
├── professional/           # Work, career, technical skills
│   ├── _meta.json          # Category metadata and stats
│   ├── _expertise.md       # Generated expertise profile
│   ├── companies/          # On-demand: created when first needed
│   │   └── <company>/
│   │       ├── projects/
│   │       └── decisions/
│   ├── skills/
│   └── career/
├── personal/               # Education, health, hobbies, goals
│   ├── _meta.json
│   ├── education/
│   ├── health/
│   └── goals/
├── social/                 # Communities, networks, collaborations
│   ├── _meta.json
│   └── communities/
├── family/                 # Family relationships and events
│   ├── _meta.json
│   └── events/
├── _consolidated/          # Merged memories from consolidation
│   └── _meta.json
├── _archived/              # Decayed memories (recoverable + searchable)
│   ├── _meta.json
│   └── index.json          # Searchable archive index
└── .sync/                  # Sync state (local only, never pushed)
    ├── config.json          # Remote URL, encryption flag
    └── repo/                # Hidden git repo for sync

Subdirectories are created on demand — the agent decides placement depth based on how specific the memory is. A generic career thought lands in professional/, but a specific deployment incident goes to professional/companies/acme/projects/alpha/.

Configuration

Brain configuration lives in ~/.brain/index.json under the config key:

{
  "config": {
    "max_depth": 6,
    "consolidation_threshold": 0.3,
    "decay_check_interval_days": 7,
    "strength_boost_on_recall": 0.05,
    "auto_consolidate": true,
    "propagation_window_days": 7,
    "association_config": {
      "co_retrieval_boost": 0.10,
      "link_decay_rate": 0.998,
      "link_prune_threshold": 0.05,
      "spreading_activation_depth": 2,
      "spreading_activation_decay": 0.5
    }
  }
}

| Setting | Default | Description | |---------|---------|-------------| | max_depth | 6 | Maximum directory nesting depth | | consolidation_threshold | 0.3 | Strength below which memories are consolidation candidates | | decay_check_interval_days | 7 | How often to suggest decay maintenance | | strength_boost_on_recall | 0.05 | Base strength increase per recall event | | auto_consolidate | true | Suggest consolidation when candidates are found | | propagation_window_days | 7 | How far back to look for recent memories during knowledge propagation | | association_config.co_retrieval_boost | 0.10 | Hebbian reinforcement increment for co-retrieved memories | | association_config.link_decay_rate | 0.998 | Daily decay factor for association edge weights | | association_config.link_prune_threshold | 0.05 | Minimum weight before an association link is pruned | | association_config.spreading_activation_depth | 2 | Maximum hops for spreading activation traversal | | association_config.spreading_activation_decay | 0.5 | Decay factor per hop during spreading activation |

Sensitive Topics

sensitive_topics (default false). Memories classified sensitive — health, race, ethnicity, religious beliefs, politics, gender identity or sexual orientation — are stored only when this is true; otherwise they wait quarantined and hidden until you approve them one by one (brain verify approve <id>). Turning it on is never retroactive. blocked content (government ID numbers, criminal history, immigration status) is refused whatever the setting. See src/sensitivity.js for the exact tiers.

Working-Memory Budget

A separate ~/.brain/config.json (created lazily with safe defaults) caps how much the brain injects into the context window at session start, so the always-present tier can never crowd out your actual work:

{
  "working_memory_budget_tokens": 3000,
  "pin_budget_tokens": 1500,
  "skills_index_budget_tokens": 800,
  "recall_budget_tokens": 700
}

| Setting | Default | Description | |---------|---------|-------------| | working_memory_budget_tokens | 3000 | Total token ceiling for the whole brain session-start payload | | pin_budget_tokens | 1500 | Sub-budget for pinned, always-present memories | | skills_index_budget_tokens | 800 | Sub-budget for the advertised skills index (L0) | | recall_budget_tokens | 700 | Sub-budget for context-relevant recalled memories |

Token counts use a dependency-free heuristic stored on each memory at write time. When pins exceed their budget they're selected by --priority then strength, and the overflow is reported rather than silently dropped.

Benchmark

Brain Memory ships with a controlled benchmark suite grounded in the 2025-2026 SOTA in long-term-memory evaluation. The system itself is a direct implementation of the CoALA agent-memory model (Sumers et al., 2023) — Pinned Tier maps to CoALA's semantic memory, procedural skills to procedural memory.

Six scenarios, each describable in one sentence:

| Id | Pitch | Tests | |---|---|---| | A Noisy Project Folder | "Your brain has 200 memories from 6 projects — does it find the 3 relevant ones?" | Retrieval under distractors (LongMemEval-S analog) | | B Three Sessions, One Decision | "Postgres Monday, gRPC rewrite Wednesday, new resource Friday — still Postgres?" | Multi-session continuity + Pinned Tier ablation | | C The Contradiction Test | "Tabs, then spaces, then tabs again — which version wins?" | Decay-weighted recency + contradiction handling | | D Skill Progressive Disclosure | "Five skills indexed, one needed — does brain load just the one?" | CoALA Phase-2 L0/L1/L2 token efficiency | | E Continual Coding | "Five bugs in order — does bug 5 finish faster than bug 1?" | Forward transfer; agent writes memories between tasks | | F Abstention | "No deployment target in memory — does the agent ask or invent?" | Confabulation resistance |

Methodology highlights — agent under test is DeepSeek V4 Pro (single-shot), graded by a cross-family judge panel (Gemini + Gemma-4 + Qwen-3.5, majority vote — no judge shares the agent's family, Preference Leakage 2502.01534, PoLL 2404.18796); deterministic distractor haystacks up to 1000 memories; real brain session-start / brain recall integration; tokens-per-successful-task as the headline efficiency metric; every scenario anchored by a no-memory floor and an oracle ceiling.

Results (DeepSeek V4 Pro, 3 runs/arm, June 2026). Scenario A — retrieval under 1000 distractors: brain-full is the only retriever whose memories let the model succeed — it passes 100% while both BM25 (0%) and a vector store (0%) fail to surface the oracle memories — and it does so at the leanest tokens-per-success (3,199) of any passing arm. Scenario D — skills: loading only the relevant skill passes 100% at 1,580 tok/success, ~31% leaner than dumping all skill bodies. Scenarios B (continuity) shows brain efficient-and-correct; C (contradiction) and F (abstention) are honest nulls — the base model handles them without memory. At n=3 the token gaps are directional, not yet significant; the pass-rate gradient is the result. Full tables: brainmemory.ai/docs/benchmarks/results.

Retrieval calibration probe (in-vivo, July 2026). Separate from the controlled suite: a 20-query retrieval probe on a real working brain (177 memories, 1,245 association edges; tag-derived topical queries with known targets) measured the scoring-calibration fix shipped after beta.30. Before: hit@1 90%, MRR 0.950 — and a four-term nonsense control query still returned ten results, the top scoring a confident-looking 0.679. After query-coverage scaling and the relevance floor: hit@1 100% / hit@3 100% / MRR 1.000, the nonsense control returns a single result with honestly low relevance (0.213), and recall latency stays at ~46 ms (p50). Caveats: n=20, single brain, tag-derived queries favor the index's tag field, not judge-graded — this is a calibration probe, not the controlled benchmark above. Method and detail: brainmemory.ai/docs/benchmarks/results.

Run the benchmarks yourself:

cd benchmark
cp .env.example .env   # Add your API keys
npm test               # Unit tests
node harness/runner.js # Full benchmark (cloud APIs)

Live methodology and per-scenario detail: brainmemory.ai/docs/benchmarks · Source: benchmark/

Contributing

Contributions are welcome! See CONTRIBUTING.md for development setup, project structure, and how to submit changes.

References

Brain Memory's architecture and benchmark methodology are grounded in the following work.

Foundations — the agent-memory model Brain implements

CoALA — Cognitive Architectures for Language Agents (arxiv 2309.02427) — Sumers, Yao, Narasimhan, Griffiths. The agent-memory taxonomy Brain implements directly. Pinned Tier → semantic memory, Skills → procedural memory, session-start aggregator → working memory.
MemGPT — LLMs as Operating Systems (arxiv 2310.08560) — Packer et al. Paging-style memory management.
Generative Agents — Interactive Simulacra of Human Behavior (arxiv 2304.03442) — Park et al. Recency · importance · relevance retrieval blend.
Memory in the Age of AI Agents (arxiv 2512.13564) — Comprehensive survey on agent memory architectures.
Mem0 (arxiv 2504.19413) — Human-like memory reinforcement and decay.
MemOS (arxiv 2507.03724) — Memory lifecycle state management.

Memory benchmarks (the suite this work follows)

LongMemEval (arxiv 2410.10813) — distractor haystacks (S / M / Oracle), abstention category, GPT-4o judge with 97% human agreement.
MemoryAgentBench (arxiv 2507.05257) — four-competency framework; FactConsolidation inspired Scenario C.
SWE-Bench-CL (arxiv 2507.00014) — repo-scoped chronological evaluation; template for Scenario E.
LoCoMo (arxiv 2402.17753) — long-conversation memory benchmark.
MIRIX (arxiv 2507.07957) — realistic synthetic-but-grounded memory benchmarks.

Methodology — judging and benchmark hygiene

Preference Leakage in LLM-as-judge (arxiv 2502.01534) — drives cross-family judging.
When Judgment Becomes Noise — position bias (arxiv 2509.20293) — drives position-swap mitigation.
Silent Judge — shortcut bias (arxiv 2509.26072) — drives rubric-based judging.
LastingBench (arxiv 2506.21614) — benchmark-leakage defense.

Neuroscience

Ebbinghaus forgetting curve — exponential memory decay.
Spreading activation — Collins & Loftus network model of semantic memory.
Hebbian theory — "neurons that fire together wire together."
Synaptic homeostasis hypothesis — Tononi & Cirelli's theory of sleep function.
SM-2 algorithm — spaced repetition scheduling.
Memory reconsolidation — recalling memories makes them temporarily malleable.

Related projects

get-shit-done — Structured file-based workflow orchestration for AI agents.

License

MIT