brain-memory 0.1.0-beta.11 → 0.1.0-beta.13

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.
@@ -1,219 +1,89 @@
1
1
  # /brain:memorize — Store a New Memory
2
2
 
3
- You are storing a new memory in the Brain Memory system. Memories are filed into the `~/.brain/` hierarchical directory structure based on their semantic content.
3
+ You are storing memories in the Brain Memory system. Your job is to decide **what** to remember and **how to classify** it. The `brain-memorize` CLI handles all file operations.
4
4
 
5
5
  **User input:** $ARGUMENTS
6
6
 
7
- ## Efficiency Rules
7
+ **Flags:**
8
+ - `--sync` — Auto-push to cloud/git after storing
9
+ - `--confirm` — Ask for confirmation before writing (off by default)
8
10
 
9
- **CRITICAL — minimize tool call round-trips:**
10
- - **Plan everything before writing anything.** Steps 1-4 are pure reasoning — no tool calls needed.
11
- - **Generate all IDs in a single shell call** using: `hexdump -n 3 -e '"%06x\n"' /dev/urandom` (one per memory, chain multiple with `;`).
12
- - **Skip reads when you already have the file contents in context** (e.g., you just wrote them, or read them earlier this session). Only read `index.json` and `associations.json` if you do NOT already know their current state.
13
- - **Batch all file writes into a single parallel tool call** — memory files, _meta.json files, index.json, and associations.json should all be written together.
14
- - **Create directories in a single mkdir -p call** before the write batch.
15
- - **Target: 3-4 tool call rounds total** — (1) read current state if needed + generate IDs, (2) present proposal to user, (3) write all files, (4) reindex.
11
+ ## Behavior
16
12
 
17
- ## Steps
13
+ **Default: store immediately, show results after.** The user said "memorize" — they want it stored. Do NOT ask "Store these memories?" unless `--confirm` is passed, or $ARGUMENTS is empty AND you're genuinely uncertain which session content to extract.
18
14
 
19
- ### 1. Determine Memory Content
15
+ ## Steps
20
16
 
21
- If the user provided specific content in $ARGUMENTS, use that as the basis for the memory.
17
+ ### 1. Determine Content
22
18
 
23
- If $ARGUMENTS is empty or vague, analyze the **current conversation context** and extract the most significant learnings, decisions, insights, or experiences from the session. Summarize them into one or more distinct memories.
19
+ If $ARGUMENTS has specific content, use it. If empty, extract the most significant learnings, decisions, insights, or experiences from the current session.
24
20
 
25
21
  ### 2. Classify Each Memory
26
22
 
