brain-memory 0.1.0-beta.9 → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (82) hide show
  1. package/CHANGELOG.md +632 -0
  2. package/README.md +390 -84
  3. package/SECURITY.md +100 -0
  4. package/assets/brand/README.md +28 -0
  5. package/assets/brand/icon-dark.svg +19 -0
  6. package/assets/brand/icon-light.svg +20 -0
  7. package/assets/brand/linkedin_cover.png +0 -0
  8. package/assets/brand/linkedin_cover_light.png +0 -0
  9. package/assets/brand/mark-dark.svg +19 -0
  10. package/assets/brand/mark-light.svg +20 -0
  11. package/assets/brand/png/icon-dark-1024.png +0 -0
  12. package/assets/brand/png/icon-dark-128.png +0 -0
  13. package/assets/brand/png/icon-dark-256.png +0 -0
  14. package/assets/brand/png/icon-dark-512.png +0 -0
  15. package/assets/brand/png/icon-dark-64.png +0 -0
  16. package/assets/brand/png/icon-light-1024.png +0 -0
  17. package/assets/brand/png/icon-light-128.png +0 -0
  18. package/assets/brand/png/icon-light-256.png +0 -0
  19. package/assets/brand/png/icon-light-512.png +0 -0
  20. package/assets/brand/png/icon-light-64.png +0 -0
  21. package/assets/brand/png/mark-dark-1024.png +0 -0
  22. package/assets/brand/png/mark-light-1024.png +0 -0
  23. package/assets/icon.png +0 -0
  24. package/assets/icon.svg +19 -0
  25. package/bin/audit.js +93 -0
  26. package/bin/brain.js +132 -0
  27. package/bin/cloud-sync.js +150 -0
  28. package/bin/forget.js +172 -0
  29. package/bin/import.js +132 -0
  30. package/bin/install.js +63 -31
  31. package/bin/memorize.js +670 -0
  32. package/bin/pin.js +44 -0
  33. package/bin/recall.js +319 -0
  34. package/bin/reinforce.js +191 -0
  35. package/bin/restore.js +122 -0
  36. package/bin/session-start.js +352 -0
  37. package/bin/skill.js +67 -0
  38. package/bin/unpin.js +38 -0
  39. package/bin/verify.js +186 -0
  40. package/commands/brain/forget.md +243 -13
  41. package/commands/brain/import.md +125 -0
  42. package/commands/brain/memorize.md +108 -130
  43. package/commands/brain/pin.md +79 -0
  44. package/commands/brain/remember.md +59 -100
  45. package/commands/brain/skills.md +60 -0
  46. package/commands/brain/sleep.md +93 -6
  47. package/commands/brain/status.md +15 -6
  48. package/commands/brain/sync.md +181 -17
  49. package/commands/brain/verify.md +63 -0
  50. package/integrations/README.md +29 -0
  51. package/integrations/agentskills/brain-memory/SKILL.md +115 -0
  52. package/integrations/agentskills/brain-memory/scripts/session-start.mjs +34 -0
  53. package/package.json +19 -7
  54. package/prompts/antigravity.md +222 -0
  55. package/prompts/claude.md +128 -40
  56. package/prompts/copilot.md +224 -0
  57. package/prompts/kilo.md +223 -0
  58. package/prompts/openai.md +133 -45
  59. package/prompts/opencode.md +221 -0
  60. package/src/anomaly.js +260 -0
  61. package/src/audit.js +71 -0
  62. package/src/cloud-sync.js +672 -0
  63. package/src/content-lint.js +118 -0
  64. package/src/export-import.js +45 -7
  65. package/src/git-sync.js +170 -11
  66. package/src/harvest.js +562 -0
  67. package/src/index-manager.js +250 -11
  68. package/src/installer.js +250 -29
  69. package/src/pinning.js +146 -0
  70. package/src/provenance.js +79 -0
  71. package/src/quarantine.js +111 -0
  72. package/src/receipt.js +87 -0
  73. package/src/scorer.js +137 -12
  74. package/src/skills.js +208 -0
  75. package/src/temporal.js +228 -0
  76. package/src/tfidf.js +520 -0
  77. package/commands/brain/consolidate.md +0 -153
  78. package/commands/brain/explore.md +0 -79
  79. package/commands/brain/init.md +0 -149
  80. package/commands/brain/review.md +0 -130
  81. package/commands/brain/sunshine.md +0 -337
  82. package/prompts/gemini.md +0 -134
package/README.md CHANGED
@@ -5,14 +5,14 @@
5
5
  <h1 align="center">Brain Memory</h1>
6
6
 
7
7
  <p align="center">
8
- <a href="https://github.com/onurkarali/brain/actions/workflows/ci.yml"><img src="https://github.com/onurkarali/brain/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
8
+ <a href="https://github.com/omelas-tech/brain/actions/workflows/ci.yml"><img src="https://github.com/omelas-tech/brain/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
9
9
  <a href="https://www.npmjs.com/package/brain-memory"><img src="https://img.shields.io/npm/v/brain-memory" alt="npm version"></a>
10
- <a href="https://github.com/onurkarali/brain/blob/main/LICENSE"><img src="https://img.shields.io/npm/l/brain-memory" alt="license"></a>
10
+ <a href="https://github.com/omelas-tech/brain/blob/main/LICENSE"><img src="https://img.shields.io/npm/l/brain-memory" alt="license"></a>
11
11
  </p>
12
12
 
13
13
  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.
14
14
 
