brain-memory 0.1.0-beta.2 → 0.1.0-beta.21
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/README.md +272 -72
- package/assets/icon.png +0 -0
- package/assets/icon.svg +27 -0
- package/bin/brain.js +111 -0
- package/bin/cloud-sync.js +149 -0
- package/bin/install.js +217 -242
- package/bin/memorize.js +436 -0
- package/bin/pin.js +44 -0
- package/bin/recall.js +237 -0
- package/bin/reinforce.js +187 -0
- package/bin/session-start.js +292 -0
- package/bin/skill.js +67 -0
- package/bin/unpin.js +38 -0
- package/commands/brain/consolidate.md +7 -2
- package/commands/brain/explore.md +7 -2
- package/commands/brain/forget.md +7 -2
- package/commands/brain/init.md +8 -12
- package/commands/brain/memorize.md +76 -144
- package/commands/brain/pin.md +37 -0
- package/commands/brain/remember.md +48 -105
- package/commands/brain/review.md +7 -2
- package/commands/brain/skills.md +60 -0
- package/commands/brain/sleep.md +68 -27
- package/commands/brain/status.md +19 -5
- package/commands/brain/sunshine.md +18 -13
- package/commands/brain/sync.md +360 -0
- package/commands/brain/unpin.md +26 -0
- package/package.json +18 -8
- package/prompts/claude.md +115 -12
- package/prompts/gemini.md +115 -12
- package/prompts/openai.md +113 -10
- package/prompts/opencode.md +178 -0
- package/src/cloud-sync.js +534 -0
- package/src/crypto.js +130 -0
- package/src/export-import.js +200 -0
- package/src/git-sync.js +444 -0
- package/src/index-manager.js +205 -18
- package/src/installer.js +384 -0
- package/src/pinning.js +124 -0
- package/src/scorer.js +8 -2
- package/src/skills.js +208 -0
- package/src/tfidf.js +408 -0
- package/hooks/session-end.md +0 -48
- package/hooks/session-start.md +0 -48
package/commands/brain/init.md
CHANGED
|
@@ -1,12 +1,16 @@
|
|
|
1
|
+
---
|
|
2
|
+
description: Initialize the brain memory structure
|
|
3
|
+
---
|
|
4
|
+
|
|
1
5
|
# /brain:init — Initialize Brain Memory Structure
|
|
2
6
|
|
|
3
|
-
You are initializing the Brain Memory system. This creates a
|
|
7
|
+
You are initializing the Brain Memory system. This creates a `~/.brain/` directory that serves as a hierarchical, file-system-based memory store inspired by human cognition.
|
|
4
8
|
|
|
5
9
|
## Steps
|
|
6
10
|
|
|
7
11
|
### 1. Check for Existing Brain
|
|
8
12
|
|
|
9
|
-
Check if
|
|
13
|
+
Check if `~/.brain/` directory already exists in the user's home directory.
|
|
10
14
|
|
|
11
15
|
- If it exists, inform the user and ask if they want to reset or keep it.
|
|
12
16
|
- If not, proceed with creation.
|
|
@@ -16,7 +20,7 @@ Check if `.brain/` directory already exists in the current project root.
|
|
|
16
20
|
Create the following structure:
|
|
17
21
|
|
|
18
22
|
```
|
|
19
|
-
|
|
23
|
+
~/.brain/
|
|
20
24
|
├── index.json
|
|
21
25
|
├── associations.json
|
|
22
26
|
├── contexts.json
|
|
@@ -131,7 +135,7 @@ If the user provides custom categories or subcategories, create them with approp
|
|
|
131
135
|
|
|
132
136
|
### 10. Add .brain to .gitignore (Optional)
|
|
133
137
|
|
|
134
|
-
Ask the user if they want
|
|
138
|
+
Ask the user if they want `~/.brain/` added to `.gitignore` (some users may want to track their memory in git, others may not).
|
|
135
139
|
|
|
136
140
|
### 11. Confirm
|
|
137
141
|
|
|
@@ -147,11 +151,3 @@ Print a summary of what was created, including the full tree structure. Inform t
|
|
|
147
151
|
- `/brain:status` — View brain overview
|
|
148
152
|
- `/brain:review` — Spaced repetition review of memories due for reinforcement
|
|
149
153
|
|
|
150
|
-
### Migration Note
|
|
151
|
-
|
|
152
|
-
If upgrading an existing v1 brain, the first `/brain:sleep` after upgrade will run a **Migration phase** (Phase 0) that:
|
|
153
|
-
- Creates `associations.json` from existing `related` fields
|
|
154
|
-
- Creates `contexts.json`, `review-queue.json`, and `_archived/index.json`
|
|
155
|
-
- Backfills `recall_history` from `access_count` (using `last_accessed` as sole entry)
|
|
156
|
-
- Sets default values for new frontmatter fields (`cognitive_type: semantic`, `salience: 0.5`, `confidence: 0.8`)
|
|
157
|
-
- Bumps `index.json` version to 2
|
|
@@ -1,176 +1,108 @@
|
|
|
1
|
+
---
|
|
2
|
+
description: Store memories from the current conversation context
|
|
3
|
+
argument-hint: "[topic]"
|
|
4
|
+
---
|
|
5
|
+
|
|
1
6
|
# /brain:memorize — Store a New Memory
|
|
2
7
|
|
|
3
|
-
You are storing
|
|
8
|
+
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
9
|
|
|
5
10
|
**User input:** $ARGUMENTS
|
|
6
11
|
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
If the user provided specific content in $ARGUMENTS, use that as the basis for the memory.
|
|
12
|
-
|
|
13
|
-
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.
|
|
14
|
-
|
|
15
|
-
### 2. Classify Each Memory
|
|
16
|
-
|
|
17
|
-
For each memory to store, determine:
|
|
18
|
-
|
|
19
|
-
**Type** (one of):
|
|
20
|
-
- `decision` — A choice that was made and why (strength: 0.85, decay: 0.995/day)
|
|
21
|
-
- `learning` — Something new that was learned (strength: 0.70, decay: 0.990/day)
|
|
22
|
-
- `experience` — A notable event or process (strength: 0.75, decay: 0.985/day)
|
|
23
|
-
- `insight` — A deep realization or pattern (strength: 0.90, decay: 0.997/day)
|
|
24
|
-
- `observation` — A casual notice or fact (strength: 0.40, decay: 0.950/day)
|
|
25
|
-
- `goal` — An objective or aspiration (strength: 0.80, decay: 0.993/day)
|
|
26
|
-
- `preference` — A user preference or style (strength: 0.60, decay: 0.998/day)
|
|
27
|
-
- `relationship` — A connection between people/things (strength: 0.70, decay: 0.997/day)
|
|
28
|
-
|
|
29
|
-
**Impact assessment** — Adjust the base strength up or down by up to ±0.15 based on:
|
|
30
|
-
- How significant is this to the user's life/work?
|
|
31
|
-
- Is this likely to be needed again?
|
|
32
|
-
- Does it represent a turning point or just routine?
|
|
33
|
-
|
|
34
|
-
**Cognitive type** (one of):
|
|
35
|
-
- `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"
|
|
36
|
-
- `semantic` — Abstracted knowledge, context-free. Use default strength/decay. E.g., "React hooks must follow rules of hooks"
|
|
37
|
-
- `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"
|
|
38
|
-
|
|
39
|
-
**Salience** (0.0-1.0) — How emotionally or motivationally significant this memory is:
|
|
40
|
-
- 0.0-0.3: Low — routine information
|
|
41
|
-
- 0.4-0.6: Moderate — professionally relevant
|
|
42
|
-
- 0.7-1.0: High — critical decisions, hard-won lessons, emotionally significant events. High-salience memories are NEVER auto-pruned.
|
|
43
|
-
|
|
44
|
-
**Confidence** (0.0-1.0) — Epistemic certainty about the memory's accuracy:
|
|
45
|
-
- 0.9-1.0: Verified/tested firsthand
|
|
46
|
-
- 0.7-0.8: Reliable source, consistent with experience
|
|
47
|
-
- 0.5-0.6: Plausible but unverified
|
|
48
|
-
- 0.1-0.4: Uncertain, speculative, or hearsay
|
|
49
|
-
|
|
50
|
-
### 3. Determine File Path (Categorization)
|
|
12
|
+
**Flags:**
|
|
13
|
+
- `--sync` — Auto-push to cloud/git after storing
|
|
14
|
+
- `--confirm` — Ask for confirmation before writing (off by default)
|
|
51
15
|
|
|
52
|
-
|
|
16
|
+
## Behavior
|
|
53
17
|
|
|
54
|
-
**
|
|
55
|
-
1. Start with the top-level category: `professional/`, `personal/`, `social/`, `family/`
|
|
56
|
-
2. Go as deep as semantically justified — but not deeper than necessary
|
|
57
|
-
3. Create subdirectories on demand if they don't exist (add `_meta.json` for each)
|
|
58
|
-
4. Use kebab-case for directory and file names
|
|
59
|
-
5. File name should be a short descriptive slug + `.md`
|
|
18
|
+
**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.
|
|
60
19
|
|
|
61
|
-
|
|
62
|
-
- Generic career thought → `professional/career-direction.md`
|
|
63
|
-
- Decision about a specific company → `professional/companies/acme-corp/joining-decision.md`
|
|
64
|
-
- A specific project issue → `professional/companies/acme-corp/projects/alpha/deployment-incident.md`
|
|
65
|
-
- Learning TypeScript → `personal/education/typescript-generics.md`
|
|
66
|
-
- User prefers dark mode → `personal/preferences/dark-mode.md`
|
|
67
|
-
|
|
68
|
-
**If a memory spans categories**, place it in the most relevant one and note the cross-reference in `related` metadata.
|
|
69
|
-
|
|
70
|
-
### 4. Generate Memory ID
|
|
71
|
-
|
|
72
|
-
Format: `mem_<YYYYMMDD>_<6-char-random-hex>`
|
|
73
|
-
|
|
74
|
-
Example: `mem_20260213_a3f2c1`
|
|
75
|
-
|
|
76
|
-
### 5. Write Memory File
|
|
20
|
+
## Steps
|
|
77
21
|
|
|
78
|
-
|
|
22
|
+
### 1. Determine Content
|
|
79
23
|
|
|
80
|
-
|
|
81
|
-
---
|
|
82
|
-
id: <memory_id>
|
|
83
|
-
type: <memory_type>
|
|
84
|
-
cognitive_type: <episodic|semantic|procedural>
|
|
85
|
-
created: <ISO timestamp>
|
|
86
|
-
last_accessed: <ISO timestamp>
|
|
87
|
-
access_count: 0
|
|
88
|
-
recall_history: []
|
|
89
|
-
strength: <calculated strength 0.0-1.0>
|
|
90
|
-
decay_rate: <decay rate per day>
|
|
91
|
-
salience: <0.0-1.0>
|
|
92
|
-
confidence: <0.0-1.0>
|
|
93
|
-
tags: [<relevant tags>]
|
|
94
|
-
related: [<related memory IDs if any>]
|
|
95
|
-
source: <brief session identifier or context>
|
|
96
|
-
encoding_context:
|
|
97
|
-
project: <current project name>
|
|
98
|
-
topics: [<2-5 key topics from session>]
|
|
99
|
-
task_type: <debugging|implementing|designing|reviewing|discussing|learning>
|
|
100
|
-
---
|
|
24
|
+
If $ARGUMENTS has specific content, use it. If empty, extract the most significant learnings, decisions, insights, or experiences from the current session.
|
|
101
25
|
|
|
102
|
-
|
|
26
|
+
### 2. Classify Each Memory
|
|
103
27
|
|
|
104
|
-
|
|
28
|
+
For each memory, determine:
|
|
105
29
|
|
|
106
|
-
|
|
30
|
+
**Type** (sets base strength/decay — the CLI computes final values):
|
|
31
|
+
- `decision` (0.85/0.995) — Choices made and rationale
|
|
32
|
+
- `insight` (0.90/0.997) — Deep realizations, patterns
|
|
33
|
+
- `goal` (0.80/0.993) — Objectives and aspirations
|
|
34
|
+
- `experience` (0.75/0.985) — Notable events or processes
|
|
35
|
+
- `learning` (0.70/0.990) — New knowledge acquired
|
|
36
|
+
- `relationship` (0.70/0.997) — Connections between entities
|
|
37
|
+
- `preference` (0.60/0.998) — User preferences and style
|
|
38
|
+
- `observation` (0.40/0.950) — Casual facts or notices
|
|
107
39
|
|
|
108
|
-
|
|
40
|
+
**Cognitive type:** `episodic` (event-specific), `semantic` (abstracted knowledge), `procedural` (skills/workflows)
|
|
109
41
|
|
|
110
|
-
|
|
42
|
+
**Path:** Where in `~/.brain/` hierarchy: `professional/`, `personal/`, `social/`, `family/` with kebab-case subdirectories as deep as semantically justified. File name = short slug + `.md`.
|
|
111
43
|
|
|
112
|
-
|
|
44
|
+
**Salience** (0.0-1.0), **confidence** (0.0-1.0), **tags**, **related** memory IDs.
|
|
113
45
|
|
|
114
|
-
|
|
46
|
+
**strength_adjustment** (optional, -0.15 to +0.15): Tweak base strength based on significance.
|
|
115
47
|
|
|
116
|
-
|
|
117
|
-
|
|
48
|
+
**Pinned & stable** (optional, CoALA Phase 1):
|
|
49
|
+
- `pinned: true` — always inject this memory at session start regardless of recall score (and decay-exempt). Optionally `pin_scope: "project:<name>"` (default `"global"`) and `pin_priority: <N>`.
|
|
50
|
+
- `stable: true` — exempt from decay (never fades) without forcing it to always load — for timeless facts recalled on demand.
|
|
51
|
+
- **Propose, don't assume:** when a memory is a durable convention/preference/standing decision (type ∈ {preference, decision, insight, relationship}, high confidence, low time-sensitivity), *suggest* pinning it — but only set `pinned` if the user agrees (or pin later with `/brain:pin`).
|
|
118
52
|
|
|
119
|
-
###
|
|
53
|
+
### 3. Call brain memorize
|
|
120
54
|
|
|
121
|
-
|
|
55
|
+
Pipe the classified memories as JSON to the CLI in a **single bash call**:
|
|
122
56
|
|
|
123
|
-
```
|
|
57
|
+
```bash
|
|
58
|
+
brain memorize <<'EOF'
|
|
124
59
|
{
|
|
125
|
-
"
|
|
126
|
-
|
|
127
|
-
|
|
128
|
-
|
|
129
|
-
|
|
130
|
-
|
|
131
|
-
|
|
132
|
-
|
|
133
|
-
|
|
134
|
-
|
|
135
|
-
|
|
136
|
-
|
|
137
|
-
|
|
138
|
-
|
|
139
|
-
|
|
140
|
-
|
|
141
|
-
|
|
60
|
+
"memories": [
|
|
61
|
+
{
|
|
62
|
+
"title": "Short descriptive title",
|
|
63
|
+
"type": "learning",
|
|
64
|
+
"cognitive_type": "semantic",
|
|
65
|
+
"path": "professional/projects/foo/what-i-learned.md",
|
|
66
|
+
"tags": ["foo", "patterns"],
|
|
67
|
+
"salience": 0.6,
|
|
68
|
+
"confidence": 0.9,
|
|
69
|
+
"strength_adjustment": 0.05,
|
|
70
|
+
"related": [],
|
|
71
|
+
"source": "Session context description",
|
|
72
|
+
"encoding_context": {
|
|
73
|
+
"project": "current-project",
|
|
74
|
+
"topics": ["topic1", "topic2"],
|
|
75
|
+
"task_type": "implementing"
|
|
76
|
+
},
|
|
77
|
+
"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..."
|
|
142
78
|
}
|
|
143
|
-
|
|
79
|
+
]
|
|
144
80
|
}
|
|
81
|
+
EOF
|
|
145
82
|
```
|
|
146
83
|
|
|
147
|
-
|
|
148
|
-
|
|
149
|
-
|
|
150
|
-
|
|
151
|
-
|
|
152
|
-
|
|
153
|
-
**A. Explicit `related` links:** For each ID in the `related` field, create an edge with weight 0.20 and origin `manual`.
|
|
154
|
-
|
|
155
|
-
**B. Auto-discovered links:** Scan `index.json` for other memories sharing **2 or more tags** with this memory. For each match, create an edge with weight 0.10 and origin `tag_overlap`.
|
|
84
|
+
Add `--sync` flag if the user requested it or passed `--sync` to the command:
|
|
85
|
+
```bash
|
|
86
|
+
brain memorize --sync <<'EOF'
|
|
87
|
+
...
|
|
88
|
+
EOF
|
|
89
|
+
```
|
|
156
90
|
|
|
157
|
-
|
|
91
|
+
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.
|
|
158
92
|
|
|
159
|
-
|
|
93
|
+
### 4. Report Results
|
|
160
94
|
|
|
161
|
-
|
|
95
|
+
The CLI outputs JSON with what was stored. Present the results to the user:
|
|
96
|
+
- Memory title, ID, and path
|
|
97
|
+
- Type, strength, tags
|
|
98
|
+
- Edges created
|
|
99
|
+
- Sync result (if applicable)
|
|
162
100
|
|
|
163
|
-
|
|
164
|
-
- Increment `memory_count`
|
|
165
|
-
- Add new subcategories to the `subcategories` array if any were created
|
|
101
|
+
### 5. Resolve contradictions (Tier B §10.2)
|
|
166
102
|
|
|
167
|
-
|
|
103
|
+
If a stored memory's result includes `potential_conflicts`, it shares heavy tag overlap with a **pinned or stable** memory — and pinned/stable facts never decay out of contention, so a stale one is dangerous. **Do not silently keep both.** Inspect the conflicting memory (`brain recall` or read its file) and, if the new memory genuinely contradicts it, propose a resolution to the user:
|
|
104
|
+
- **Supersede** — unpin/forget the old fact, keep the new one (record the supersession).
|
|
105
|
+
- **Keep both, scoped** — e.g. pin each to its own project.
|
|
106
|
+
- **Reject the new one** — the old fact stands.
|
|
168
107
|
|
|
169
|
-
|
|
170
|
-
- Memory title and ID
|
|
171
|
-
- Full path in the brain
|
|
172
|
-
- Assigned type, cognitive type, and strength
|
|
173
|
-
- Salience and confidence levels
|
|
174
|
-
- Tags
|
|
175
|
-
- Association edges created (count and targets)
|
|
176
|
-
- Any new directories that were created
|
|
108
|
+
Never auto-resolve; surface the conflict and let the user decide.
|
|
@@ -0,0 +1,37 @@
|
|
|
1
|
+
---
|
|
2
|
+
description: Pin a memory to the always-present tier
|
|
3
|
+
argument-hint: "[id|query]"
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# /brain:pin — Pin a Memory (Always-Present Tier)
|
|
7
|
+
|
|
8
|
+
You are pinning a memory into the **always-present semantic tier**. Pinned memories are injected at every session start regardless of recall score, and are decay-exempt — they never fade.
|
|
9
|
+
|
|
10
|
+
**User input:** $ARGUMENTS
|
|
11
|
+
|
|
12
|
+
## Behavior
|
|
13
|
+
|
|
14
|
+
1. **Resolve the target memory:**
|
|
15
|
+
- If `$ARGUMENTS` is a memory ID (`mem_...`), use it directly.
|
|
16
|
+
- Otherwise run `brain recall "$ARGUMENTS" --top 5`, show the top matches, and confirm which one to pin.
|
|
17
|
+
|
|
18
|
+
2. **Choose a scope** (default `global`):
|
|
19
|
+
- `global` — loads in every project.
|
|
20
|
+
- `project:<name>` — loads only while working in that project. Use for project-specific conventions.
|
|
21
|
+
|
|
22
|
+
3. **Pin it:**
|
|
23
|
+
```bash
|
|
24
|
+
brain pin <id> [--scope global|project:<name>] [--priority N]
|
|
25
|
+
```
|
|
26
|
+
`--priority` (default 0) breaks ties when the pin budget (`~/.brain/config.json` → `pin_budget_tokens`) is tight; higher wins.
|
|
27
|
+
|
|
28
|
+
4. Confirm:
|
|
29
|
+
```
|
|
30
|
+
📌 Pinned <title> (<scope>) — will load every session.
|
|
31
|
+
```
|
|
32
|
+
|
|
33
|
+
## When to pin
|
|
34
|
+
|
|
35
|
+
Durable conventions, preferences, and standing decisions the agent must **always** honor — e.g. "always use tabs", "deploy via Cloudflare", "never touch the legacy billing module". Good candidates are `preference`, `decision`, `insight`, and `relationship` memories with high confidence and low time-sensitivity.
|
|
36
|
+
|
|
37
|
+
**Do not pin** episodic or time-sensitive content (a one-off incident, a temporary workaround). Those belong in normal recall, where decay can retire them.
|
|
@@ -1,22 +1,19 @@
|
|
|
1
|
+
---
|
|
2
|
+
description: Recall relevant memories with spreading activation and context matching
|
|
3
|
+
argument-hint: "[query]"
|
|
4
|
+
---
|
|
5
|
+
|
|
1
6
|
# /brain:remember — Recall Relevant Memories
|
|
2
7
|
|
|
3
|
-
You are recalling memories from the Brain Memory system. This command
|
|
8
|
+
You are recalling memories from the Brain Memory system. This command uses the **deterministic recall engine** (`brain recall`) to score and rank memories, then presents the results.
|
|
4
9
|
|
|
5
10
|
**User query:** $ARGUMENTS
|
|
6
11
|
|
|
7
12
|
## Steps
|
|
8
13
|
|
|
9
|
-
### 1.
|
|
10
|
-
|
|
11
|
-
Analyze $ARGUMENTS to determine:
|
|
12
|
-
- **Keywords**: Extract key terms and concepts
|
|
13
|
-
- **Category hints**: Does the query suggest a specific life domain? (professional, personal, social, family)
|
|
14
|
-
- **Time hints**: Is the user asking about recent or old memories?
|
|
15
|
-
- **Intent**: Are they looking for a specific memory, a pattern, or general knowledge?
|
|
14
|
+
### 1. Determine Context
|
|
16
15
|
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
Determine the current session context for context-dependent matching:
|
|
16
|
+
Identify the current session context:
|
|
20
17
|
|
|
21
18
|
```yaml
|
|
22
19
|
recall_context:
|
|
@@ -25,51 +22,30 @@ recall_context:
|
|
|
25
22
|
task_type: <debugging|implementing|designing|reviewing|discussing|learning>
|
|
26
23
|
```
|
|
27
24
|
|
|
28
|
-
###
|
|
29
|
-
|
|
30
|
-
Read `.brain/index.json` to get the full memory inventory.
|
|
31
|
-
|
|
32
|
-
**Search strategy (in order):**
|
|
25
|
+
### 2. Run the Recall Engine
|
|
33
26
|
|
|
34
|
-
|
|
35
|
-
2. **Tag matching**: Match query keywords against memory tags
|
|
36
|
-
3. **Title matching**: Match against memory titles in the index
|
|
37
|
-
4. **Full-text search**: If index matching yields few results, read memory files in relevant categories and search content
|
|
27
|
+
Execute the recall CLI to get deterministically scored results:
|
|
38
28
|
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
3. Memories NOT in the initial candidates but reached via spreading activation with bonus >= 0.05 are **added** to the candidate pool (they were "reminded" by association)
|
|
47
|
-
|
|
48
|
-
This implements how the brain works: thinking about topic A naturally activates related topics B and C.
|
|
29
|
+
```bash
|
|
30
|
+
node <brain-memory-install-path>/bin/recall.js "$ARGUMENTS" \
|
|
31
|
+
--project "<project>" \
|
|
32
|
+
--task "<task_type>" \
|
|
33
|
+
--topics "<topic1,topic2>" \
|
|
34
|
+
--top 10
|
|
35
|
+
```
|
|
49
36
|
|
|
50
|
-
|
|
37
|
+
If the brain-memory package is installed globally, use:
|
|
38
|
+
```bash
|
|
39
|
+
brain recall "$ARGUMENTS" --project "<project>" --task "<task_type>" --top 10
|
|
40
|
+
```
|
|
51
41
|
|
|
52
|
-
|
|
42
|
+
The engine computes **TF-IDF relevance** (cosine similarity between query and memory content), then combines it with decayed strength, recency, spreading activation, context match, and salience using the v4 formula. All scoring is deterministic — same query always produces the same ranking.
|
|
53
43
|
|
|
54
|
-
|
|
55
|
-
days_elapsed = (now - last_accessed) / (1000 * 60 * 60 * 24)
|
|
56
|
-
decayed_strength = strength * (decay_rate ^ days_elapsed)
|
|
57
|
-
recency_bonus = max(0, 1 - (days_elapsed / 365))
|
|
58
|
-
spreading_bonus = <computed in step 3.5, 0 if not reached via associations>
|
|
59
|
-
context_match = 0.3*(project matches) + 0.4*jaccard(topics) + 0.3*(task_type matches)
|
|
60
|
-
salience_bonus = salience (from memory frontmatter, default 0.5)
|
|
61
|
-
|
|
62
|
-
effective_score = 0.38 * relevance
|
|
63
|
-
+ 0.18 * decayed_strength
|
|
64
|
-
+ 0.08 * recency_bonus
|
|
65
|
-
+ 0.14 * spreading_bonus
|
|
66
|
-
+ 0.14 * context_match
|
|
67
|
-
+ 0.08 * salience_bonus
|
|
68
|
-
```
|
|
44
|
+
### 3. Read Top Memories
|
|
69
45
|
|
|
70
|
-
|
|
46
|
+
Parse the JSON output. For the top results (score > 0.3), read the actual memory files from `~/.brain/<path>` to get full content.
|
|
71
47
|
|
|
72
|
-
###
|
|
48
|
+
### 4. Decide Response Strategy
|
|
73
49
|
|
|
74
50
|
Based on the scored results:
|
|
75
51
|
|
|
@@ -81,68 +57,49 @@ Read all candidate memory files and synthesize a **consolidated response** that:
|
|
|
81
57
|
- Weaves together insights from all relevant memories
|
|
82
58
|
- Notes which memories contributed (by ID and title)
|
|
83
59
|
- Highlights patterns or evolution across memories
|
|
84
|
-
- Presents the most current/relevant information prominently
|
|
85
60
|
|
|
86
61
|
**Case C — Many weak matches (>5 candidates, all scores < 0.4):**
|
|
87
|
-
List the top 5-7 memories with titles, paths, types, and
|
|
62
|
+
List the top 5-7 memories with titles, paths, types, and scores.
|
|
88
63
|
Ask the user which ones they'd like to explore in detail.
|
|
89
64
|
|
|
90
|
-
**Case D — No matches
|
|
91
|
-
Search
|
|
92
|
-
- Present them with a note that they're archived
|
|
93
|
-
- Offer to restore them (move back to active brain with strength +0.10)
|
|
65
|
+
**Case D — No matches:**
|
|
66
|
+
Search `~/.brain/_archived/` via the archive index. If archived matches found, present them and offer to restore. Otherwise suggest different keywords or `/brain:explore`.
|
|
94
67
|
|
|
95
|
-
|
|
96
|
-
- Trying different keywords
|
|
97
|
-
- Exploring the brain structure with `/brain:explore`
|
|
98
|
-
- Storing new memories with `/brain:memorize`
|
|
68
|
+
### 5. Reinforce Retrieved Memories
|
|
99
69
|
|
|
100
|
-
|
|
70
|
+
After presenting results, run the reinforcement engine for all memories shown to the user:
|
|
101
71
|
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
**Calculate spacing-aware boost:**
|
|
105
|
-
```
|
|
106
|
-
daysSinceLastAccess = (now - last_accessed) / (1000 * 60 * 60 * 24)
|
|
107
|
-
recallCount = access_count (or len(recall_history))
|
|
108
|
-
spacingMultiplier = min(3.0, 1.0 + log2(1 + daysSinceLastAccess))
|
|
109
|
-
diminishingFactor = 1.0 / (1.0 + 0.1 * recallCount)
|
|
110
|
-
boost = 0.05 * spacingMultiplier * diminishingFactor
|
|
72
|
+
```bash
|
|
73
|
+
node <brain-memory-install-path>/bin/reinforce.js <mem_id1> <mem_id2> ...
|
|
111
74
|
```
|
|
112
75
|
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
- `access_count` → increment by 1
|
|
118
|
-
- `recall_history` → append current timestamp
|
|
119
|
-
- `strength` → min(1.0, strength + boost)
|
|
120
|
-
- `decay_rate` → improved via: `decay_rate + 0.10 * (0.999 - decay_rate)` (memories become progressively more forgetting-resistant)
|
|
121
|
-
|
|
122
|
-
### 7. Hebbian Co-Retrieval Learning
|
|
123
|
-
|
|
124
|
-
When multiple memories are returned together (Case B), strengthen their mutual association edges in `associations.json`:
|
|
125
|
-
- For each pair of retrieved memories, call `reinforceEdge()` with origin `co_retrieval`
|
|
126
|
-
- This implements "neurons that fire together wire together" — memories recalled in the same context become more tightly linked over time
|
|
76
|
+
Or if globally installed:
|
|
77
|
+
```bash
|
|
78
|
+
brain reinforce <mem_id1> <mem_id2> ...
|
|
79
|
+
```
|
|
127
80
|
|
|
128
|
-
|
|
81
|
+
This deterministically applies:
|
|
82
|
+
- **Spaced reinforcement** — strength boost based on time since last access
|
|
83
|
+
- **Decay rate improvement** — memories become more forgetting-resistant
|
|
84
|
+
- **Hebbian co-retrieval** — strengthens association edges between all returned memories
|
|
129
85
|
|
|
130
|
-
###
|
|
86
|
+
### 6. Present Results
|
|
131
87
|
|
|
132
88
|
Format the output clearly. Include confidence indicators for low-confidence memories.
|
|
133
89
|
|
|
134
90
|
```
|
|
135
91
|
## Recalled Memory: <Title>
|
|
136
92
|
|
|
137
|
-
**Path:**
|
|
93
|
+
**Path:** ~/.brain/<path>
|
|
138
94
|
**Strength:** <decayed_strength> (original: <base_strength>)
|
|
95
|
+
**Score:** <score> (relevance: <relevance>, context: <context_match>)
|
|
139
96
|
**Type:** <type> (<cognitive_type>) | **Created:** <date> | **Recalled:** <access_count> times
|
|
140
|
-
**Confidence:** <confidence> <show
|
|
97
|
+
**Confidence:** <confidence> <show warning if < 0.5>
|
|
141
98
|
|
|
142
99
|
<memory content>
|
|
143
100
|
|
|
144
101
|
---
|
|
145
|
-
*Memory reinforced — strength updated
|
|
102
|
+
*Memory reinforced — strength updated, decay improved*
|
|
146
103
|
```
|
|
147
104
|
|
|
148
105
|
For consolidated responses (Case B):
|
|
@@ -153,24 +110,10 @@ For consolidated responses (Case B):
|
|
|
153
110
|
<consolidated narrative>
|
|
154
111
|
|
|
155
112
|
### Contributing Memories
|
|
156
|
-
1. **<title>** (
|
|
157
|
-
2. **<title>** (
|
|
113
|
+
1. **<title>** (~/.brain/<path>) — score: <score>
|
|
114
|
+
2. **<title>** (~/.brain/<path>) — score: <score>
|
|
158
115
|
...
|
|
159
116
|
|
|
160
117
|
---
|
|
161
|
-
*<N> memories reinforced,
|
|
162
|
-
```
|
|
163
|
-
|
|
164
|
-
For archived matches (Case D fallback):
|
|
165
|
-
|
|
166
|
-
```
|
|
167
|
-
## Found in Archive: <Title>
|
|
168
|
-
|
|
169
|
-
**Path:** .brain/_archived/<path>
|
|
170
|
-
**Original Strength:** <strength> | **Archived:** <date>
|
|
171
|
-
|
|
172
|
-
<memory content summary>
|
|
173
|
-
|
|
174
|
-
---
|
|
175
|
-
*Would you like to restore this memory to active brain?*
|
|
118
|
+
*<N> memories reinforced, association links strengthened*
|
|
176
119
|
```
|
package/commands/brain/review.md
CHANGED
|
@@ -1,3 +1,8 @@
|
|
|
1
|
+
---
|
|
2
|
+
description: Spaced-repetition review session for memories due for reinforcement
|
|
3
|
+
argument-hint: "[scope]"
|
|
4
|
+
---
|
|
5
|
+
|
|
1
6
|
# /brain:review — Spaced Repetition Review
|
|
2
7
|
|
|
3
8
|
You are conducting a spaced repetition review session. This command surfaces memories that are due for review based on optimal spacing intervals, measures recall quality, and schedules the next review. Regular review sessions dramatically improve long-term retention.
|
|
@@ -12,7 +17,7 @@ This implements a simplified SM-2 (SuperMemo 2) spaced repetition algorithm. Mem
|
|
|
12
17
|
|
|
13
18
|
### 1. Load Review Queue
|
|
14
19
|
|
|
15
|
-
Read
|
|
20
|
+
Read `~/.brain/review-queue.json`. If it doesn't exist or is empty, generate it:
|
|
16
21
|
- Scan all memories in `index.json`
|
|
17
22
|
- For memories with `access_count > 0`, calculate initial review schedule
|
|
18
23
|
- For memories never recalled, add with `next_review` = now (immediate first review)
|
|
@@ -41,7 +46,7 @@ For each due memory (process up to 10 per session):
|
|
|
41
46
|
### Review 1 of <N>
|
|
42
47
|
|
|
43
48
|
**Memory:** <title>
|
|
44
|
-
**Path:**
|
|
49
|
+
**Path:** ~/.brain/<path>
|
|
45
50
|
**Type:** <type> (<cognitive_type>) | **Last reviewed:** <date> | **Interval:** <days>d
|
|
46
51
|
**Confidence:** <confidence>
|
|
47
52
|
|
|
@@ -0,0 +1,60 @@
|
|
|
1
|
+
---
|
|
2
|
+
description: Manage procedural skills (list, show, add, use, remove, export)
|
|
3
|
+
argument-hint: "[subcommand]"
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# /brain:skills — Manage Procedural Skills
|
|
7
|
+
|
|
8
|
+
You are managing **procedural memory** — reusable "how to do things" stored as `~/.brain/_skills/<name>/SKILL.md`. Skills use **progressive disclosure** so they never bloat the context window:
|
|
9
|
+
|
|
10
|
+
- **L0 (session start):** only each skill's name + description is advertised (≈100 tokens each).
|
|
11
|
+
- **L1 (on a matching task):** read the full `SKILL.md` for step-by-step instructions.
|
|
12
|
+
- **L2 (at execution):** load any referenced `resources/` (templates, scripts) only when a step needs them.
|
|
13
|
+
|
|
14
|
+
**User input:** $ARGUMENTS
|
|
15
|
+
|
|
16
|
+
## Actions
|
|
17
|
+
|
|
18
|
+
**List** advertised skills:
|
|
19
|
+
```bash
|
|
20
|
+
brain skill list
|
|
21
|
+
```
|
|
22
|
+
|
|
23
|
+
**Show** a skill's full instructions (do this when a task matches a skill's description/triggers):
|
|
24
|
+
```bash
|
|
25
|
+
brain skill show <name>
|
|
26
|
+
```
|
|
27
|
+
|
|
28
|
+
**Add** a skill — pipe JSON on stdin:
|
|
29
|
+
```bash
|
|
30
|
+
brain skill add <<'EOF'
|
|
31
|
+
{
|
|
32
|
+
"name": "structured-code-review",
|
|
33
|
+
"description": "One-paragraph advertised summary used for matching (~100 tokens).",
|
|
34
|
+
"triggers": ["code review", "review PR", "audit changes"],
|
|
35
|
+
"body": "## Steps\n1. ...\n2. ..."
|
|
36
|
+
}
|
|
37
|
+
EOF
|
|
38
|
+
```
|
|
39
|
+
|
|
40
|
+
**Use** — record an outcome after running a skill. Success strengthens it; `--failed` weakens it (a skill that fails too often demotes itself out of the advertised L0 index):
|
|
41
|
+
```bash
|
|
42
|
+
brain skill use <name> # succeeded
|
|
43
|
+
brain skill use <name> --failed # produced a bad outcome
|
|
44
|
+
```
|
|
45
|
+
|
|
46
|
+
**Remove** a skill:
|
|
47
|
+
```bash
|
|
48
|
+
brain skill remove <name>
|
|
49
|
+
```
|
|
50
|
+
|
|
51
|
+
**Export** a skill into the host agent's native format so it becomes directly executable (writes `.claude/skills/<name>/SKILL.md` or `.gemini/...` in the current project):
|
|
52
|
+
```bash
|
|
53
|
+
brain skill export <name> [--target claude|gemini]
|
|
54
|
+
```
|
|
55
|
+
|
|
56
|
+
## Guidance
|
|
57
|
+
|
|
58
|
+
- Advertise skills with a **crisp, matchable description** — that single line is all the agent sees at L0, so it must convey when to reach for the skill.
|
|
59
|
+
- Reach for `show` only when a task genuinely matches; don't pre-load skills speculatively.
|
|
60
|
+
- Always record the outcome with `use` (success or `--failed`) so the strength/demotion feedback loop stays accurate.
|