27
- For each memory to store, determine:
28
-
29
- **Type** (one of):
30
- - `decision` — A choice that was made and why (strength: 0.85, decay: 0.995/day)
31
- - `learning` — Something new that was learned (strength: 0.70, decay: 0.990/day)
32
- - `experience` — A notable event or process (strength: 0.75, decay: 0.985/day)
33
- - `insight` — A deep realization or pattern (strength: 0.90, decay: 0.997/day)
34
- - `observation` — A casual notice or fact (strength: 0.40, decay: 0.950/day)
35
- - `goal` — An objective or aspiration (strength: 0.80, decay: 0.993/day)
36
- - `preference` — A user preference or style (strength: 0.60, decay: 0.998/day)
37
- - `relationship` — A connection between people/things (strength: 0.70, decay: 0.997/day)
38
-
39
- **Impact assessment** — Adjust the base strength up or down by up to ±0.15 based on:
40
- - How significant is this to the user's life/work?
41
- - Is this likely to be needed again?
42
- - Does it represent a turning point or just routine?
43
-
44
- **Cognitive type** (one of):
45
- - `episodic` — Tied to a specific event/time. Add +0.10 to strength (vivid at first, fades faster). Multiply decay rate by 0.995. E.g., "The deployment failed Tuesday because X"
46
- - `semantic` — Abstracted knowledge, context-free. Use default strength/decay. E.g., "React hooks must follow rules of hooks"
47
- - `procedural` — How-to workflows, skills. Subtract -0.10 from strength but multiply decay rate by 1.003 (extremely slow decay once established). E.g., "Steps to debug memory leaks"
48
-
49
- **Salience** (0.0-1.0) — How emotionally or motivationally significant this memory is:
50
- - 0.0-0.3: Low — routine information
51
- - 0.4-0.6: Moderate — professionally relevant
52
- - 0.7-1.0: High — critical decisions, hard-won lessons, emotionally significant events. High-salience memories are NEVER auto-pruned.
53
-
54
- **Confidence** (0.0-1.0) — Epistemic certainty about the memory's accuracy:
55
- - 0.9-1.0: Verified/tested firsthand
56
- - 0.7-0.8: Reliable source, consistent with experience
57
- - 0.5-0.6: Plausible but unverified
58
- - 0.1-0.4: Uncertain, speculative, or hearsay
59
-
60
- ### 3. Determine File Path (Categorization)
61
-
62
- Choose the most appropriate path in the `~/.brain/` hierarchy. This is the most critical step.
63
-
64
- **Rules for path selection:**
65
- 1. Start with the top-level category: `professional/`, `personal/`, `social/`, `family/`
66
- 2. Go as deep as semantically justified — but not deeper than necessary
67
- 3. Create subdirectories on demand if they don't exist (add `_meta.json` for each)
68
- 4. Use kebab-case for directory and file names
69
- 5. File name should be a short descriptive slug + `.md`
23
+ For each memory, determine:
70
24
 
71
- **Depth guidelines:**
72
- - Generic career thought → `professional/career-direction.md`
73
- - Decision about a specific company → `professional/companies/acme-corp/joining-decision.md`
74
- - A specific project issue → `professional/companies/acme-corp/projects/alpha/deployment-incident.md`
75
- - Learning TypeScript → `personal/education/typescript-generics.md`
76
- - User prefers dark mode → `personal/preferences/dark-mode.md`
25
+ **Type** (sets base strength/decay — the CLI computes final values):
26
+ - `decision` (0.85/0.995) — Choices made and rationale
27
+ - `insight` (0.90/0.997) — Deep realizations, patterns
28
+ - `goal` (0.80/0.993) — Objectives and aspirations
29
+ - `experience` (0.75/0.985) — Notable events or processes
30
+ - `learning` (0.70/0.990) — New knowledge acquired
31
+ - `relationship` (0.70/0.997) — Connections between entities
32
+ - `preference` (0.60/0.998) — User preferences and style
33
+ - `observation` (0.40/0.950) — Casual facts or notices
77
34
 
78
- **If a memory spans categories**, place it in the most relevant one and note the cross-reference in `related` metadata.
35
+ **Cognitive type:** `episodic` (event-specific), `semantic` (abstracted knowledge), `procedural` (skills/workflows)
79
36
 
80
- ### 4. Present Proposal for Confirmation
37
+ **Path:** Where in `~/.brain/` hierarchy: `professional/`, `personal/`, `social/`, `family/` with kebab-case subdirectories as deep as semantically justified. File name = short slug + `.md`.
81
38
 
82
- Before writing anything, show the user what you plan to store:
39
+ **Salience** (0.0-1.0), **confidence** (0.0-1.0), **tags**, **related** memory IDs.
83
40
 
84
- For each proposed memory, display:
85
- - **Title** and proposed **path**
86
- - **Type** / **cognitive type** / **strength**
87
- - **Salience** / **confidence**
88
- - **Tags**
89
- - A 1-2 sentence summary
41
+ **strength_adjustment** (optional, -0.15 to +0.15): Tweak base strength based on significance.
90
42
 
91
- Ask: "Store these memories?" and wait for confirmation. If the user wants changes, adjust before proceeding.
43
+ ### 3. Call brain-memorize
92
44
 