15
- Works with **Claude Code**, **Gemini CLI**, and **OpenAI Codex CLI**.
15
+ 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](integrations/) plug the same brain into OpenClaw and Hermes as their memory engine.
16
16
 
17
17
  ```
18
18
  ~/.brain/
@@ -40,86 +40,230 @@ Existing AI memory solutions use flat databases with tag-based retrieval. Brain
40
40
  - **Human-inspectable** — Browse your "brain" in any file explorer
41
41
  - **Git-friendly** — Full version history of how memories evolve
42
42
  - **Strength + decay** — Recalled memories get stronger, forgotten ones fade. Just like your brain
43
+ - **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
44
+ - **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
45
+ - **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
43
46
  - **Associative network** — Memories link to each other with weighted connections. Recalling one activates related ones automatically
44
47
  - **Context-dependent recall** — Memories encoded in a similar context to the current session are scored higher
45
48
  - **Spaced reinforcement** — Memories recalled after longer intervals get bigger boosts, cramming produces diminishing returns
46
49
  - **Cognitive types** — Episodic, semantic, and procedural memories each decay differently, just like in the brain
50
+ - **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
51
+ - **Procedural skills** — Reusable how-to workflows with progressive disclosure, learned automatically from repeated experience and exportable to your agent's native skills
47
52
  - **On-demand depth** — Subcategories are created as needed, not pre-defined
48
53
  - **Consolidation** — Weak related memories merge into stronger combined knowledge
49
54
  - **Zero dependencies** — Pure file I/O, no databases, no servers, no embeddings required
50
55
 
51
56
  ## Install
52
57
 
58
+ There are two ways to give an agent its brain. They are complementary — most people end up with both:
59
+
60
+ | Path | Reaches | Storage | Cost | Best for |
61
+ |------|---------|---------|------|----------|
62
+ | **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 |
63
+ | **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 |
64
+ | **[Assistant integrations](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 |
65
+
66
+ ### 1. Universal path — the hosted MCP connector
67
+
68
+ 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.
69
+
53
70
  ```bash
