brain-memory 0.1.0-beta.24 → 0.1.0-beta.27

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.
package/CHANGELOG.md ADDED
@@ -0,0 +1,264 @@
1
+ # Changelog
2
+
3
+ All notable changes to brain-memory will be documented in this file.
4
+
5
+ The format is based on [Keep a Changelog](https://keepachangelog.com/), and this project adheres to [Semantic Versioning](https://semver.org/).
6
+
7
+ ## [Unreleased]
8
+
9
+ ## [0.1.0-beta.27] - 2026-06-10
10
+
11
+ ### Security
12
+
13
+ - **Hosted-service hardening (Brain Cloud + connector).** Memories synced to Brain
14
+ Cloud are now **encrypted at rest** (AES-256-GCM, per-user key, with keys managed
15
+ in a cloud KMS — the key never sits on the server); the connector keeps per-user
16
+ working copies in **RAM only** (tmpfs), never on disk. CLI sessions use
17
+ **rotating refresh tokens with automatic reuse detection** and real **logout**
18
+ (one device or all). The connector now fails closed without an identity provider,
19
+ runs as an unprivileged sandboxed service, safely handles untrusted brain
20
+ bundles, and rate-limits its endpoints; OAuth account-linking requires a
21
+ **verified** email. None of this changes local-only or Git/export use, which stay
22
+ passphrase-encrypted and never touch the cloud. See [SECURITY.md](SECURITY.md).
23
+ - The published package now also ships `SECURITY.md` and `CHANGELOG.md`.
24
+
25
+ ## [0.1.0-beta.25] - 2026-06-07
26
+
27
+ ### Changed
28
+
29
+ - **Brand refresh.** Adopted the firing-neuron "activation" glyph in place of the brain emoji across the prompts, command output, CLI help text, and the README, and refreshed the icon set (`assets/`). No behavior change.
30
+
31
+ ## [0.1.0-beta.24] - 2026-06-05
32
+
33
+ ### Added
34
+
35
+ - **`BRAIN_DIR` environment variable** — point your brain at any folder instead of the default `~/.brain`. Set it to a folder your existing tools already sync (Google Drive, Dropbox, iCloud Drive, OneDrive, Syncthing, or a git working copy) to get cross-device sync with no account and no extra setup. A leading `~/` is expanded. Honored everywhere the brain is resolved — recall, memorize, init, and Cloud sync.
36
+
37
+ ## [0.1.0-beta.23] - 2026-06-05
38
+
39
+ ### Changed
40
+
41
+ - **Command surface collapsed to a six-verb core.** The everyday loop is ambient (recall + memorize), with a small manual surface and maintenance demoted to the background. Removed/merged six commands: `consolidate` and `review` are now handled by `/brain:sleep`; `unpin` is folded into `/brain:pin` (a toggle — `--off` unpins); `sunshine` (forensic erasure) is now `/brain:forget --deep`; `explore` is dropped (browse `~/.brain/` directly or use the web dashboard); and `init` is folded into install + first `/brain:sync` (which auto-creates the structure if missing). The surviving commands are `remember`, `memorize`, `status`, `pin`, `forget`, `sync`, `skills`, and `sleep`. This aligns the plugin with the forthcoming Claude connector, which exposes the same minimal tool set.
42
+
43
+ ### Fixed
44
+
45
+ - **Install detection no longer depends on a specific command.** The Codex/OpenAI skills-style detector keyed off `brain-init/SKILL.md`; it now matches any `brain-*` skill directory, so detection survives command-set changes.
46
+
47
+ ## [0.1.0-beta.21] - 2026-06-03
48
+
49
+ ### Changed
50
+
51
+ - **Primary domain moved to `brainmemory.ai`.** The website, dashboard, and Brain Cloud API now live at `brainmemory.ai`, `app.brainmemory.ai`, and `api.brainmemory.ai`. The plugin's default sync endpoint (`DEFAULT_API_URL`) is now `https://api.brainmemory.ai`. The old `brainmemory.work` hosts remain as redirects — `api.brainmemory.work` issues a `308` to the new API, so existing installs keep syncing without changes.
52
+
53
+ ## [0.1.0-beta.20] - 2026-05-31
54
+
55
+ ### Fixed
56
+
57
+ - **`memorize` and `skill add` now read piped stdin portably (fixes CI on Linux & Windows).** Both CLIs read input by opening the `/dev/stdin` *path*, which works on macOS but throws `ENXIO` on Linux CI runners and doesn't exist on Windows — so the contradiction-surfacing tests failed on every non-macOS job. Switched to reading file descriptor `0` (`fs.readFileSync(0, …)`), which reads piped stdin correctly across Linux, macOS, and Windows.
58
+
59
+ ### Changed
60
+
61
+ - **Project moved to the Omelas organization.** Repository transferred to `github.com/omelas-tech/brain` (old `onurkarali/brain` URLs redirect). Updated `repository`, `bugs`, and all in-repo/website GitHub references accordingly, and set `homepage` to `https://brainmemory.work/`. No code or behavior changes — metadata only. The npm package name stays `brain-memory` (unscoped); install is unchanged.
62
+
63
+ ## [0.1.0-beta.19] - 2026-05-30
64
+
65
+ ### Fixed
66
+
67
+ - **Installer now removes stale command files on update**, so the beta.18 `/brain:skill` → `/brain:skills` rename actually takes effect for existing users. Previously the installer only *copied* the current command set and never deleted renamed/removed files — so an upgrader's old `skill.md` lingered next to the new `skills.md`, and on case-insensitive filesystems that leftover `skill.md` (== `SKILL.md`) kept the whole `commands/brain/` directory shadowed as a single skill, hiding every `/brain:*` command. `installForRuntime` now wipes the `brain` command dir (and stale `brain-*` skill dirs for the Codex skills layout) before writing the fresh set.
68
+
69
+ ## [0.1.0-beta.18] - 2026-05-30
70
+
71
+ ### Fixed
72
+
73
+ - **`/brain:*` slash commands now actually register in Claude Code** (completes the beta.17 fix). On case-insensitive filesystems (default on macOS), the `skill` command file `skill.md` collides with `SKILL.md` — Claude Code's skill loader treated the entire `commands/brain/` directory as a single skill named `brain`, shadowing all 14 commands so none appeared in autocomplete. Renamed the command `skill` → `skills` (`commands/brain/skills.md`, invoked as `/brain:skills`) to remove the collision. The CLI subcommand remains `brain skill`. Updated slash-command references in `prompts/{claude,gemini,opencode}.md`, `CLAUDE.md`, and `README.md`.
74
+
75
+ ## [0.1.0-beta.17] - 2026-05-29
76
+
77
+ ### Fixed
78
+
79
+ - **Claude Code now registers all `/brain:*` slash commands.** The command files (`commands/brain/*.md`) shipped without YAML frontmatter; current Claude Code requires a `description` field to register a `.md` as a slash command, so all 14 commands were silently skipped (only `/brain:skill` surfaced, via the separate skills path). Added `description` + `argument-hint` frontmatter to every command file — the field Claude Code needs, and tolerated by the Gemini / Codex / OpenCode install targets too.
80
+
81
+ ## [0.1.0-beta.16] - 2026-05-28
82
+
83
+ ### Changed
84
+
85
+ - **Benchmark redesigned around 2025-2026 long-term-memory SOTA.** No runtime changes to the brain CLI; this release is a milestone marker for the new evaluation methodology shipped in `benchmark/` and documented at `/docs/benchmarks/`.
86
+ - New N-arm matrix harness with cross-family LLM judge (Claude judges Gemini and vice-versa) — mitigates preference leakage (arxiv 2502.01534) and position bias (arxiv 2509.20293).
87
+ - Six pitchable scenarios (A-F) replacing the legacy 5-scenario suite: Noisy Project Folder (LongMemEval-S retrieval-under-distractors), Three Sessions / One Decision (Pinned Tier ablation), The Contradiction Test (decay + recency), Skill Progressive Disclosure (CoALA Phase-2 L0/L1/L2 ablation), Continual Coding (SWE-Bench-CL style with real `brain memorize` between tasks), Abstention (confabulation resistance).
88
+ - Deterministic 200-memory distractor haystack; real `brain session-start` / `brain recall` integration with Recall@k / NDCG@k scoring against oracle ID sets.
89
+ - Tokens-per-successful-task adopted as the headline efficiency metric (Mem0/BEAM standard); write-side cost co-reported.
90
+ - New OpenCode CLI agent adapter (default model `deepseek/deepseek-v4-pro`), with `--opencode-model` override for cheaper DeepSeek variants.
91
+ - Codex CLI dropped from the default benchmark suite (no token reporting); remains a fully supported brain install target.
92
+ - Legacy scenarios 1-5 stay on disk for reproducing historical reports; invoke explicitly via `--scenario scenario-N-…`.
93
+
94
+ ## [0.1.0-beta.15] - 2026-05-27
95
+
96
+ ### Changed
97
+
98
+ - **BREAKING: unified CLI surface** — the five separate binaries (`brain-memory`, `brain-recall`, `brain-reinforce`, `brain-cloud`, `brain-memorize`) are replaced by a single `brain` dispatcher with subcommands: `brain recall`, `brain memorize`, `brain reinforce`, `brain cloud <…>`, and `brain install|update|uninstall` (bare `brain` runs the installer). New features ship as subcommands rather than new top-level binaries. Re-run the installer/update to refresh prompts; agents now invoke `brain <command>`. (`bin/brain.js`)
99
+
100
+ ### Added
101
+
102
+ - `brain --help` / `brain --version` on the unified dispatcher
103
+ - **CoALA Phase 0 — budget-aware working memory.** New `brain session-start` aggregator returns a single deterministic, token-budget-bounded startup payload (`memory_count`, `pinned`, `skills_index`, `context_recall`, `due_for_review`, `low_confidence_alerts`, `budget`); `~/.brain/config.json` holds the working-memory budget (created lazily with safe defaults); each new memory records a `token_estimate`. Session-start prompts/hook now make one `brain session-start` call instead of hand-rolled recall + review + low-confidence checks.
104
+ - **CoALA Phase 3 — procedural crystallization.** New `/brain:sleep` phase (4b) clusters repeated procedural/experience memories and proposes distilling a recurring task-solving procedure into a `SKILL.md` (user-confirmed, never silent) — learned skills, not just hand-authored ones.
105
+ - **CoALA Phase 4 — host skill export.** `brain skill export <name> [--target claude|gemini]` emits a native `.claude/skills/<name>/SKILL.md` (or `.gemini/...`) so distilled skills become directly executable by the host. The new state files (`config.json`, `pinned.json`, `skills-index.json`, `_skills/`) sync automatically via the existing whole-directory git/export-import engines.
106
+ - **Tier B §10.1 — obsolescence / context-shift detection.** `/brain:sleep` Prune phase flags memory clusters whose project/role has been absent from recent sessions (`contexts.json`) as reversible archive candidates — catching abrupt relevance loss that decay misses. Never flags pinned memories.
107
+ - **Tier B §10.2 — contradiction surfacing.** `brain memorize` now reports `potential_conflicts` when a new memory heavily overlaps a pinned/stable memory; `/brain:memorize` guidance has the agent adjudicate (supersede / keep-both-scoped / reject) instead of silently keeping both.
108
+ - **Tier B §10.4 — primacy/recency ordering.** `brain session-start` orders recalled memories so the highest-ranked land at the edges of the payload, mitigating "lost in the middle."
109
+ - **CoALA Phase 2 — procedural skills layer.** Skills are stored as `~/.brain/_skills/<name>/SKILL.md` and served via three-level progressive disclosure (L0 session-start advertises name + description only; L1 reads the full skill on a matching task; L2 loads resources at execution). `brain skill list|show <name>|use <name> [--failed]|add|remove <name>` and `/brain:skill`. Procedural strength rises on successful `use` and falls on `--failed`; a skill that fails too often demotes itself out of the advertised L0 index (Tier B §10.3). `~/.brain/skills-index.json` holds the L0 list; session-start injects skill summaries budget-capped by `skills_index_budget_tokens`.
110
+ - **CoALA Phase 1 — pinned semantic tier + stable flag.** `brain pin <id> [--scope global|project:<name>] [--priority N]` / `brain unpin <id>` and the `/brain:pin` `/brain:unpin` commands. Pinned memories are injected at every session start regardless of recall score and are decay-exempt; `stable: true` exempts a memory from decay without forcing it to always load. `pinned`/`stable` memories are skipped by sleep-cycle homeostasis and pruning. `~/.brain/pinned.json` manifest; `/brain:memorize` now proposes pinning durable conventions. Fixes the long-standing hole where a stored preference (e.g. "always use tabs") only applied if recall happened to surface it.
111
+
112
+ ## [0.1.0-beta.14] - 2026-04-25
113
+
114
+ ### Added
115
+
116
+ - **OpenCode support** — `brain --opencode` installs Brain Memory for the OpenCode agent (`prompts/opencode.md`), bringing the supported runtimes to Claude Code, Gemini CLI, OpenAI Codex CLI, and OpenCode.
117
+
118
+ ### Fixed
119
+
120
+ - **Graceful handling of corrupt brain state files** — CLI tools now emit a clear, actionable error (naming the offending JSON and suggesting a sync/backup restore) instead of crashing when `index.json`, `associations.json`, or the search index is malformed.
121
+
122
+ ### Changed
123
+
124
+ - **Install docs recommend `npm install -g` over `npx`** — `npx` discards the temporary install, so the `brain` CLI never lands in `PATH` and agents fall back to less reliable manual file operations.
125
+
126
+ ## [0.1.0-beta.13] - 2026-04-05
127
+
128
+ ### Added
129
+
130
+ - **`brain-memorize` CLI** — single-command memory storage that handles all plumbing (ID generation, strength/decay computation, directory creation, file writing, index updates, association edges, search index) in one call
131
+ - `--sync` flag for `/brain:memorize` — auto-pushes to cloud/git after storing, eliminating the separate `/brain:sync push` step
132
+ - `--confirm` flag for `/brain:memorize` — opt-in confirmation (was previously the default)
133
+ - Install check for `brain-cloud` CLI in `/brain:sync cloud push` — shows install instructions if missing
134
+
135
+ ### Changed
136
+
137
+ - **`/brain:memorize` is now non-interactive by default** — stores immediately and shows results after, instead of asking "Store these memories?" before writing. The user said "memorize" — they want it stored.
138
+ - **`/brain:sync push` and `cloud push` are now non-interactive** — execute immediately without confirmation, matching `git push` behavior. Pull/import still confirm before overwriting.
139
+ - **Memorize prompt reduced ~60%** — AI classifies memories and pipes JSON to `brain-memorize` CLI instead of manually writing files. One bash call instead of 6-8 tool calls.
140
+ - **Session start behavior made lightweight** — recall engine skips if project has no matching memories, output condensed to single status line, removed heavy mandatory phrasing
141
+
142
+ ## [0.1.0-beta.12] - 2026-04-02
143
+
144
+ ### Added
145
+
146
+ - **Brain Cloud sync** — push/pull `~/.brain/` to Brain Cloud (`api.brainmemory.work`) via new cloud subcommands
147
+ - `brain-cloud` CLI (`bin/cloud-sync.js`) — device code auth, push, pull, status, logout
148
+ - `src/cloud-sync.js` — zero-dependency cloud sync engine using Node.js built-in `https` module
149
+ - Device code OAuth flow for CLI authentication (`/brain:sync cloud login`)
150
+ - Tar.gz archive-based sync protocol for efficient uploads/downloads
151
+ - Token management with automatic refresh
152
+ - Cloud subcommands in `/brain:sync`: `cloud login`, `cloud push`, `cloud pull`, `cloud status`, `cloud logout`
153
+
154
+ ## [0.1.0-beta.11] - 2026-03-22
155
+
156
+ ### Added
157
+
158
+ - **Ambient Session Tracking** — agent maintains a running mental log of decisions, learnings, insights, experiences, and goals as they happen throughout the session, so nothing is lost by session end
159
+ - **Periodic Memory Checkpoint** — every ~10 substantive interactions, the agent appends a one-liner nudge to its next response, never interrupting flow
160
+ - `notable_unsaved` field in session context — preserves what happened even when the user doesn't memorize, so future sessions can reference it
161
+ - `update` subcommand — auto-detects existing installations and refreshes commands + prompt sections (`brain-memory update`)
162
+ - `uninstall` subcommand — removes commands and prompt sections, preserves `.brain/` by default (`brain-memory uninstall`)
163
+ - `detectInstallations()`, `removePromptSection()`, `removeCommands()`, `uninstallForRuntime()` in `src/installer.js`
164
+ - Subcommand routing in `bin/install.js` with `parseArgs()`, `runUpdate()`, `runUninstall()`
165
+ - 20 new tests covering detection, removal, and round-trip install/uninstall
166
+ - Git-based sync — push/pull `.brain/` to any private Git remote (GitHub, GitLab, Codeberg, self-hosted) via `/brain:sync setup/push/pull`
167
+ - Export/Import — single-file encrypted backup for portable transfers via `/brain:sync export` and `/brain:sync import`
168
+ - `src/crypto.js` — standalone AES-256-GCM crypto module extracted from the old sync code
169
+ - `src/git-sync.js` — Git sync engine using `child_process.execFileSync`
170
+ - `src/export-import.js` — single-file export/import with encryption and merge mode
171
+ - 74 new tests: installer unit tests (`test/install.test.js`) and prompt content validation + integration tests (`test/prompts.test.js`)
172
+ - Deterministic recall engine with TF-IDF scoring (`bin/recall.js`, `bin/reinforce.js`)
173
+ - Benchmark suite with automated multi-agent evaluation
174
+ - Website with full documentation site at brainmemory.work
175
+
176
+ ### Changed
177
+
178
+ - **Session End Behavior** — context save to `contexts.json` is now the first action (was an afterthought), saves unconditionally even for trivial sessions, and proactively detects session endings without waiting for explicit signals
179
+ - **`/brain:memorize` command** — restructured prompt for efficiency: batches all file writes into a single parallel call, skips reads when state is already in context, presents proposed memories for user confirmation before writing, targets 3-4 tool call rounds total (was 6+)
180
+ - `/brain:sync` now uses Git remotes instead of OAuth cloud providers — no more registering OAuth apps
181
+ - Replaced cloud sync dashboard in `/brain:status` with git sync status (remote URL, ahead/behind counts)
182
+ - Extracted installer logic from `bin/install.js` into `src/installer.js` for testability — `bin/install.js` is now a thin CLI wrapper
183
+ - Hook files (`hooks/session-start.md`, `hooks/session-end.md`) now have reference notes clarifying that behavior is delivered through prompt injection, not native hook events
184
+ - Removed dead `settingsFile` config from runtime definitions — it was never used
185
+ - Removed `hooks/` from npm package since they are internal reference docs, not user-facing files
186
+ - Website redesigned with clean light theme and updated icon
187
+
188
+ ### Removed
189
+
190
+ - Cloud sync module (`src/sync/`) — OAuth2, Dropbox, Google Drive, and OneDrive providers
191
+ - OAuth token storage (`credentials.enc`) and three-way diff sync state (`sync-state.json`)
192
+
193
+ ### Fixed
194
+
195
+ - Git sync repo isolation — the `git()` helper in `src/git-sync.js` only used `cwd` to scope commands; if `.brain/.sync/repo/.git` didn't exist yet (first push or failed init), git would walk up the directory tree and commit brain files to the parent project repo. Now uses `GIT_DIR` + `GIT_WORK_TREE` env vars to fully isolate the sync repo.
196
+ - Session lifecycle was dead code — session-start/end hook instructions were defined in `hooks/` but never installed or referenced anywhere. The prompt injected into CLAUDE.md/GEMINI.md/AGENTS.md only had a weak one-liner about memorization. Now all three prompt files contain full "Session Start Behavior" and "Session End Behavior" sections with automatic brain context loading, review queue alerts, and end-of-session memorization suggestions.
197
+ - `release:beta` npm script now automatically updates the `latest` dist-tag after publishing
198
+ - Accurate model names in benchmark results
199
+
200
+ ## [0.1.0-beta.4] - 2026-03-03
201
+
202
+ ### Added
203
+
204
+ - `/brain:sync` command — cloud sync for pushing/pulling memories to Dropbox, Google Drive, or OneDrive
205
+ - Cloud sync module (`src/sync/`) with OAuth2 PKCE + Device Code Flow, AES-256-GCM encryption, three-way diff algorithm, and provider-specific implementations (Dropbox API v2, Google Drive API v3, Microsoft Graph API)
206
+ - Zero new dependencies — uses Node.js 18+ built-in `fetch`, `crypto`, `http`
207
+
208
+ ### Changed
209
+
210
+ - Removed all v1 migration code and references — no v1 users exist
211
+ - Updated documentation to reflect 11 slash commands and cloud sync
212
+
213
+ ## [0.1.0-beta.3] - 2026-02-28
214
+
215
+ ### Added
216
+
217
+ - `/brain:sunshine` command — deep forensic memory erasure that traces and removes all references across the `.brain/` tree (related arrays, content mentions, association edges, context sessions, review queue, archive index, crystallization comments)
218
+ - `removeEdgesForMemory()` utility in index-manager for removing all association edges involving a memory
219
+ - `removeFromReviewQueue()` utility in index-manager for removing a memory from the review queue
220
+ - `_erased.json` audit log schema for tracking erasures without preserving erased content
221
+ - 16 new tests for erasure utilities
222
+ - npm release scripts (`release:beta`, `release:patch`, `release:minor`, `release:major`)
223
+
224
+ ### Fixed
225
+
226
+ - Windows CI compatibility: explicit test file listing, bash shell for glob expansion, `path.join` in tests
227
+ - Relaxed stress test thresholds for CI runners (5x multiplier)
228
+
229
+ ## [0.1.0-beta.1] - 2026-02-22
230
+
231
+ ### Added
232
+
233
+ - 375x faster `rankMemories` via batch spreading activation
234
+
235
+ ### Fixed
236
+
237
+ - Clamped recency bonus and optimized spreading activation loop
238
+ - Normalized `package.json` bin and repository fields for npm
239
+
240
+ ## [0.1.0] - 2026-02-15
241
+
242
+ Initial beta release.
243
+
244
+ ### Added
245
+
246
+ - 9 slash commands: `init`, `memorize`, `remember`, `review`, `explore`, `consolidate`, `forget`, `sleep`, `status`
247
+ - Neuroscience-inspired scoring with Ebbinghaus exponential decay
248
+ - Associative memory network with spreading activation (BFS, 2-hop, 50% decay per hop)
249
+ - Hebbian learning for co-retrieved memories
250
+ - Context-dependent recall scoring (project, topic Jaccard, task type matching)
251
+ - Spaced reinforcement with logarithmic spacing multiplier and diminishing returns
252
+ - 3 cognitive memory types: episodic, semantic, procedural (each with distinct decay behavior)
253
+ - Salience-based protection preventing auto-pruning of important memories
254
+ - Confidence tracking with contradiction detection
255
+ - 9-phase sleep cycle: replay, synaptic homeostasis, knowledge propagation, semantic crystallization, reorganize, consolidate, prune, REM dreaming, expertise detection
256
+ - SM-2 spaced repetition review scheduler
257
+ - Memory consolidation with salience anchoring
258
+ - Archive system with recoverable memories
259
+ - Multi-factor recall scoring formula (relevance, strength, recency, spreading, context, salience)
260
+ - Multi-runtime installer: Claude Code, Gemini CLI, OpenAI Codex CLI
261
+ - Interactive and non-interactive installation modes
262
+ - Session lifecycle hook definitions (session-start, session-end)
263
+ - 114 tests covering scorer, index-manager, and end-to-end lifecycle
264
+ - Zero external dependencies
package/README.md CHANGED
@@ -12,7 +12,7 @@
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**, **OpenAI Codex CLI**, and **OpenCode**.
15
+ One hosted **MCP connector** reaches every major agent and chat app — **Claude Code**, **OpenAI Codex CLI**, **OpenCode**, the **Claude.ai** apps, **ChatGPT**, and **Google Antigravity** (Gemini CLI's successor). Prefer a free, local-first install? The native plugin runs entirely from `~/.brain/` on Claude Code, Codex, OpenCode, and Antigravity.
16
16
 
17
17
  ```
18
18
  ~/.brain/
@@ -52,6 +52,50 @@ Existing AI memory solutions use flat databases with tag-based retrieval. Brain
52
52
 
53
53
  ## Install
54
54
 
55
+ There are two ways to give an agent its brain. They are complementary — most people end up with both:
56
+
57
+ | Path | Reaches | Storage | Cost | Best for |
58
+ |------|---------|---------|------|----------|
59
+ | **Hosted MCP connector** | Every MCP-capable host (Claude Code, Codex CLI, OpenCode, Claude.ai apps, ChatGPT, Antigravity) | Brain Cloud (hosted) | account | One connector, everywhere — including web & mobile chat |
60
+ | **Local-first native plugin** | The current CLIs (Claude Code, Codex CLI, OpenCode, Antigravity) | `~/.brain/` on your machine | free | Zero-config ambient memory, no account, files you own |
61
+
62
+ ### 1. Universal path — the hosted MCP connector
63
+
64
+ 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.
65
+
66
+ ```bash
67
+ # Claude Code
68
+ claude mcp add --transport http brain https://mcp.brainmemory.ai/mcp
69
+
70
+ # OpenAI Codex CLI
71
+ codex mcp add brain --url https://mcp.brainmemory.ai/mcp
72
+ ```
73
+
74
+ <details>
75
+ <summary>Per-host setup for every other connector</summary>
76
+
77
+ - **Codex CLI (config file)** — add to `~/.codex/config.toml`:
78
+ ```toml
79
+ [mcp_servers.brain]
80
+ url = "https://mcp.brainmemory.ai/mcp"
81
+ ```
82
+ - **OpenCode** — add to `opencode.json`:
83
+ ```json
84
+ {
85
+ "mcp": {
86
+ "brain": { "type": "remote", "url": "https://mcp.brainmemory.ai/mcp" }
87
+ }
88
+ }
89
+ ```
90
+ - **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.)
91
+ - **Google Antigravity** — add to `mcp_config.json` under the `serverUrl` key. *(Legacy Gemini CLI used the `httpUrl` key in `settings.json`.)*
92
+
93
+ </details>
94
+
95
+ 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.
96
+
97
+ ### 2. Local-first path — the native plugin
98
+
55
99
  ```bash
56
100
  npm install -g brain-memory@beta
57
101
  brain
@@ -59,16 +103,23 @@ brain
59
103
 
60
104
  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.
61
105
 
62
- The second command runs the setup wizard, which 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.
106
+ 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:
63
107
 
64
- ### Non-interactive
108
+ | Runtime | Instructions file | Commands land at |
109
+ |---------|-------------------|------------------|
110
+ | **Claude Code** | `CLAUDE.md` | `~/.claude/commands/brain/` (plugin slash commands) |
111
+ | **OpenAI Codex CLI** | `AGENTS.md` (`~/.codex/`) | `~/.agents/skills/<name>/SKILL.md` |
112
+ | **OpenCode** | `AGENTS.md` | `~/.config/opencode/commands/` |
113
+ | **Google Antigravity** | `GEMINI.md` | `~/.gemini/skills/` *(experimental — verify paths against a live install)* |
114
+
115
+ #### Non-interactive
65
116
 
66
117
  ```bash
67
- brain --claude --global # Claude Code, global
68
- brain --gemini --local # Gemini CLI, local project
69
- brain --codex --global # OpenAI Codex CLI, global
70
- brain --opencode --global # OpenCode, global
71
- brain --all --global # All runtimes, global
118
+ brain --claude --global # Claude Code, global
119
+ brain --codex --global # OpenAI Codex CLI, global
120
+ brain --opencode --global # OpenCode, global
121
+ brain --antigravity --global # Google Antigravity, global (experimental)
122
+ brain --all --global # All runtimes, global
72
123
  ```
73
124
 
74
125
  ### Update
@@ -78,7 +129,7 @@ npm install -g brain-memory@beta
78
129
  brain update
79
130
  ```
80
131
 
81
- 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`, `--gemini`, `--openai`, or `--all`.
132
+ 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`.
82
133
 
83
134
  > **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.
84
135
 
@@ -95,27 +146,38 @@ The first command removes slash commands and prompt sections from your agent con
95
146
 
96
147
  ### Manual Install
97
148
 
98
- Copy the `commands/brain/` directory to your agent's commands folder:
149
+ 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.
99
150
 
100
151
  ```bash
101
- # Claude Code
152
+ # Claude Code — flat slash commands
102
153
  cp -r commands/brain/ ~/.claude/commands/brain/
103
154
 
104
- # Gemini CLI
105
- cp -r commands/brain/ ~/.gemini/commands/brain/
155
+ # OpenCode — flat slash commands
156
+ mkdir -p ~/.config/opencode/commands/brain
157
+ cp -r commands/brain/. ~/.config/opencode/commands/brain/
106
158
 
107
- # OpenAI Codex CLI (each command becomes a skill)
159
+ # OpenAI Codex CLI — each command becomes a skill under the cross-tool skills dir
108
160
  for f in commands/brain/*.md; do
109
161
  name=$(basename "$f" .md)
110
- mkdir -p ~/.codex/skills/brain-"$name"
111
- cp "$f" ~/.codex/skills/brain-"$name"/SKILL.md
162
+ mkdir -p ~/.agents/skills/brain-"$name"
163
+ cp "$f" ~/.agents/skills/brain-"$name"/SKILL.md
164
+ done
165
+
166
+ # Google Antigravity (experimental — verify paths) — skills under ~/.gemini/skills/
167
+ for f in commands/brain/*.md; do
168
+ name=$(basename "$f" .md)
169
+ mkdir -p ~/.gemini/skills/brain-"$name"
170
+ cp "$f" ~/.gemini/skills/brain-"$name"/SKILL.md
112
171
  done
113
172
  ```
114
173
 
115
174
  Then append the contents of the corresponding prompt file to your agent's instructions file:
116
175
  - `prompts/claude.md` → `CLAUDE.md`
117
- - `prompts/gemini.md` → `GEMINI.md`
118
- - `prompts/openai.md` → `AGENTS.md`
176
+ - `prompts/openai.md` → `AGENTS.md` (Codex, in `~/.codex/`)
177
+ - `prompts/opencode.md` → `AGENTS.md` (OpenCode)
178
+ - `prompts/antigravity.md` → `GEMINI.md` (experimental)
179
+
180
+ > **`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).
119
181
 
120
182
  ## Commands
121
183
 
@@ -146,7 +208,7 @@ When a session begins and `~/.brain/` exists, the agent makes a single `brain se
146
208
  4. **Review queue + low-confidence alerts**, then a brief status line:
147
209
 
148
210
  ```
149
- 🧠 Brain active — 42 memories loaded (8 in current project context)
211
+ ◉ Brain active — 42 memories loaded (8 in current project context)
150
212
  📋 3 memories due for review — reinforced automatically during /brain:sleep
151
213
  ```
152
214
 
@@ -161,7 +223,7 @@ Throughout the session, the agent maintains a running mental log of notable even
161
223
  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:
162
224
 
163
225
  ```
164
- 🧠 Notable decisions and learnings this session — /brain:memorize when ready
226
+ ◉ Notable decisions and learnings this session — /brain:memorize when ready
165
227
  ```
166
228
 
167
229
  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`.
@@ -446,7 +508,7 @@ Failed recalls reset the interval to 1 day. Successful recalls extend the interv
446
508
 
447
509
  ### Cross-Agent Memory Sharing
448
510
 
449
- `~/.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, OpenAI Codex CLI, or OpenCode 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.
511
+ `~/.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.
450
512
 
451
513
  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.**
452
514
 
@@ -483,6 +545,24 @@ For one-off transfers, use `/brain:sync export` and `/brain:sync import <path>`.
483
545
 
484
546
  Sync state is stored locally in `~/.brain/.sync/` and is never pushed to the remote.
485
547
 
548
+ ### Brain in Claude apps (web & mobile) — beta
549
+
550
+ Beyond the CLI, you can use your brain from the **Claude apps** (web, desktop, and your
551
+ **phone**) via the **Brain connector** — a remote MCP server hosted by [Brain Cloud](https://app.brainmemory.ai).
552
+ Add it once on claude.ai (**Settings → Connectors → Add custom connector → `https://mcp.brainmemory.ai/mcp`**),
553
+ sign in with the Google account holding your cloud brain, and it syncs to every Claude client on
554
+ your account. Read **and write**: recall + status, plus memorize / pin / unpin (writes prompt for
555
+ confirmation) — so you can capture a memory on your phone and recall it on your laptop.
556
+
557
+ → Full guide: **[Use Brain in Claude apps](https://brainmemory.ai/docs/getting-started/claude-apps)**
558
+
559
+ **Your data, protected.** Brains synced to Brain Cloud are **encrypted at rest**
560
+ (AES-256-GCM, per-user key); the connector holds working copies in **RAM only**
561
+ (never on disk); all traffic is **TLS**; sessions use **rotating, revocable tokens
562
+ with reuse detection** (log out one device or all); and every request is isolated
563
+ to your account. Prefer the server never sees plaintext? Stay **local-only** (the
564
+ default) or use Git/export sync with a passphrase. See **[SECURITY.md](SECURITY.md)**.
565
+
486
566
  ## File Structure
487
567
 
488
568
  ```
package/SECURITY.md ADDED
@@ -0,0 +1,61 @@
1
+ # Security Policy
2
+
3
+ ## Reporting Vulnerabilities
4
+
5
+ If you discover a security vulnerability, please report it privately via email to **onur@omelas.tech**. Do not open a public GitHub issue for security vulnerabilities.
6
+
7
+ You should receive a response within 48 hours. Please include:
8
+ - Description of the vulnerability
9
+ - Steps to reproduce
10
+ - Potential impact
11
+
12
+ ## Scope
13
+
14
+ Brain Memory handles sensitive data in several areas:
15
+
16
+ - **AES-256-GCM encryption** — Optional encryption for Git-synced and exported memory files using a user-provided passphrase (PBKDF2-SHA512, 100K iterations)
17
+ - **File system access** — Reads and writes to the `.brain/` directory tree
18
+ - **Git operations** — When sync is configured, pushes/pulls to a user-specified Git remote using the system `git` binary and the user's existing Git/SSH authentication
19
+
20
+ ## Hosted service: Brain Cloud & the connector
21
+
22
+ Brain Memory is **local-first** — by default your memories are plain files on your
23
+ own disk and never leave it. The hosted **Brain Cloud** sync hub and the **Claude
24
+ connector** (a remote MCP server) are entirely optional. When you do use them, this
25
+ is how your data is protected:
26
+
27
+ - **Encrypted at rest.** Brains stored in Brain Cloud are encrypted on disk with
28
+ **AES-256-GCM** using a **per-user key** (HKDF-derived from a server master key).
29
+ A stolen disk, backup, or snapshot yields no readable memories.
30
+ - **No plaintext on the connector.** The connector keeps each user's working copy
31
+ in **RAM only** (a tmpfs, wiped on restart) — it is never written to the
32
+ connector's disk.
33
+ - **Encrypted in transit.** All traffic to `api.brainmemory.ai` and the connector
34
+ is HTTPS/TLS.
35
+ - **Strict tenant isolation.** Every cloud request is authorized against the
36
+ authenticated user; one account can never read or overwrite another's brain.
37
+ - **Revocable sessions.** CLI sessions use **rotating refresh tokens with
38
+ automatic reuse detection** — a replayed (stolen) token revokes the whole
39
+ session family. You can log out a device, or **all** devices, at any time.
40
+ - **Verified-identity sign-in.** Connector and dashboard login is Google OAuth via
41
+ Firebase; account-linking requires a **verified** email.
42
+ - **Least privilege.** The connector runs as an unprivileged, sandboxed service
43
+ (systemd hardening: no new privileges, read-only filesystem, private tmp).
44
+
45
+ Because the cloud runs deterministic recall server-side, this is **server-side**
46
+ encryption at rest, not end-to-end encryption: the service necessarily processes
47
+ your memories in memory. If you require that the server never sees plaintext, keep
48
+ your brain **local-only** (the default) or use Git/export sync with a passphrase
49
+ (below) instead of Brain Cloud.
50
+
51
+ ## Supported Versions
52
+
53
+ | Version | Supported |
54
+ |---------|-----------|
55
+ | 0.1.x (beta) | Yes |
56
+
57
+ ## Design Principles
58
+
59
+ - **No runtime dependencies** — Reduces supply chain attack surface
60
+ - **Local-first** — Sensitive data stays on disk by default; sync is opt-in
61
+ - **No stored credentials** — Git sync relies on the user's existing SSH keys or Git credential helpers; Brain Memory never stores auth tokens
package/assets/icon.png CHANGED
Binary file
package/assets/icon.svg CHANGED
@@ -1,27 +1,19 @@
1
- <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1024 1024" width="1024" height="1024">
2
- <defs>
3
- <radialGradient id="bm-glow" cx="50%" cy="50%" r="50%">
4
- <stop offset="0%" stop-color="#FFD27A" stop-opacity="0.9"/>
5
- <stop offset="100%" stop-color="#E8A33D" stop-opacity="0"/>
6
- </radialGradient>
7
- </defs>
8
- <rect x="0" y="0" width="1024" height="1024" rx="224" ry="224" fill="#07090A"/>
9
- <circle cx="512" cy="512" r="384" fill="url(#bm-glow)" opacity="0.7"/>
10
- <g stroke="#E8A33D" stroke-width="38" stroke-linecap="round">
11
- <line x1="512" y1="512" x2="256" y2="256" stroke-opacity="0.4"/>
12
- <line x1="512" y1="512" x2="800" y2="256" stroke-opacity="0.82"/>
13
- <line x1="512" y1="512" x2="864" y2="544" stroke-opacity="0.5"/>
14
- <line x1="512" y1="512" x2="768" y2="800" stroke-opacity="0.75"/>
15
- <line x1="512" y1="512" x2="256" y2="736" stroke-opacity="0.4"/>
16
- <line x1="512" y1="512" x2="192" y2="512" stroke-opacity="0.35"/>
1
+ <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 32 32" width="1024" height="1024" role="img" aria-label="Brain Memory"><defs><radialGradient id="core" cx="50%" cy="50%" r="50%"><stop offset="0%" stop-color="#8FDDFF" stop-opacity="0.95"/><stop offset="100%" stop-color="#46C6FF" stop-opacity="0"/></radialGradient></defs><rect x="0" y="0" width="32" height="32" rx="7" ry="7" fill="#07090A"/>
2
+ <circle cx="16" cy="16" r="12" fill="url(#core)" opacity="0.7"/>
3
+ <g stroke="#2E9FD6" stroke-width="1.25" stroke-linecap="round">
4
+ <line x1="16" y1="16" x2="8" y2="8" stroke-opacity="0.4"/>
5
+ <line x1="16" y1="16" x2="25" y2="8" stroke-opacity="0.82"/>
6
+ <line x1="16" y1="16" x2="27" y2="17" stroke-opacity="0.5"/>
7
+ <line x1="16" y1="16" x2="24" y2="25" stroke-opacity="0.75"/>
8
+ <line x1="16" y1="16" x2="8" y2="23" stroke-opacity="0.4"/>
9
+ <line x1="16" y1="16" x2="6" y2="16" stroke-opacity="0.35"/>
17
10
  </g>
18
- <circle cx="256" cy="256" r="51" fill="#9A6E28"/>
19
- <circle cx="864" cy="544" r="45" fill="#DCA044"/>
20
- <circle cx="768" cy="800" r="61" fill="#F0B24A"/>
21
- <circle cx="256" cy="736" r="51" fill="#A9762E"/>
22
- <circle cx="192" cy="512" r="42" fill="#8A6022"/>
23
- <circle cx="800" cy="256" r="83" fill="#FFDD8C"/>
24
- <circle cx="672" cy="368" r="42" fill="#FFF0CC"/>
25
- <circle cx="512" cy="512" r="118" fill="#FFF2D2"/>
26
- <circle cx="512" cy="512" r="61" fill="#FFFFFF"/>
27
- </svg>
11
+ <circle cx="8" cy="8" r="1.6" fill="#1C7FB0"/>
12
+ <circle cx="27" cy="17" r="1.4" fill="#4FB8E6"/>
13
+ <circle cx="24" cy="25" r="1.9" fill="#2E9FD6"/>
14
+ <circle cx="8" cy="23" r="1.6" fill="#2389BE"/>
15
+ <circle cx="6" cy="16" r="1.3" fill="#1B6E97"/>
16
+ <circle cx="25" cy="8" r="2.4" fill="#6FD3FF"/>
17
+ <circle cx="21" cy="11.5" r="1.3" fill="#CFEEFF"/>
18
+ <circle cx="16" cy="16" r="3.7" fill="#DFF4FF"/>
19
+ <circle cx="16" cy="16" r="1.9" fill="#FFFFFF"/></svg>
package/bin/brain.js CHANGED
@@ -40,7 +40,7 @@ const DELEGATED = {
40
40
  // `npx brain-memory` via npm's single-bin fallback.
41
41
  const INSTALLER = new Set(['install', 'update', 'uninstall']);
42
42
 
43
- const HELP = `🧠 brain — Brain Memory CLI
43
+ const HELP = `◉ brain — Brain Memory CLI
44
44
 
45
45
  Usage: brain <command> [options]
46
46