93
- **Skip this step only if** the user explicitly passed detailed $ARGUMENTS that leave no ambiguity about what to store.
94
-
95
- ### 5. Generate Memory IDs and Prepare Directories
96
-
97
- **In a single tool call**, generate all needed random hex IDs and create any new directories:
45
+ Pipe the classified memories as JSON to the CLI in a **single bash call**:
98
46
 
99
47
  ```bash
100
- # Generate N IDs (one per memory) and create directories in one call
101
- hexdump -n 3 -e '"%06x\n"' /dev/urandom; hexdump -n 3 -e '"%06x\n"' /dev/urandom; mkdir -p ~/.brain/path/to/new/dir
102
- ```
103
-
104
- Format: `mem_<YYYYMMDD>_<6-char-random-hex>`
105
-
106
- ### 6. Read Current State (only if needed)
107
-
108
- **If you already have `index.json` and `associations.json` contents in context from this session, SKIP this step entirely.**
109
-
110
- Otherwise, read them now in a single parallel call:
111
- - `~/.brain/index.json`
112
- - `~/.brain/associations.json`
113
-
114
- ### 7. Write Everything in One Batch
115
-
116
- **Write ALL files in a single parallel tool call:**
117
-
118
- **A. Memory files** — one per memory, at the determined paths:
119
-
120
- ```markdown
121
- ---
122
- id: <memory_id>
123
- type: <memory_type>
124
- cognitive_type: <episodic|semantic|procedural>
125
- created: <ISO timestamp>
126
- last_accessed: <ISO timestamp>
127
- access_count: 0
128
- recall_history: []
129
- strength: <calculated strength 0.0-1.0>
130
- decay_rate: <decay rate per day>
131
- salience: <0.0-1.0>
132
- confidence: <0.0-1.0>
133
- tags: [<relevant tags>]
134
- related: [<related memory IDs if any>]
135
- source: <brief session identifier or context>
136
- encoding_context:
137
- project: <current project name>
138
- topics: [<2-5 key topics from session>]
139
- task_type: <debugging|implementing|designing|reviewing|discussing|learning>
140
- ---
141
-
142
- # <Short Descriptive Title>
143
-
144
- <2-5 sentence summary of the memory. Be specific and actionable. Include the WHY, not just the WHAT.>
145
-
146
- ## Context
147
-
148
- <1-3 sentences about the circumstances — when, where, what was happening>
149
-
150
- ## Key Details
151
-
152
- <Bullet points of the most important specifics>
153
-
154
- ## Connections
155
-
156
- <How this relates to other knowledge, patterns, or goals — if applicable>
157
- ```
158
-
159
- **B. Updated index.json** — add entries for all new memories:
160
-
161
- ```json
48
+ brain-memorize <<'EOF'
162
49
  {
163
- "<memory_id>": {
164
- "path": "<relative path from ~/.brain/>",
165
- "title": "<short title>",
166
- "type": "<memory_type>",
167
- "cognitive_type": "<episodic|semantic|procedural>",
168
- "strength": <strength>,
169
- "decay_rate": <decay_rate>,
170
- "salience": <salience>,
171
- "confidence": <confidence>,
172
- "created": "<ISO timestamp>",
173
- "last_accessed": "<ISO timestamp>",
174
- "access_count": 0,
175
- "tags": ["<tags>"],
176
- "encoding_context": {
177
- "project": "<project>",
178
- "topics": ["<topics>"],
179
- "task_type": "<task_type>"
50
+ "memories": [
51
+ {
52
+ "title": "Short descriptive title",
53
+ "type": "learning",
54
+ "cognitive_type": "semantic",
55
+ "path": "professional/projects/foo/what-i-learned.md",
56
+ "tags": ["foo", "patterns"],
57
+ "salience": 0.6,
58
+ "confidence": 0.9,
59
+ "strength_adjustment": 0.05,
60
+ "related": [],
61
+ "source": "Session context description",
62
+ "encoding_context": {
63
+ "project": "current-project",
64
+ "topics": ["topic1", "topic2"],
65
+ "task_type": "implementing"
66
+ },
67
+ "content": "# What I Learned\n\nThe main insight was...\n\n## Context\n\nThis came up while...\n\n## Key Details\n\n- Detail one\n- Detail two\n\n## Connections\n\nRelates to previous work on..."
180
68
  }
181
- }
69
+ ]
182
70
  }
71
+ EOF
183
72
  ```