54
- npx brain-memory@beta
71
+ # Claude Code
72
+ claude mcp add --transport http brain https://mcp.brainmemory.ai/mcp
73
+
74
+ # OpenAI Codex CLI
75
+ codex mcp add brain --url https://mcp.brainmemory.ai/mcp
55
76
  ```
56
77
 
57
- The interactive installer asks which runtime(s) to configure (Claude Code, Gemini CLI, OpenAI Codex CLI, or all) and whether to install globally or for the current project.
78
+ <details>
79
+ <summary>Per-host setup for every other connector</summary>
80
+
81
+ - **Codex CLI (config file)** — add to `~/.codex/config.toml`:
82
+ ```toml
83
+ [mcp_servers.brain]
84
+ url = "https://mcp.brainmemory.ai/mcp"
85
+ ```
86
+ - **OpenCode** — add to `opencode.json`:
87
+ ```json
88
+ {
89
+ "mcp": {
90
+ "brain": { "type": "remote", "url": "https://mcp.brainmemory.ai/mcp" }
91
+ }
92
+ }
93
+ ```
94
+ - **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.)
95
+ - **Google Antigravity** — add to `mcp_config.json` under the `serverUrl` key. *(Legacy Gemini CLI used the `httpUrl` key in `settings.json`.)*
96
+ - **GitHub Copilot CLI** — add to `~/.copilot/mcp-config.json` (OAuth via `/mcp auth brain` in-session):
97
+ ```json
98
+ {
99
+ "mcpServers": {
100
+ "brain-memory": { "type": "http", "url": "https://mcp.brainmemory.ai/mcp", "tools": ["*"] }
101
+ }
102
+ }
103
+ ```
104
+ - **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](integrations/openclaw/).)
105
+ - **Hermes Agent** — add to `~/.hermes/config.yaml`:
106
+ ```yaml
107
+ mcp_servers:
108
+ brain: { url: "https://mcp.brainmemory.ai/mcp", auth: oauth }
109
+ ```
110
+ - **Goose** — add a remote extension (streamable-HTTP) pointing at `https://mcp.brainmemory.ai/mcp`.
111
+ - **Kilo** — add to `kilo.jsonc` (OAuth starts automatically):
112
+ ```json
113
+ {
114
+ "mcp": {
115
+ "brain-memory": { "type": "remote", "url": "https://mcp.brainmemory.ai/mcp", "enabled": true }
116
+ }
117
+ }
118
+ ```
119
+
120
+ </details>
121
+
122
+ 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](https://brainmemory.ai/docs/getting-started/claude-apps)** for the full walkthrough.
123
+
124
+ ### 2. Local-first path — the native plugin
125
+
126
+ ```bash
127
+ npm install -g brain-memory
128
+ brain
129
+ ```
130
+
131
+ 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.
132
+
133
+ 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:
134
+
135
+ | Runtime | Instructions file | Commands land at |
136
+ |---------|-------------------|------------------|
137
+ | **Claude Code** | `CLAUDE.md` | `~/.claude/commands/brain/` (plugin slash commands) |
138
+ | **OpenAI Codex CLI** | `AGENTS.md` (`~/.codex/`) | `~/.agents/skills/<name>/SKILL.md` |
139
+ | **OpenCode** | `AGENTS.md` | `~/.config/opencode/commands/` |
140
+ | **GitHub Copilot CLI** | `copilot-instructions.md` (`~/.copilot/`), repo-local `AGENTS.md` | `~/.agents/skills/<name>/SKILL.md` (shared with Codex) |
141
+ | **Kilo** | `rules/brain-memory.md` + `kilo.jsonc` `instructions` entry (`~/.config/kilo/`), repo-local `AGENTS.md` | `~/.config/kilo/commands/` |
142
+ | **Google Antigravity** | `GEMINI.md` | `~/.gemini/skills/` *(experimental — verify paths against a live install)* |
143
+
144
+ #### Non-interactive
145
+
146
+ ```bash
147
+ brain --claude --global # Claude Code, global
148
+ brain --codex --global # OpenAI Codex CLI, global
149
+ brain --opencode --global # OpenCode, global
150
+ brain --copilot --global # GitHub Copilot CLI, global
151
+ brain --kilo --global # Kilo, global
152
+ brain --antigravity --global # Google Antigravity, global (experimental)
153
+ brain --all --global # All runtimes, global
154
+ ```
155
+
156
+ For the deepest Copilot CLI integration — deterministic session-start context injection via its `sessionStart` hook — install the [Copilot plugin](integrations/copilot/) from the brain marketplace:
157
+
158
+ ```bash
159
+ copilot plugin marketplace add omelas-tech/brain
160
+ copilot plugin install brain-memory@brain
161
+ ```
58
162
 
59
- ### Non-interactive
163
+ Kilo gets the same treatment via its runtime plugin — deterministic session-start injection, session tracking, and `BRAIN_AGENT` labeling ([details](integrations/kilo/)):
60
164
 
61
165
  ```bash
62
- npx brain-memory --claude --global # Claude Code, global
63
- npx brain-memory --gemini --local # Gemini CLI, local project
64
- npx brain-memory --codex --global # OpenAI Codex CLI, global
65
- npx brain-memory --all --global # All runtimes, global
166
+ mkdir -p ~/.config/kilo/plugin
167
+ cp integrations/kilo/plugin/brain-memory.js ~/.config/kilo/plugin/
66
168
  ```
67
169
 
170
+ ### 3. Personal-assistant integrations — OpenClaw, NemoClaw, Hermes
171
+
172
+ 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:
173
+
174
+ - **[OpenClaw / NVIDIA NemoClaw](integrations/openclaw/)** — 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.
175
+ - **[Hermes Agent](integrations/hermes/)** — 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.
176
+
177
+ Both are backed by the same `brain` CLI the coding-agent installs use — one memory, every agent.
178
+
68
179
  ### Update
69
180
 
70
181
  ```bash
71
- npx brain-memory@beta update
182
+ npm install -g brain-memory
183
+ brain update
72
184
  ```
73
185
 
74
- Auto-detects installed runtimes and refreshes commands + prompt sections. Target specific runtimes with `--claude`, `--gemini`, `--openai`, or `--all`.
186
+ 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`.
187
+
188
+ > **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.
189
+
190
+ > **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.
75
191
 
76
192
  ### Uninstall
77
193
 
78
194
  ```bash
79
- npx brain-memory@beta uninstall
195
+ brain uninstall
196
+ npm uninstall -g brain-memory
80
197
  ```
81
198
 
82
- Removes commands and prompt sections. Your `~/.brain/` directory (memories) is preserved by default. Add `--delete-data` to remove it too. Use `--yes` to skip confirmation prompts.
199
+ 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.
83
200
 
84
201
  ### Manual Install
85
202
 
86
- Copy the `commands/brain/` directory to your agent's commands folder:
203
+ 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.
87
204
 
88
205
  ```bash
89
- # Claude Code
206
+ # Claude Code — flat slash commands
90
207
  cp -r commands/brain/ ~/.claude/commands/brain/
91
208
 
92
- # Gemini CLI
93
- cp -r commands/brain/ ~/.gemini/commands/brain/
209
+ # OpenCode — flat slash commands
210
+ mkdir -p ~/.config/opencode/commands/brain
211
+ cp -r commands/brain/. ~/.config/opencode/commands/brain/
94
212
 
95
- # OpenAI Codex CLI (each command becomes a skill)
213
+ # OpenAI Codex CLI — each command becomes a skill under the cross-tool skills dir
96
214
  for f in commands/brain/*.md; do
97
215
  name=$(basename "$f" .md)
98
- mkdir -p ~/.codex/skills/brain-"$name"
99
- cp "$f" ~/.codex/skills/brain-"$name"/SKILL.md
216
+ mkdir -p ~/.agents/skills/brain-"$name"
217
+ cp "$f" ~/.agents/skills/brain-"$name"/SKILL.md
218
+ done
219
+
220
+ # Google Antigravity (experimental — verify paths) — skills under ~/.gemini/skills/
221
+ for f in commands/brain/*.md; do
222
+ name=$(basename "$f" .md)
223
+ mkdir -p ~/.gemini/skills/brain-"$name"
224
+ cp "$f" ~/.gemini/skills/brain-"$name"/SKILL.md
100
225
  done
101
226
  ```
102
227
 
103
228
  Then append the contents of the corresponding prompt file to your agent's instructions file:
104
229
  - `prompts/claude.md` → `CLAUDE.md`
105
- - `prompts/gemini.md` → `GEMINI.md`
106
- - `prompts/openai.md` → `AGENTS.md`
230
+ - `prompts/openai.md` → `AGENTS.md` (Codex, in `~/.codex/`)
231
+ - `prompts/opencode.md` → `AGENTS.md` (OpenCode)
232
+ - `prompts/antigravity.md` → `GEMINI.md` (experimental)
233
+
234
+ > **`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).
107
235
 
108
236
  ## Commands
109
237
 
238
+ 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:
239
+
110
240
  | Command | Description |
111
241
  |---------|-------------|
112
- | `/brain:init` | Initialize `~/.brain/` directory structure with default categories |
113
- | `/brain:memorize [topic]` | Store memories from current session context |
114
242
  | `/brain:remember [query]` | Recall relevant memories with spreading activation and context matching |
115
- | `/brain:review [scope]` | Spaced repetition review session for due memories |
116
- | `/brain:explore [category]` | Browse the brain hierarchy with visual tree view |
117
- | `/brain:consolidate [scope]` | Merge related weak memories into stronger combined ones |
118
- | `/brain:forget [target]` | Decay, archive, or remove memories |
119
- | `/brain:sunshine [target]` | Deep forensic erasure — trace and remove all references |
120
- | `/brain:sleep [scope]` | Full maintenance cycle — 9 neuroscience-inspired phases |
243
+ | `/brain:memorize [topic] [--sync]` | Store memories from current session context (add `--sync` to auto-push) |
121
244
  | `/brain:status` | Dashboard with brain health metrics and recommendations |
122
- | `/brain:sync [subcommand]` | Sync memories via Git remote or export/import for portability |
245
+ | `/brain:pin [id\|query]` | Pin a memory to the always-present tier — loads every session, never decays. Toggles: also unpins (`--off`) |
246
+ | `/brain:forget [target]` | Decay, archive, or remove memories. `--deep` performs forensic erasure — traces and removes every reference |
247
+ | `/brain:import [--project P] [--since 30d]` | Cold-start a new brain from transcripts your agents already wrote. Incremental — safe to re-run |
248
+ | `/brain:sync [subcommand]` | Sync via Brain Cloud, Git remote, or export/import (auto-initializes the brain on first run) |
249
+ | `/brain:skills [list\|show\|add\|use\|remove\|export]` | Manage procedural skills — reusable how-to workflows with progressive disclosure |
250
+ | `/brain:sleep [scope]` | Full maintenance cycle — 9 neuroscience-inspired phases (replay, consolidation, review reinforcement, pruning, dreaming, …). Usually runs automatically/in the background |
251
+
252
+ ## Cold Start
253
+
254
+ 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.
255
+
256
+ ```bash
257
+ brain import --sources # what history exists on this machine
258
+ brain import --project my-app # digest that project's past sessions
259
+ brain import --since 30d # or scope by time
260
+ ```
261
+
262
+ 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.
263
+
264
+ 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.**
265
+
266
+ 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.
123
267
 
124
268
  ## Session Lifecycle
125
269
 
@@ -127,22 +271,41 @@ Brain Memory works automatically in the background — no commands needed for ba
127
271
 
128
272
  ### Session Start
129
273
 
130
- When a session begins and `~/.brain/` exists, the agent automatically:
274
+ 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`):
131
275
 
132
- 1. Reads the brain index and loads the top 3-5 memories relevant to the current project
133
- 2. Checks the review queue for memories due for spaced repetition
134
- 3. Outputs a brief status line:
276
+ 1. **Pinned memories** — always-present conventions and preferences, injected verbatim regardless of recall score
277
+ 2. **Skills index** — the name + description of each available procedural skill (~100 tokens each; full instructions are loaded only when a task matches)
278
+ 3. **Context recall** — the top memories relevant to the current project
279
+ 4. **Review queue + low-confidence alerts**, then a brief status line:
135
280
 
136
281
  ```
137
- 🧠 Brain active — 42 memories loaded (8 in current project context)
138
- 📋 3 memories due for review — run /brain:review
282
+ ◉ Brain active — 42 memories loaded (8 in current project context)
283
+ 📋 3 memories due for review — reinforced automatically during /brain:sleep
139
284
  ```
140
285
 
141
- The agent silently internalizes relevant memories and references them naturally during the session — no information dump.
286
+ 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.
287
+
288
+ ### Ambient Session Tracking
289
+
290
+ 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.
291
+
292
+ ### Periodic Memory Checkpoint
293
+
294
+ 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:
295
+
296
+ ```
297
+ ◉ Notable decisions and learnings this session — /brain:memorize when ready
298
+ ```
299
+
300
+ 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`.
142
301
 
143
302
  ### Session End
144
303
 
145
- When a session ends, the agent evaluates whether significant decisions, learnings, insights, or experiences occurred. If so, it suggests:
304
+ When a session ends, the agent performs two steps in order:
305
+
306
+ 1. **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.
307
+
308
+ 2. **Suggests memorization** if the session contained meaningful decisions, learnings, or insights:
146
309
 
147
310
  ```
148
311
  💡 This session contained notable decisions and learnings.
@@ -150,7 +313,7 @@ When a session ends, the agent evaluates whether significant decisions, learning
150
313
  Run /brain:memorize to capture them before this context is lost.
151
314
  ```
152
315
 
153
- The agent never auto-memorizes without user consent. Session context is always saved to `~/.brain/contexts.json` for context-dependent recall.
316
+ The agent never auto-memorizes without user consent. Context is saved proactively — the agent doesn't wait for an explicit goodbye signal.
154
317
 
155
318
  ## How It Works
156
319
 
@@ -167,8 +330,8 @@ Create → Store → Decay → Recall → Reinforce → Review → Sleep → Arc
167
330
  3. **Decay** — Memories naturally weaken over time: `effective_strength = base_strength * (decay_rate ^ days_since_access)`
168
331
  4. **Recall** — `/brain:remember` searches, scores with spreading activation and context matching, and returns the best memories. Archived memories are searched as a fallback.
169
332
  5. **Reinforce** — Each recall applies spaced reinforcement (longer gaps = bigger boosts) and improves the memory's decay resistance
170
- 6. **Review** — `/brain:review` implements SM-2 spaced repetition, surfacing memories at optimal intervals for long-term retention
171
- 7. **Sleep** — `/brain:sleep` performs a 9-phase maintenance cycle inspired by real neuroscience
333
+ 6. **Review** — SM-2 spaced repetition surfaces memories at optimal intervals for long-term retention; reinforcement runs automatically during the sleep cycle
334
+ 7. **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
172
335
  8. **Archive** — Fully decayed memories move to `_archived/` (recoverable and searchable) or can be permanently deleted
173
336
 
174
337
  ### Neuroscience Foundations
@@ -214,6 +377,38 @@ Each memory is also classified by how the brain processes it:
214
377
 
215
378
  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.
216
379
 
380
+ ### Always-Present Memories (Pinning)
381
+
382
+ 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:
383
+
384
+ - **`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).
385
+ - **`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.
386
+
387
+ ```bash
388
+ brain pin <id> --scope global --priority 1 # or: /brain:pin always use tabs
389
+ ```
390
+
391
+ 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](https://arxiv.org/abs/2309.02427) agent-memory model — knowledge that is always in context — decomposed into two orthogonal properties (always-loaded vs. non-decaying).
392
+
393
+ ### Procedural Skills
394
+
395
+ 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**:
396
+
397
+ | Level | When | What loads |
398
+ |-------|------|------------|
399
+ | **L0** | Every session start | Only each skill's name + description (~100 tokens) |
400
+ | **L1** | A task matches a skill | The full `SKILL.md` step-by-step instructions |
401
+ | **L2** | A step needs them | Referenced `resources/` (templates, scripts) |
402
+
403
+ ```bash
404
+ brain skill list # advertised skills (L0)
405
+ brain skill show structured-code-review # full instructions (L1)
406
+ brain skill use structured-code-review # record outcome (--failed weakens it)
407
+ brain skill export structured-code-review --target claude # → native .claude/skills/
408
+ ```
409
+
410
+ 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.
411
+
217
412
  ### Memory File Format
218
413
 
219
414
  Each memory is a Markdown file with YAML frontmatter:
@@ -231,6 +426,10 @@ strength: 0.92
231
426
  decay_rate: 0.995
232
427
  salience: 0.8
233
428
  confidence: 0.9
429
+ # Valid time — when the fact was TRUE, as distinct from `created` above (when
430
+ # it was recorded). Optional and half-open [from, until); omit for facts that
431
+ # are simply true. Superseding stamps `valid_until` on the old memory for you.
432
+ valid_from: 2026-02-13T14:30:00Z
234
433
  tags: [architecture, microservices, scaling]
235
434
  related: [mem_20260210_b4e5d6]
236
435
  source: project-alpha-session
@@ -282,6 +481,16 @@ score = 0.38 * relevance
282
481
  - **context_match** (0.14) — How similar the encoding context is to the current session
283
482
  - **salience** (0.08) — Emotional/motivational significance
284
483
 
484
+ Relevance is **calibrated in absolute terms**: BM25 scores are scaled by
485
+ IDF-weighted *query coverage*, so a memory matching one term of a four-term query
486
+ cannot claim relevance 1.0 just for being the best available match. Explicit-query
487
+ recall also applies a **relevance floor** — memories that are neither
488
+ query-relevant nor activated by a relevant associate are excluded rather than
489
+ padding the results on strength alone. A query about things the brain doesn't
490
+ know returns few results with honestly low scores (or none), instead of
491
+ confident-looking noise. Context-mode recall (session start) is exempt, where
492
+ strength-ranked topical padding is the intended behavior.
493
+
285
494
  The agent then decides the response strategy:
286
495
  - **Single strong match** (top score > 0.7) → Return the full memory
287
496
  - **Multiple related** (2-5 candidates > 0.4) → Synthesize a consolidated response
@@ -374,7 +583,7 @@ Each expertise area gets an `_expertise.md` profile documenting what you know we
374
583
 
375
584
  ### Spaced Repetition Review
376
585
 
377
- `/brain:review` implements the SM-2 algorithm to surface memories at optimal intervals for long-term retention. The review queue is generated during sleep and tracks:
586
+ 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:
378
587
 
379
588
  - **Interval** — Time until next review (grows exponentially with successful recalls)
380
589
  - **Ease factor** — How easily the memory is recalled (adjusts based on recall quality 1-5)
@@ -384,17 +593,27 @@ Failed recalls reset the interval to 1 day. Successful recalls extend the interv
384
593
 
385
594
  ### Cross-Agent Memory Sharing
386
595
 
387
- `~/.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 Gemini CLI or Codex CLI 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.
596
+ `~/.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.
597
+
598
+ 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.**
388
599
 
389
600
  To share memories across different machines, use `/brain:sync` (see below).
390
601
 
391
- ### Portable Sync
602
+ ### Portable Sync — your memory, no lock-in
603
+
604
+ **Your brain is plain files in a folder — sync it however you already sync files.** No account or cloud provider is required.
605
+
606
+ **Any synced folder** — Point `BRAIN_DIR` at a folder your existing tools already sync, and you're done:
392
607
 
393
- `/brain:sync` provides two ways to sync memories across devices — no OAuth apps, no cloud provider setup.
608
+ ```bash
609
+ export BRAIN_DIR="$HOME/Google Drive/brain" # or Dropbox, iCloud Drive, OneDrive, Syncthing…
610
+ ```
394
611
 
395
- **Git remote** — Push/pull `~/.brain/` to any private Git repository. Works with GitHub, GitLab, Codeberg, or any self-hosted Git server. Uses your existing Git/SSH authentication — no additional credentials needed.
612
+ **Git remote** — `/brain:sync` push/pull `~/.brain/` to any private Git repository (GitHub, GitLab, Codeberg, or self-hosted), using your existing Git/SSH auth.
396
613
 
397
- **Export/Import** — Pack the entire `~/.brain/` into a single encrypted file for manual transfer via USB, email, or any file-sharing service.
614
+ **Export/Import** — Pack the entire brain into a single encrypted file for manual transfer via USB, email, or any file-sharing service.
615
+
616
+ **Brain Cloud** (optional) — A hosted, zero-config hub if you'd rather not run your own. Entirely optional — everything above works without it.
398
617
 
399
618
  **Key features:**
400
619
  - **Manual push/pull** — No background watchers, no auto-sync. You control when data moves.
@@ -409,16 +628,52 @@ To share memories across different machines, use `/brain:sync` (see below).
409
628
 
410
629
  For one-off transfers, use `/brain:sync export` and `/brain:sync import <path>`.
411
630
 
631
+ **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:
632
+
633
+ ```bash
634
+ brain restore --list # list restore points (the Git sync history)
635
+ brain restore --to <commit> # roll ~/.brain/ back to that point
636
+ brain restore --list --from cloud # list Brain Cloud's pre-push snapshots
637
+ brain restore --to <version> --from cloud # restore from a cloud snapshot
638
+ ```
639
+
640
+ 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.
641
+
412
642
  Sync state is stored locally in `~/.brain/.sync/` and is never pushed to the remote.
413
643
 
644
+ ### Brain in Claude apps (web & mobile) — beta
645
+
646
+ Beyond the CLI, you can use your brain from the **Claude apps** (web, desktop, and your
647
+ **phone**) via the **Brain connector** — a remote MCP server hosted by [Brain Cloud](https://app.brainmemory.ai).
648
+ Add it once on claude.ai (**Settings → Connectors → Add custom connector → `https://mcp.brainmemory.ai/mcp`**),
649
+ sign in with the Google account holding your cloud brain, and it syncs to every Claude client on
650
+ your account. Read **and write**: recall + status, plus memorize / pin / unpin (writes prompt for
651
+ confirmation) — so you can capture a memory on your phone and recall it on your laptop.
652
+
653
+ → Full guide: **[Use Brain in Claude apps](https://brainmemory.ai/docs/getting-started/claude-apps)**
654
+
655
+ **Your data, protected.** Brains synced to Brain Cloud are **encrypted at rest**
656
+ (AES-256-GCM, per-user key); the connector holds working copies in **RAM only**
657
+ (never on disk); all traffic is **TLS**; sessions use **rotating, revocable tokens
658
+ with reuse detection** (log out one device or all); and every request is isolated
659
+ to your account. Prefer the server never sees plaintext? Stay **local-only** (the
660
+ default) or use Git/export sync with a passphrase. See **[SECURITY.md](SECURITY.md)**.
661
+
414
662
  ## File Structure
415
663
 
416
664
  ```
417
665
  ~/.brain/
418
666
  ├── index.json # Memory inventory — fast lookup for all memories
667
+ ├── config.json # Working-memory token budgets (session-start injection)
419
668
  ├── associations.json # Weighted associative network between memories
420
669
  ├── contexts.json # Session context snapshots for context-dependent recall
421
670
  ├── review-queue.json # Spaced repetition scheduling
671
+ ├── pinned.json # Always-present tier manifest (pinned memory IDs + scope)
672
+ ├── skills-index.json # Advertised procedural skills (L0 — name + description)
673
+ ├── _skills/ # Procedural skills
674
+ │ └── <skill-name>/
675
+ │ ├── SKILL.md # Advertised description + step-by-step instructions
676
+ │ └── resources/ # Optional templates/scripts (loaded only at execution)
422
677
  ├── professional/ # Work, career, technical skills
423
678
  │ ├── _meta.json # Category metadata and stats
424
679
  │ ├── _expertise.md # Generated expertise profile
@@ -489,35 +744,58 @@ Brain configuration lives in `~/.brain/index.json` under the `config` key:
489
744
  | `association_config.spreading_activation_depth` | 2 | Maximum hops for spreading activation traversal |
490
745
  | `association_config.spreading_activation_decay` | 0.5 | Decay factor per hop during spreading activation |
491
746
 
492
- ## Benchmark
747
+ ### Working-Memory Budget
748
+
749
+ 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:
750
+
751
+ ```json
752
+ {
753
+ "working_memory_budget_tokens": 3000,
754
+ "pin_budget_tokens": 1500,
755
+ "skills_index_budget_tokens": 800,
756
+ "recall_budget_tokens": 700
757
+ }
758
+ ```
759
+
760
+ | Setting | Default | Description |
761
+ |---------|---------|-------------|
762
+ | `working_memory_budget_tokens` | 3000 | Total token ceiling for the whole `brain session-start` payload |
763
+ | `pin_budget_tokens` | 1500 | Sub-budget for pinned, always-present memories |
764
+ | `skills_index_budget_tokens` | 800 | Sub-budget for the advertised skills index (L0) |
765
+ | `recall_budget_tokens` | 700 | Sub-budget for context-relevant recalled memories |
766
+
767
+ 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.
493
768
 
494
- Empirical benchmarks show that agents with Brain Memory produce **more consistent** and **more successful** outputs across sessions.
769
+ ## Benchmark
495
770
 
496
- | Scenario | What it tests | Consistency Improvement | Success Improvement |
497
- |----------|---------------|:---:|:---:|
498
- | Multi-Session Continuity | Decisions carry from Session 1 → Session 2 | **+26.2%** | 0% |
499
- | Cross-Agent Consistency | All agents follow memorized style guide | 0% | 0% |
500
- | Accumulated Knowledge | 5 sessions of learning → better Session 6 | **+7.3%** | 0% |
501
- | Error Pattern Learning | Past debugging → faster fix | **+4.8%** | 0% |
502
- | Preference Retention | Preferences applied without re-stating | **+34.7%** | **+33.3%** |
771
+ 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**](https://arxiv.org/abs/2309.02427) agent-memory model (Sumers et al., 2023) — Pinned Tier maps to CoALA's *semantic* memory, procedural skills to *procedural* memory.
503
772
 
504
- **Per-agent consistency gains (Scenario 1 — Continuity):**
773
+ **Six scenarios**, each describable in one sentence:
505
774
 
506
- | Agent | With Brain | Without Brain | Improvement |
507
- |-------|:---:|:---:|:---:|
508
- | Claude Code | 0.944 | 0.645 | +46.4% |
509
- | Gemini CLI | 0.822 | 0.555 | +48.1% |
510
- | Codex CLI | 0.767 | 0.545 | +40.7% |
775
+ | Id | Pitch | Tests |
776
+ |---|---|---|
777
+ | **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) |
778
+ | **B** *Three Sessions, One Decision* | "Postgres Monday, gRPC rewrite Wednesday, new resource Friday — still Postgres?" | Multi-session continuity + Pinned Tier ablation |
779
+ | **C** *The Contradiction Test* | "Tabs, then spaces, then tabs again — which version wins?" | Decay-weighted recency + contradiction handling |
780
+ | **D** *Skill Progressive Disclosure* | "Five skills indexed, one needed — does brain load just the one?" | CoALA Phase-2 L0/L1/L2 token efficiency |
781
+ | **E** *Continual Coding* | "Five bugs in order — does bug 5 finish faster than bug 1?" | Forward transfer; agent writes memories between tasks |
782
+ | **F** *Abstention* | "No deployment target in memory — does the agent ask or invent?" | Confabulation resistance |
511
783
 
512
- **Preference retention (Scenario 5) — the strongest result:**
784
+ **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](https://arxiv.org/abs/2502.01534), [PoLL 2404.18796](https://arxiv.org/abs/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.
513
785
 
514
- | Agent | With Brain | Without Brain | Notes |
515
- |-------|:---:|:---:|:---|
516
- | Claude Code | 0.866 / PASS | 0.359 / **FAIL** | Brain prevented failure |
517
- | Gemini CLI | 0.800 / PASS | 0.534 / PASS | +49.8% consistency |
518
- | Codex CLI | 0.934 / PASS | 0.666 / PASS | +40.2% consistency |
786
+ > 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](https://brainmemory.ai/docs/benchmarks/results).
519
787
 
520
- > Average across 5 scenarios: **+18.3% consistency**, **+33.3% success improvement**. Agents with Brain Memory use more tokens (memory context is injected as prompt), but the consistency and reliability gains justify the cost. In the preference scenario, Claude Code without Brain Memory failed entirely — with Brain Memory, it passed every run.
788
+ **Retrieval calibration probe (in-vivo, July 2026).** Separate from the controlled
789
+ suite: a 20-query retrieval probe on a real working brain (177 memories, 1,245
790
+ association edges; tag-derived topical queries with known targets) measured the
791
+ scoring-calibration fix shipped after beta.30. Before: hit@1 90%, MRR 0.950 — and a
792
+ four-term nonsense control query still returned ten results, the top scoring a
793
+ confident-looking 0.679. After query-coverage scaling and the relevance floor:
794
+ **hit@1 100% / hit@3 100% / MRR 1.000**, the nonsense control returns a single result
795
+ with honestly low relevance (0.213), and recall latency stays at ~46 ms (p50).
796
+ *Caveats: n=20, single brain, tag-derived queries favor the index's tag field, not
797
+ judge-graded — this is a calibration probe, not the controlled benchmark above.*
798
+ Method and detail: [brainmemory.ai/docs/benchmarks/results](https://brainmemory.ai/docs/benchmarks/results).
521
799
 
522
800
  Run the benchmarks yourself:
523
801
 
@@ -528,24 +806,52 @@ npm test # Unit tests
528
806
  node harness/runner.js # Full benchmark (cloud APIs)
529
807
  ```
530
808
 
531
- Full methodology, per-scenario breakdowns, and raw data: [`benchmark/`](benchmark/) | [Detailed Report](benchmark/results/REPORT.md)
809
+ Live methodology and per-scenario detail: [brainmemory.ai/docs/benchmarks](https://brainmemory.ai/docs/benchmarks) · Source: [`benchmark/`](benchmark/)
532
810
 
533
811
  ## Contributing
534
812
 
535
813
  Contributions are welcome! See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup, project structure, and how to submit changes.
536
814
 
537
- ## Inspired By
538
-
539
- - [get-shit-done](https://github.com/gsd-build/get-shit-done) — Structured file-based workflow orchestration for AI agents
540
- - [Memory in the Age of AI Agents](https://arxiv.org/abs/2512.13564) — Comprehensive survey on agent memory architectures
541
- - [Mem0](https://arxiv.org/pdf/2504.19413) — Human-like memory reinforcement and decay
542
- - [MemOS](https://arxiv.org/pdf/2507.03724) — Memory lifecycle state management
543
- - [Ebbinghaus forgetting curve](https://en.wikipedia.org/wiki/Forgetting_curve) — Exponential memory decay
544
- - [Spreading activation](https://en.wikipedia.org/wiki/Spreading_activation) — Collins & Loftus network model of semantic memory
545
- - [Hebbian theory](https://en.wikipedia.org/wiki/Hebbian_theory) — "Neurons that fire together wire together"
546
- - [Synaptic homeostasis hypothesis](https://doi.org/10.1016/j.neuron.2013.10.024) — Tononi & Cirelli's theory of sleep function
547
- - [SM-2 algorithm](https://en.wikipedia.org/wiki/SuperMemo#Description_of_SM-2_algorithm) — Spaced repetition scheduling
548
- - [Memory reconsolidation](https://en.wikipedia.org/wiki/Memory_consolidation#Reconsolidation) — How recalling memories makes them temporarily malleable
815
+ ## References
816
+
817
+ Brain Memory's architecture and benchmark methodology are grounded in the following work.
818
+
819
+ ### Foundations — the agent-memory model Brain implements
820
+
821
+ - [**CoALA — Cognitive Architectures for Language Agents**](https://arxiv.org/abs/2309.02427) (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.
822
+ - [**MemGPT — LLMs as Operating Systems**](https://arxiv.org/abs/2310.08560) (arxiv 2310.08560) — Packer et al. Paging-style memory management.
823
+ - [**Generative Agents — Interactive Simulacra of Human Behavior**](https://arxiv.org/abs/2304.03442) (arxiv 2304.03442) — Park et al. Recency · importance · relevance retrieval blend.
824
+ - [**Memory in the Age of AI Agents**](https://arxiv.org/abs/2512.13564) (arxiv 2512.13564) — Comprehensive survey on agent memory architectures.
825
+ - [**Mem0**](https://arxiv.org/abs/2504.19413) (arxiv 2504.19413) — Human-like memory reinforcement and decay.
826
+ - [**MemOS**](https://arxiv.org/abs/2507.03724) (arxiv 2507.03724) — Memory lifecycle state management.
827
+
828
+ ### Memory benchmarks (the suite this work follows)
829
+
830
+ - [**LongMemEval**](https://arxiv.org/abs/2410.10813) (arxiv 2410.10813) — distractor haystacks (S / M / Oracle), abstention category, GPT-4o judge with 97% human agreement.
831
+ - [**MemoryAgentBench**](https://arxiv.org/abs/2507.05257) (arxiv 2507.05257) — four-competency framework; FactConsolidation inspired Scenario C.
832
+ - [**SWE-Bench-CL**](https://arxiv.org/abs/2507.00014) (arxiv 2507.00014) — repo-scoped chronological evaluation; template for Scenario E.
833
+ - [**LoCoMo**](https://arxiv.org/abs/2402.17753) (arxiv 2402.17753) — long-conversation memory benchmark.
834
+ - [**MIRIX**](https://arxiv.org/abs/2507.07957) (arxiv 2507.07957) — realistic synthetic-but-grounded memory benchmarks.
835
+
836
+ ### Methodology — judging and benchmark hygiene
837
+
838
+ - [**Preference Leakage in LLM-as-judge**](https://arxiv.org/abs/2502.01534) (arxiv 2502.01534) — drives cross-family judging.
839
+ - [**When Judgment Becomes Noise — position bias**](https://arxiv.org/abs/2509.20293) (arxiv 2509.20293) — drives position-swap mitigation.
840
+ - [**Silent Judge — shortcut bias**](https://arxiv.org/abs/2509.26072) (arxiv 2509.26072) — drives rubric-based judging.
841
+ - [**LastingBench**](https://arxiv.org/abs/2506.21614) (arxiv 2506.21614) — benchmark-leakage defense.
842
+
843
+ ### Neuroscience
844
+
845
+ - [**Ebbinghaus forgetting curve**](https://en.wikipedia.org/wiki/Forgetting_curve) — exponential memory decay.
846
+ - [**Spreading activation**](https://en.wikipedia.org/wiki/Spreading_activation) — Collins & Loftus network model of semantic memory.
847
+ - [**Hebbian theory**](https://en.wikipedia.org/wiki/Hebbian_theory) — "neurons that fire together wire together."
848
+ - [**Synaptic homeostasis hypothesis**](https://doi.org/10.1016/j.neuron.2013.10.024) — Tononi & Cirelli's theory of sleep function.
849
+ - [**SM-2 algorithm**](https://en.wikipedia.org/wiki/SuperMemo#Description_of_SM-2_algorithm) — spaced repetition scheduling.
850
+ - [**Memory reconsolidation**](https://en.wikipedia.org/wiki/Memory_consolidation#Reconsolidation) — recalling memories makes them temporarily malleable.
851
+
852
+ ### Related projects
853
+
854
+ - [get-shit-done](https://github.com/gsd-build/get-shit-done) — Structured file-based workflow orchestration for AI agents.
549
855
 
550
856
  ## License
551
857