184
73
 
185
- Increment `memory_count`. Update `last_updated`.
186
-
187
- **C. Updated associations.json** — create edges for new memories:
188
-
189
- - **Explicit `related` links:** For each ID in the `related` field, create an edge with weight 0.20 and origin `manual`.
190
- - **Auto-discovered links:** Scan `index.json` for other memories sharing **2 or more tags** with the new memory. For each match, create an edge with weight 0.10 and origin `tag_overlap`.
191
- - Use the `reinforceEdge()` function — if an edge already exists, strengthen it via Hebbian reinforcement instead of creating a duplicate.
192
-
193
- **D. _meta.json files** — for each directory along the path:
194
- - Increment `memory_count`
195
- - Add new subcategories to the `subcategories` array if any were created
196
-
197
- ### 8. Update Search Index
198
-
199
- Rebuild the TF-IDF search index so the new memories are discoverable by the recall engine:
200
-
74
+ Add `--sync` flag if the user requested it or passed `--sync` to the command:
201
75
  ```bash
202
- node <brain-memory-install-path>/bin/recall.js --reindex
76
+ brain-memorize --sync <<'EOF'
77
+ ...
78
+ EOF
203
79
  ```
204
80
 
205
- Or if globally installed:
206
- ```bash
207
- brain-recall --reindex
208
- ```
81
+ The CLI handles: ID generation, strength/decay computation, directory creation, file writing, index.json updates, association edges (explicit + tag overlaps), search index updates, and optional sync push.
209
82
 
210
- ### 9. Confirm
83
+ ### 4. Report Results
211
84
 
212
- Print what was stored:
213
- - Memory title and ID
214
- - Full path in the brain
215
- - Assigned type, cognitive type, and strength
216
- - Salience and confidence levels
217
- - Tags
218
- - Association edges created (count and targets)
219
- - Any new directories that were created
85
+ The CLI outputs JSON with what was stored. Present the results to the user:
86
+ - Memory title, ID, and path
87
+ - Type, strength, tags
88
+ - Edges created
89
+ - Sync result (if applicable)
@@ -4,13 +4,23 @@ You are managing synchronization for the Brain Memory system. This enables manua
4
4
 
5
5
  **CRITICAL RULES:**
6
6
  - NEVER auto-sync — always require explicit user action
7
- - NEVER silently overwrite files — always show a preview first
7
+ - NEVER silently overwrite files on pull/import — show a preview first
8
8
  - NEVER display passphrases or secrets in output
9
- - ALWAYS show what will change before executing push/pull/import
9
+ - Push operations execute immediately (no confirmation) — the user said "push"
10
+ - Pull/import operations warn before overwriting local data
10
11
 
11
12
  ## Subcommands
12
13
 
13
14
  Parse the user's input to determine the subcommand:
15
+
16
+ **Cloud Sync (Brain Cloud API):**
17
+ - `cloud login [--api-url URL]` → Authenticate via device code flow
18
+ - `cloud push` → Upload ~/.brain/ to Brain Cloud
19
+ - `cloud pull` → Download from Brain Cloud to ~/.brain/
20
+ - `cloud status` → Show cloud connection info
21
+ - `cloud logout` → Clear stored credentials
22
+
23
+ **Git Sync (any Git remote):**
14
24
  - `setup <url>` → Configure a Git remote for sync
15
25
  - `push` → Commit and push local changes to remote
16
26
  - `pull` → Fetch and merge remote changes to local
@@ -23,6 +33,135 @@ If no subcommand is given, show available subcommands.
23
33
 
24
34
  ---
25
35
 
36
+ ## `/brain:sync cloud login [--api-url URL]`
37
+
38
+ ### Steps
39
+
40
+ 1. **Check if already logged in:**
41
+ - Read `~/.brain/.cloud/config.json` via `readConfig()` from `src/cloud-sync.js`.
42
+ - If already connected, show current user and ask if they want to re-authenticate.
43
+
44
+ 2. **Start device code flow:**
45
+ - Run `brain-cloud login` (or call `login()` from `src/cloud-sync.js`).
46
+ - This calls `POST /auth/device/request` and returns a user code + verification URL.
47
+
48
+ 3. **Display instructions to user:**
49
+ ```
50
+ 🔐 Brain Cloud Login
51
+
52
+ Open this URL in your browser:
53
+ <verify_url>
54
+
55
+ Your code: <user_code>
56
+
57
+ Waiting for approval...
58
+ ```
59
+
60
+ 4. **Wait for approval:**
61
+ - The CLI polls `POST /auth/device/poll` every 5 seconds.
62
+ - Once approved, tokens are saved to `~/.brain/.cloud/config.json`.
63
+
64
+ 5. **Show result:**
65
+ ```
66
+ ✓ Logged in as <email>
67
+ Brain ID: <brain_id>
68
+ API: <api_url>
69
+ ```
70
+
71
+ ---
72
+
73
+ ## `/brain:sync cloud push`
74
+
75
+ ### Prerequisites
76
+
77
+ Check that `brain-cloud` CLI is available. If not:
78
+ ```
79
+ brain-cloud is not installed. Install it with:
80
+ npm install -g brain-memory
81
+ ```
82
+ Then return — do not attempt the push.
83
+
84
+ ### Steps
85
+
86
+ 1. **Check logged in.** If not, suggest `cloud login`.
87
+
88
+ 2. **Execute push immediately** — no confirmation needed:
89
+ - Run `brain-cloud push`.
90
+ - Show result:
91
+ ```
92
+ ✓ Push complete!
93
+ Size: <size>
94
+ Files: <count>
95
+ Checksum: <checksum>
96
+ ```
97
+
98
+ ---
99
+
100
+ ## `/brain:sync cloud pull`
101
+
102
+ ### Steps
103
+
104
+ 1. **Check logged in.**
105
+
106
+ 2. **Warn about overwrite:**
107
+ ```
108
+ 📥 Cloud Pull Preview:
109
+ Source: <api_url>
110
+ ⚠️ This will overwrite local files with the cloud version.
111
+ ```
112
+
113
+ 3. **Ask for confirmation.**
114
+
115
+ 4. **Execute pull:**
116
+ - Run `brain-cloud pull` (or call `pull()` from `src/cloud-sync.js`).
117
+ - Downloads tar.gz from `GET /api/brains/{id}/sync` and extracts to `~/.brain/`.
118
+ - Show result:
119
+ ```
120
+ ✓ Pull complete!
121
+ Size: <size>
122
+ ```
123
+
124
+ 5. **Rebuild index:**
125
+ - After pull, run the index manager to rebuild `~/.brain/index.json`.
126
+
127
+ ---
128
+
129
+ ## `/brain:sync cloud status`
130
+
131
+ ### Steps
132
+
133
+ 1. **Read cloud config** using `readConfig()` from `src/cloud-sync.js`.
134
+
135
+ 2. **Fetch live status** (if connected) by calling `status()` from `src/cloud-sync.js`.
136
+
137
+ 3. **Display dashboard:**
138
+ ```
139
+ ☁️ Brain Cloud Status
140
+ ─────────────────────────
141
+ API: <api_url or "not connected">
142
+ User: <email>
143
+ Brain ID: <brain_id>
144
+ Cloud Size: <size>
145
+ Cloud Files: <count>
146
+ Last Push: <timestamp or "never">
147
+ Last Pull: <timestamp or "never">
148
+ Last Synced: <timestamp or "never">
149
+ Connected: <timestamp>
150
+ ```
151
+
152
+ ---
153
+
154
+ ## `/brain:sync cloud logout`
155
+
156
+ ### Steps
157
+
158
+ 1. **Show current connection** (API URL, email).
159
+ 2. **Ask for confirmation:** "This will clear your stored credentials. Cloud data will NOT be deleted."
160
+ 3. **Remove `~/.brain/.cloud/` directory.**
161
+ 4. **Confirm:** "✓ Logged out. Cloud data is untouched."
162
+
163
+ ---
164
+
26
165
  ## `/brain:sync setup <url>`
27
166
 
28
167
  ### Steps
@@ -67,19 +206,9 @@ If no subcommand is given, show available subcommands.
67
206
 
68
207
  1. **Check sync is configured.** If not, suggest `/brain:sync setup`.
69
208
 
70
- 2. **Preview changes:**
71
- - Call `getStatus()` from `src/git-sync.js`.
72
- - Display summary:
73
- ```
74
- 📤 Push Preview:
75
- Remote: <remote-url>
76
- Status: <ahead> commits ahead, <behind> behind
77
- ```
78
- - If behind > 0, warn: "Remote has newer changes. Consider pulling first."
79
-
80
- 3. **Ask for confirmation** before proceeding.
209
+ 2. **Check status** via `getStatus()`. If behind > 0, warn: "Remote has newer changes. Consider pulling first." and stop.
81
210
 
82
- 4. **Execute push:**
211
+ 3. **Execute push immediately** — no confirmation needed:
83
212
  - If encryption is enabled, ask for passphrase.
84
213
  - Call `push()` from `src/git-sync.js`.
85
214
  - Show result:
@@ -214,9 +343,13 @@ If no subcommand is given, show available subcommands.
214
343
 
215
344
  ## Key Implementation Notes
216
345
 
346
+ - **Cloud sync engine**: `src/cloud-sync.js` — API client for Brain Cloud
347
+ - **Cloud CLI**: `bin/cloud-sync.js` — installed as `brain-cloud` command
348
+ - **Cloud config**: stored in `~/.brain/.cloud/config.json` (tokens, brain ID, API URL)
349
+ - **Cloud protocol**: tar.gz archives uploaded/downloaded via REST API
217
350
  - Git sync engine: `src/git-sync.js`
218
351
  - Export/import: `src/export-import.js`
219
352
  - Crypto utilities: `src/crypto.js`
220
- - Sync config stored in `~/.brain/.sync/config.json` (local only)
353
+ - Git sync config stored in `~/.brain/.sync/config.json` (local only)
221
354
  - Hidden git repo at `~/.brain/.sync/repo/` — never interferes with the project's own git
222
- - All git operations use `execFileSync` — no npm dependencies
355
+ - All operations use Node.js built-ins only — no npm runtime dependencies
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "brain-memory",
3
- "version": "0.1.0-beta.11",
3
+ "version": "0.1.0-beta.13",
4
4
  "description": "A brain-inspired hierarchical memory system for AI coding agents. Deep nested file structure that mimics human memory with time-decay and strength-based recall.",
5
5
  "keywords": [
6
6
  "claude-code",
@@ -26,7 +26,9 @@
26
26
  "bin": {
27
27
  "brain-memory": "bin/install.js",
28
28
  "brain-recall": "bin/recall.js",
29
- "brain-reinforce": "bin/reinforce.js"
29
+ "brain-reinforce": "bin/reinforce.js",
30
+ "brain-cloud": "bin/cloud-sync.js",
31
+ "brain-memorize": "bin/memorize.js"
30
32
  },
31
33
  "files": [
32
34
  "assets/",
package/prompts/claude.md CHANGED
@@ -62,37 +62,28 @@ Memories store their encoding context (project, topics, task type). During recal
62
62
 
63
63
  ## Session Start Behavior
64
64
 
65
- **IMPORTANT: Perform these steps automatically at the beginning of every session.**
65
+ **Perform these steps at session start — but keep it lightweight.**
66
66
 
67
67
  If `~/.brain/index.json` exists:
68
68
 
69
- 1. **Read the index** to understand the current brain state (memory count, categories)
70
- 2. **Run the recall engine** to deterministically identify relevant memories for the current project:
69
+ 1. **Read the index** to get memory count and categories
70
+ 2. **Run the recall engine only if the current project has relevant memories:**
71
71
  ```bash
72
72
  brain-recall --context --project "<current project>" --top 5
73
73
  ```
74
- This uses TF-IDF + the v4 scoring formula to find the most relevant memories — no guessing.
75
- 3. **Silently internalize** the returned memories so you can reference them naturally during the session — do NOT dump memory contents
76
- 4. **Check review queue** — read `~/.brain/review-queue.json` if it exists for memories due for review
77
- 5. **Output a brief status** (1-3 lines):
74
+ If the project is unrelated to any stored memories (e.g., a new project with no matching context), skip the recall and just show the count. Don't waste cycles searching when nothing will match.
75
+ 3. **Silently internalize** results — do NOT dump memory contents
76
+ 4. **Output a single status line:**
78
77
 
79
- If memories are due for review:
80
78
  ```
81
- 🧠 Brain active — <N> memories loaded (<M> in current project context)
82
- 📋 <X> memories due for review — run /brain:review
79
+ 🧠 Brain active — <N> memories (<M> in project context)
83
80
  ```
84
81
 
85
- Otherwise:
86
- ```
87
- 🧠 Brain active — <N> memories loaded (<M> in current project context)
88
- ```
89
-
90
- If any frequently-used memories (access_count >= 3) have confidence < 0.5:
91
- ```
92
- ⚠️ <N> frequently-used memories have low confidence — consider verifying
93
- ```
82
+ Only add extra lines if actionable:
83
+ - `📋 <X> due for review` — if review queue has items
84
+ - `⚠️ <N> low-confidence memories used frequently` — if access_count ≥ 3 and confidence < 0.5
94
85
 
95
- **The goal is ambient awareness** — know about past decisions, learnings, and preferences without reciting them. When a situation arises where a past memory is relevant, naturally reference it.
86
+ **The goal is ambient awareness** — know about past decisions, learnings, and preferences without reciting them. Reference them naturally when relevant.
96
87
 
97
88
  ## Ambient Session Tracking
98
89
 
package/prompts/gemini.md CHANGED
@@ -63,37 +63,28 @@ Commands are available via `/brain:` prefix:
63
63
 
64
64
  ## Session Start Behavior
65
65
 
66
- **IMPORTANT: Perform these steps automatically at the beginning of every session.**
66
+ **Perform these steps at session start — but keep it lightweight.**
67
67
 
68
68
  If `~/.brain/index.json` exists:
69
69
 
70
- 1. **Read the index** to understand the current brain state (memory count, categories)
71
- 2. **Run the recall engine** to deterministically identify relevant memories for the current project:
70
+ 1. **Read the index** to get memory count and categories
71
+ 2. **Run the recall engine only if the current project has relevant memories:**
72
72
  ```bash
73
73
  brain-recall --context --project "<current project>" --top 5
74
74
  ```
75
- This uses TF-IDF + the v4 scoring formula to find the most relevant memories — no guessing.
76
- 3. **Silently internalize** the returned memories so you can reference them naturally during the session — do NOT dump memory contents
77
- 4. **Check review queue** — read `~/.brain/review-queue.json` if it exists for memories due for review
78
- 5. **Output a brief status** (1-3 lines):
75
+ If the project is unrelated to any stored memories (e.g., a new project with no matching context), skip the recall and just show the count. Don't waste cycles searching when nothing will match.
76
+ 3. **Silently internalize** results — do NOT dump memory contents
77
+ 4. **Output a single status line:**
79
78
 
80
- If memories are due for review:
81
79
  ```
82
- 🧠 Brain active — <N> memories loaded (<M> in current project context)
83
- 📋 <X> memories due for review — run /brain:review
80
+ 🧠 Brain active — <N> memories (<M> in project context)
84
81
  ```
85
82
 
86
- Otherwise:
87
- ```
88
- 🧠 Brain active — <N> memories loaded (<M> in current project context)
89
- ```
90
-
91
- If any frequently-used memories (access_count >= 3) have confidence < 0.5:
92
- ```
93
- ⚠️ <N> frequently-used memories have low confidence — consider verifying
94
- ```
83
+ Only add extra lines if actionable:
84
+ - `📋 <X> due for review` — if review queue has items
85
+ - `⚠️ <N> low-confidence memories used frequently` — if access_count ≥ 3 and confidence < 0.5
95
86
 
96
- **The goal is ambient awareness** — know about past decisions, learnings, and preferences without reciting them. When a situation arises where a past memory is relevant, naturally reference it.
87
+ **The goal is ambient awareness** — know about past decisions, learnings, and preferences without reciting them. Reference them naturally when relevant.
97
88
 
98
89
  ## Ambient Session Tracking
99
90
 
package/prompts/openai.md CHANGED
@@ -63,37 +63,28 @@ Brain skills are available via `/brain-` prefix:
63
63
 
64
64
  ## Session Start Behavior
65
65
 
66
- **IMPORTANT: Perform these steps automatically at the beginning of every session.**
66
+ **Perform these steps at session start — but keep it lightweight.**
67
67
 
68
- If `.brain/index.json` exists in the current project:
68
+ If `.brain/index.json` exists:
69
69
 
70
- 1. **Read the index** to understand the current brain state (memory count, categories)
71
- 2. **Run the recall engine** to deterministically identify relevant memories for the current project:
70
+ 1. **Read the index** to get memory count and categories
71
+ 2. **Run the recall engine only if the current project has relevant memories:**
72
72
  ```bash
73
73
  brain-recall --context --project "<current project>" --top 5
74
74
  ```
75
- This uses TF-IDF + the v4 scoring formula to find the most relevant memories — no guessing.
76
- 3. **Silently internalize** the returned memories so you can reference them naturally during the session — do NOT dump memory contents
77
- 4. **Check review queue** — read `.brain/review-queue.json` if it exists for memories due for review
78
- 5. **Output a brief status** (1-3 lines):
75
+ If the project is unrelated to any stored memories (e.g., a new project with no matching context), skip the recall and just show the count. Don't waste cycles searching when nothing will match.
76
+ 3. **Silently internalize** results — do NOT dump memory contents
77
+ 4. **Output a single status line:**
79
78
 
80
- If memories are due for review:
81
79
  ```
82
- 🧠 Brain active — <N> memories loaded (<M> in current project context)
83
- 📋 <X> memories due for review — run /brain-review
80
+ 🧠 Brain active — <N> memories (<M> in project context)
84
81
  ```
85
82
 
86
- Otherwise:
87
- ```
88
- 🧠 Brain active — <N> memories loaded (<M> in current project context)
89
- ```
90
-
91
- If any frequently-used memories (access_count >= 3) have confidence < 0.5:
92
- ```
93
- ⚠️ <N> frequently-used memories have low confidence — consider verifying
94
- ```
83
+ Only add extra lines if actionable:
84
+ - `📋 <X> due for review` — if review queue has items
85
+ - `⚠️ <N> low-confidence memories used frequently` — if access_count ≥ 3 and confidence < 0.5
95
86
 
96
- **The goal is ambient awareness** — know about past decisions, learnings, and preferences without reciting them. When a situation arises where a past memory is relevant, naturally reference it.
87
+ **The goal is ambient awareness** — know about past decisions, learnings, and preferences without reciting them. Reference them naturally when relevant.
97
88
 
98
89
  ## Ambient Session Tracking
99
90