brain-memory 0.1.0-beta.1
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/LICENSE +21 -0
- package/README.md +466 -0
- package/bin/install.js +361 -0
- package/commands/brain/consolidate.md +153 -0
- package/commands/brain/explore.md +79 -0
- package/commands/brain/forget.md +115 -0
- package/commands/brain/init.md +157 -0
- package/commands/brain/memorize.md +176 -0
- package/commands/brain/remember.md +176 -0
- package/commands/brain/review.md +130 -0
- package/commands/brain/sleep.md +535 -0
- package/commands/brain/status.md +122 -0
- package/commands/brain/sunshine.md +337 -0
- package/hooks/session-end.md +48 -0
- package/hooks/session-start.md +48 -0
- package/package.json +46 -0
- package/prompts/claude.md +75 -0
- package/prompts/gemini.md +76 -0
- package/prompts/openai.md +76 -0
- package/src/index-manager.js +401 -0
- package/src/scorer.js +452 -0
- package/templates/default-categories.json +82 -0
|
@@ -0,0 +1,115 @@
|
|
|
1
|
+
# /brain:forget — Decay or Remove Memories
|
|
2
|
+
|
|
3
|
+
You are managing memory decay in the Brain Memory system. This command accelerates forgetting for specific memories or prunes memories that have naturally decayed below usefulness.
|
|
4
|
+
|
|
5
|
+
**Target:** $ARGUMENTS
|
|
6
|
+
|
|
7
|
+
## Steps
|
|
8
|
+
|
|
9
|
+
### 1. Determine Mode
|
|
10
|
+
|
|
11
|
+
Based on $ARGUMENTS:
|
|
12
|
+
|
|
13
|
+
**Mode A — Targeted forget** (e.g., "/brain:forget kubernetes deployment issue"):
|
|
14
|
+
Find specific memories matching the query and offer to accelerate their decay or remove them.
|
|
15
|
+
|
|
16
|
+
**Mode B — Threshold prune** (e.g., "/brain:forget --prune" or "/brain:forget --prune 0.2"):
|
|
17
|
+
Find all memories whose effective (decayed) strength is below the given threshold (default: 0.2) and offer to archive them.
|
|
18
|
+
|
|
19
|
+
**Mode C — Category prune** (e.g., "/brain:forget professional/companies/old-corp"):
|
|
20
|
+
Apply decay/removal to an entire category subtree.
|
|
21
|
+
|
|
22
|
+
### 2. Find Affected Memories
|
|
23
|
+
|
|
24
|
+
Read `index.json` and compute effective (decayed) strength for each candidate:
|
|
25
|
+
|
|
26
|
+
```
|
|
27
|
+
days_elapsed = (now - last_accessed) / (1000 * 60 * 60 * 24)
|
|
28
|
+
decayed_strength = strength * (decay_rate ^ days_elapsed)
|
|
29
|
+
```
|
|
30
|
+
|
|
31
|
+
For Mode A: Match query against titles, tags, and paths.
|
|
32
|
+
For Mode B: Filter by decayed strength < threshold.
|
|
33
|
+
For Mode C: Filter by path prefix.
|
|
34
|
+
|
|
35
|
+
**Salience protection**: Flag any memories with `salience >= 0.7` — these require explicit `/brain:forget` with direct confirmation (never included in bulk prune operations).
|
|
36
|
+
|
|
37
|
+
### 3. Present Candidates
|
|
38
|
+
|
|
39
|
+
Show the user what would be affected:
|
|
40
|
+
|
|
41
|
+
```
|
|
42
|
+
## Memories to Forget
|
|
43
|
+
|
|
44
|
+
| # | Title | Path | Strength | Decayed | Salience | Age |
|
|
45
|
+
|---|-------|------|----------|---------|----------|-----|
|
|
46
|
+
| 1 | K8s Config Issue | professional/companies/acme/k8s-config.md | 0.40 | 0.12 | 0.3 | 94d |
|
|
47
|
+
| 2 | Old Deploy Notes | professional/companies/acme/deploy-v1.md | 0.35 | 0.08 | 0.2 | 120d |
|
|
48
|
+
|
|
49
|
+
⚡ Salience-protected (requires explicit confirmation):
|
|
50
|
+
| 3 | Critical Auth Fix | professional/security/auth-fix.md | 0.30 | 0.05 | 0.9 | 200d |
|
|
51
|
+
|
|
52
|
+
**Action options:**
|
|
53
|
+
- **Archive**: Move to `_archived/` (recoverable, searchable via /brain:remember)
|
|
54
|
+
- **Accelerate decay**: Set decay_rate to 0.90 (fast fade)
|
|
55
|
+
- **Delete permanently**: Remove files entirely (not recoverable)
|
|
56
|
+
```
|
|
57
|
+
|
|
58
|
+
### 4. Get User Confirmation
|
|
59
|
+
|
|
60
|
+
The user must explicitly choose an action. Default to **archive** (safest).
|
|
61
|
+
|
|
62
|
+
**IMPORTANT:** Never delete memories without explicit user confirmation.
|
|
63
|
+
|
|
64
|
+
### 5. Execute
|
|
65
|
+
|
|
66
|
+
**Archive:**
|
|
67
|
+
- Move memory files to `.brain/_archived/<original-path>/`
|
|
68
|
+
- Add entry to `.brain/_archived/index.json` with all original metadata:
|
|
69
|
+
```json
|
|
70
|
+
{
|
|
71
|
+
"<memory_id>": {
|
|
72
|
+
"path": "<original path>",
|
|
73
|
+
"archived_path": "<path in _archived/>",
|
|
74
|
+
"title": "<title>",
|
|
75
|
+
"type": "<type>",
|
|
76
|
+
"cognitive_type": "<cognitive_type>",
|
|
77
|
+
"strength": <strength at archival>,
|
|
78
|
+
"salience": <salience>,
|
|
79
|
+
"confidence": <confidence>,
|
|
80
|
+
"tags": ["<tags>"],
|
|
81
|
+
"archived_date": "<ISO timestamp>",
|
|
82
|
+
"archived_reason": "<user-specified or auto>"
|
|
83
|
+
}
|
|
84
|
+
}
|
|
85
|
+
```
|
|
86
|
+
- Remove entries from `index.json` `memories`
|
|
87
|
+
- Remove from `review-queue.json` if present
|
|
88
|
+
- Remove association edges involving this memory from `associations.json`
|
|
89
|
+
- Decrement `memory_count` in index and relevant `_meta.json` files
|
|
90
|
+
- Update `last_updated`
|
|
91
|
+
|
|
92
|
+
**Accelerate decay:**
|
|
93
|
+
- Set `decay_rate` to 0.90 in the memory file's frontmatter
|
|
94
|
+
- Update `index.json` entry
|
|
95
|
+
- Memory will naturally fade in subsequent sleep cycles
|
|
96
|
+
|
|
97
|
+
**Delete permanently:**
|
|
98
|
+
- Remove memory files
|
|
99
|
+
- Remove entries from `index.json`
|
|
100
|
+
- Remove from `review-queue.json` if present
|
|
101
|
+
- Remove association edges from `associations.json`
|
|
102
|
+
- Update `_meta.json` files
|
|
103
|
+
- Clean up empty directories
|
|
104
|
+
|
|
105
|
+
### 6. Suggest Consolidation
|
|
106
|
+
|
|
107
|
+
If any remaining memories in the affected area are also weak (decayed strength < 0.4), suggest running `/brain:consolidate` on that category to preserve the knowledge in a more durable form before it fades.
|
|
108
|
+
|
|
109
|
+
### 7. Confirm
|
|
110
|
+
|
|
111
|
+
Print summary:
|
|
112
|
+
- Number of memories affected
|
|
113
|
+
- Action taken (archived/accelerated/deleted)
|
|
114
|
+
- Current brain stats (total memories, average strength)
|
|
115
|
+
- Archive searchability note: "Archived memories are searchable via /brain:remember if needed in the future"
|
|
@@ -0,0 +1,157 @@
|
|
|
1
|
+
# /brain:init — Initialize Brain Memory Structure
|
|
2
|
+
|
|
3
|
+
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
|
+
|
|
5
|
+
## Steps
|
|
6
|
+
|
|
7
|
+
### 1. Check for Existing Brain
|
|
8
|
+
|
|
9
|
+
Check if `.brain/` directory already exists in the current project root.
|
|
10
|
+
|
|
11
|
+
- If it exists, inform the user and ask if they want to reset or keep it.
|
|
12
|
+
- If not, proceed with creation.
|
|
13
|
+
|
|
14
|
+
### 2. Create Directory Structure
|
|
15
|
+
|
|
16
|
+
Create the following structure:
|
|
17
|
+
|
|
18
|
+
```
|
|
19
|
+
.brain/
|
|
20
|
+
├── index.json
|
|
21
|
+
├── associations.json
|
|
22
|
+
├── contexts.json
|
|
23
|
+
├── review-queue.json
|
|
24
|
+
├── professional/
|
|
25
|
+
│ └── _meta.json
|
|
26
|
+
├── personal/
|
|
27
|
+
│ └── _meta.json
|
|
28
|
+
├── social/
|
|
29
|
+
│ └── _meta.json
|
|
30
|
+
├── family/
|
|
31
|
+
│ └── _meta.json
|
|
32
|
+
├── _consolidated/
|
|
33
|
+
│ └── _meta.json
|
|
34
|
+
└── _archived/
|
|
35
|
+
└── index.json
|
|
36
|
+
```
|
|
37
|
+
|
|
38
|
+
### 3. Create index.json
|
|
39
|
+
|
|
40
|
+
```json
|
|
41
|
+
{
|
|
42
|
+
"version": 2,
|
|
43
|
+
"created": "<current ISO timestamp>",
|
|
44
|
+
"last_updated": "<current ISO timestamp>",
|
|
45
|
+
"memory_count": 0,
|
|
46
|
+
"memories": {},
|
|
47
|
+
"config": {
|
|
48
|
+
"max_depth": 6,
|
|
49
|
+
"consolidation_threshold": 0.3,
|
|
50
|
+
"decay_check_interval_days": 7,
|
|
51
|
+
"strength_boost_on_recall": 0.05,
|
|
52
|
+
"auto_consolidate": true,
|
|
53
|
+
"propagation_window_days": 7,
|
|
54
|
+
"association_config": {
|
|
55
|
+
"co_retrieval_boost": 0.10,
|
|
56
|
+
"link_decay_rate": 0.998,
|
|
57
|
+
"link_prune_threshold": 0.05,
|
|
58
|
+
"spreading_activation_depth": 2,
|
|
59
|
+
"spreading_activation_decay": 0.5
|
|
60
|
+
}
|
|
61
|
+
}
|
|
62
|
+
}
|
|
63
|
+
```
|
|
64
|
+
|
|
65
|
+
### 4. Create associations.json
|
|
66
|
+
|
|
67
|
+
The associative network stores weighted connections between memories — implementing spreading activation (like neurons activating linked memories) and Hebbian learning (memories that fire together wire together).
|
|
68
|
+
|
|
69
|
+
```json
|
|
70
|
+
{
|
|
71
|
+
"version": 1,
|
|
72
|
+
"edges": {}
|
|
73
|
+
}
|
|
74
|
+
```
|
|
75
|
+
|
|
76
|
+
### 5. Create contexts.json
|
|
77
|
+
|
|
78
|
+
Stores session-level context snapshots used for context-dependent recall — memories encoded in a similar context to the current one are scored higher.
|
|
79
|
+
|
|
80
|
+
```json
|
|
81
|
+
{
|
|
82
|
+
"version": 1,
|
|
83
|
+
"sessions": []
|
|
84
|
+
}
|
|
85
|
+
```
|
|
86
|
+
|
|
87
|
+
### 6. Create review-queue.json
|
|
88
|
+
|
|
89
|
+
Implements spaced repetition scheduling — surfaces memories for review at optimal intervals to maximize long-term retention.
|
|
90
|
+
|
|
91
|
+
```json
|
|
92
|
+
{
|
|
93
|
+
"version": 1,
|
|
94
|
+
"items": []
|
|
95
|
+
}
|
|
96
|
+
```
|
|
97
|
+
|
|
98
|
+
### 7. Create _archived/index.json
|
|
99
|
+
|
|
100
|
+
A searchable index of archived memories so they can be found and restored if needed.
|
|
101
|
+
|
|
102
|
+
```json
|
|
103
|
+
{
|
|
104
|
+
"version": 1,
|
|
105
|
+
"archived_count": 0,
|
|
106
|
+
"memories": {}
|
|
107
|
+
}
|
|
108
|
+
```
|
|
109
|
+
|
|
110
|
+
### 8. Create _meta.json for Each Top Category
|
|
111
|
+
|
|
112
|
+
For each top-level category (professional, personal, social, family, _consolidated), create a `_meta.json`:
|
|
113
|
+
|
|
114
|
+
```json
|
|
115
|
+
{
|
|
116
|
+
"category": "<category_name>",
|
|
117
|
+
"description": "<description from defaults>",
|
|
118
|
+
"created": "<current ISO timestamp>",
|
|
119
|
+
"memory_count": 0,
|
|
120
|
+
"subcategories": []
|
|
121
|
+
}
|
|
122
|
+
```
|
|
123
|
+
|
|
124
|
+
### 9. Ask User for Customization (Optional)
|
|
125
|
+
|
|
126
|
+
Ask the user:
|
|
127
|
+
- "Would you like to add any custom top-level categories beyond the defaults (professional, personal, social, family)?"
|
|
128
|
+
- "Do you have specific subcategories you'd like pre-created? (e.g., a company name under professional/companies/)"
|
|
129
|
+
|
|
130
|
+
If the user provides custom categories or subcategories, create them with appropriate `_meta.json` files.
|
|
131
|
+
|
|
132
|
+
### 10. Add .brain to .gitignore (Optional)
|
|
133
|
+
|
|
134
|
+
Ask the user if they want `.brain/` added to `.gitignore` (some users may want to track their memory in git, others may not).
|
|
135
|
+
|
|
136
|
+
### 11. Confirm
|
|
137
|
+
|
|
138
|
+
Print a summary of what was created, including the full tree structure. Inform the user of available commands:
|
|
139
|
+
|
|
140
|
+
- `/brain:memorize` — Store a new memory
|
|
141
|
+
- `/brain:remember` — Recall relevant memories
|
|
142
|
+
- `/brain:explore` — Browse the brain structure
|
|
143
|
+
- `/brain:consolidate` — Merge related memories
|
|
144
|
+
- `/brain:forget` — Decay or remove memories
|
|
145
|
+
- `/brain:sunshine` — Deep forensic erasure: trace and remove all references to a memory
|
|
146
|
+
- `/brain:sleep` — Overnight reorganization: restructure, consolidate, prune, and detect expertise areas
|
|
147
|
+
- `/brain:status` — View brain overview
|
|
148
|
+
- `/brain:review` — Spaced repetition review of memories due for reinforcement
|
|
149
|
+
|
|
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
|
|
@@ -0,0 +1,176 @@
|
|
|
1
|
+
# /brain:memorize — Store a New Memory
|
|
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.
|
|
4
|
+
|
|
5
|
+
**User input:** $ARGUMENTS
|
|
6
|
+
|
|
7
|
+
## Steps
|
|
8
|
+
|
|
9
|
+
### 1. Determine Memory Content
|
|
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)
|
|
51
|
+
|
|
52
|
+
Choose the most appropriate path in the `.brain/` hierarchy. This is the most critical step.
|
|
53
|
+
|
|
54
|
+
**Rules for path selection:**
|
|
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`
|
|
60
|
+
|
|
61
|
+
**Depth guidelines:**
|
|
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
|
|
77
|
+
|
|
78
|
+
Create the memory file at the determined path with this format:
|
|
79
|
+
|
|
80
|
+
```markdown
|
|
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
|
+
---
|
|
101
|
+
|
|
102
|
+
# <Short Descriptive Title>
|
|
103
|
+
|
|
104
|
+
<2-5 sentence summary of the memory. Be specific and actionable. Include the WHY, not just the WHAT.>
|
|
105
|
+
|
|
106
|
+
## Context
|
|
107
|
+
|
|
108
|
+
<1-3 sentences about the circumstances — when, where, what was happening>
|
|
109
|
+
|
|
110
|
+
## Key Details
|
|
111
|
+
|
|
112
|
+
<Bullet points of the most important specifics>
|
|
113
|
+
|
|
114
|
+
## Connections
|
|
115
|
+
|
|
116
|
+
<How this relates to other knowledge, patterns, or goals — if applicable>
|
|
117
|
+
```
|
|
118
|
+
|
|
119
|
+
### 6. Update Index
|
|
120
|
+
|
|
121
|
+
Read `.brain/index.json` and add an entry:
|
|
122
|
+
|
|
123
|
+
```json
|
|
124
|
+
{
|
|
125
|
+
"<memory_id>": {
|
|
126
|
+
"path": "<relative path from .brain/>",
|
|
127
|
+
"title": "<short title>",
|
|
128
|
+
"type": "<memory_type>",
|
|
129
|
+
"cognitive_type": "<episodic|semantic|procedural>",
|
|
130
|
+
"strength": <strength>,
|
|
131
|
+
"decay_rate": <decay_rate>,
|
|
132
|
+
"salience": <salience>,
|
|
133
|
+
"confidence": <confidence>,
|
|
134
|
+
"created": "<ISO timestamp>",
|
|
135
|
+
"last_accessed": "<ISO timestamp>",
|
|
136
|
+
"access_count": 0,
|
|
137
|
+
"tags": ["<tags>"],
|
|
138
|
+
"encoding_context": {
|
|
139
|
+
"project": "<project>",
|
|
140
|
+
"topics": ["<topics>"],
|
|
141
|
+
"task_type": "<task_type>"
|
|
142
|
+
}
|
|
143
|
+
}
|
|
144
|
+
}
|
|
145
|
+
```
|
|
146
|
+
|
|
147
|
+
Increment `memory_count`. Update `last_updated`.
|
|
148
|
+
|
|
149
|
+
### 7. Update Associations
|
|
150
|
+
|
|
151
|
+
Read `.brain/associations.json` and create edges for this memory:
|
|
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`.
|
|
156
|
+
|
|
157
|
+
Use the `reinforceEdge()` function — if an edge already exists (e.g., the related memory already links back), it will be strengthened via Hebbian reinforcement instead of creating a duplicate.
|
|
158
|
+
|
|
159
|
+
Write the updated `associations.json`.
|
|
160
|
+
|
|
161
|
+
### 8. Update _meta.json
|
|
162
|
+
|
|
163
|
+
Update the `_meta.json` in each directory along the path:
|
|
164
|
+
- Increment `memory_count`
|
|
165
|
+
- Add new subcategories to the `subcategories` array if any were created
|
|
166
|
+
|
|
167
|
+
### 9. Confirm
|
|
168
|
+
|
|
169
|
+
Print what was stored:
|
|
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
|
|
@@ -0,0 +1,176 @@
|
|
|
1
|
+
# /brain:remember — Recall Relevant Memories
|
|
2
|
+
|
|
3
|
+
You are recalling memories from the Brain Memory system. This command searches the `.brain/` hierarchy, scores memories by relevance, strength, associative links, and context match, and returns the most useful memories — either individually or as a consolidated synthesis.
|
|
4
|
+
|
|
5
|
+
**User query:** $ARGUMENTS
|
|
6
|
+
|
|
7
|
+
## Steps
|
|
8
|
+
|
|
9
|
+
### 1. Parse the Query
|
|
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?
|
|
16
|
+
|
|
17
|
+
### 2. Capture Recall Context
|
|
18
|
+
|
|
19
|
+
Determine the current session context for context-dependent matching:
|
|
20
|
+
|
|
21
|
+
```yaml
|
|
22
|
+
recall_context:
|
|
23
|
+
project: <current project name>
|
|
24
|
+
topics: [<key topics from query and session>]
|
|
25
|
+
task_type: <debugging|implementing|designing|reviewing|discussing|learning>
|
|
26
|
+
```
|
|
27
|
+
|
|
28
|
+
### 3. Search the Brain
|
|
29
|
+
|
|
30
|
+
Read `.brain/index.json` to get the full memory inventory.
|
|
31
|
+
|
|
32
|
+
**Search strategy (in order):**
|
|
33
|
+
|
|
34
|
+
1. **Category-first**: If the query clearly maps to a category, traverse that subtree first
|
|
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
|
|
38
|
+
|
|
39
|
+
Collect all candidate memories.
|
|
40
|
+
|
|
41
|
+
### 3.5. Spreading Activation
|
|
42
|
+
|
|
43
|
+
Read `.brain/associations.json`. For each candidate memory scoring > 0.3 in initial relevance:
|
|
44
|
+
1. Traverse the association graph up to 2 hops
|
|
45
|
+
2. For each reached memory: `spread_bonus = parent_score * link_weight * 0.5^hop`
|
|
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.
|
|
49
|
+
|
|
50
|
+
### 4. Score Candidates
|
|
51
|
+
|
|
52
|
+
For each candidate memory, compute an **effective score** using the v4 formula:
|
|
53
|
+
|
|
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
|
+
```
|
|
69
|
+
|
|
70
|
+
**Note:** If a memory lacks newer fields (spreading_bonus, context_match, salience), the formula renormalizes weights across the available terms. This ensures backward compatibility with v1 memories.
|
|
71
|
+
|
|
72
|
+
### 5. Decide Response Strategy
|
|
73
|
+
|
|
74
|
+
Based on the scored results:
|
|
75
|
+
|
|
76
|
+
**Case A — Single strong match (top score > 0.7 and 2x higher than second):**
|
|
77
|
+
Return the full memory content directly.
|
|
78
|
+
|
|
79
|
+
**Case B — Multiple related memories (2-5 candidates with scores > 0.4):**
|
|
80
|
+
Read all candidate memory files and synthesize a **consolidated response** that:
|
|
81
|
+
- Weaves together insights from all relevant memories
|
|
82
|
+
- Notes which memories contributed (by ID and title)
|
|
83
|
+
- Highlights patterns or evolution across memories
|
|
84
|
+
- Presents the most current/relevant information prominently
|
|
85
|
+
|
|
86
|
+
**Case C — Many weak matches (>5 candidates, all scores < 0.4):**
|
|
87
|
+
List the top 5-7 memories with titles, paths, types, and effective scores.
|
|
88
|
+
Ask the user which ones they'd like to explore in detail.
|
|
89
|
+
|
|
90
|
+
**Case D — No matches in active brain:**
|
|
91
|
+
Search `.brain/_archived/` via the archive index (`_archived/index.json`). If archived matches are found with relevance > 0.3:
|
|
92
|
+
- Present them with a note that they're archived
|
|
93
|
+
- Offer to restore them (move back to active brain with strength +0.10)
|
|
94
|
+
|
|
95
|
+
If still no matches, inform the user and suggest:
|
|
96
|
+
- Trying different keywords
|
|
97
|
+
- Exploring the brain structure with `/brain:explore`
|
|
98
|
+
- Storing new memories with `/brain:memorize`
|
|
99
|
+
|
|
100
|
+
### 6. Reinforce Retrieved Memories (Spaced Reinforcement)
|
|
101
|
+
|
|
102
|
+
For every memory that was returned to the user (Cases A and B), apply spaced reinforcement:
|
|
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
|
|
111
|
+
```
|
|
112
|
+
|
|
113
|
+
Examples: 1 day gap = +0.05 (same as v1), 7 days = +0.08, 30 days = +0.10, cramming same day 20th recall = +0.02.
|
|
114
|
+
|
|
115
|
+
**Update in both the memory file AND index.json:**
|
|
116
|
+
- `last_accessed` → current timestamp
|
|
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
|
|
127
|
+
|
|
128
|
+
Write the updated `associations.json`.
|
|
129
|
+
|
|
130
|
+
### 8. Present Results
|
|
131
|
+
|
|
132
|
+
Format the output clearly. Include confidence indicators for low-confidence memories.
|
|
133
|
+
|
|
134
|
+
```
|
|
135
|
+
## Recalled Memory: <Title>
|
|
136
|
+
|
|
137
|
+
**Path:** .brain/<path>
|
|
138
|
+
**Strength:** <decayed_strength> (original: <base_strength>)
|
|
139
|
+
**Type:** <type> (<cognitive_type>) | **Created:** <date> | **Recalled:** <access_count> times
|
|
140
|
+
**Confidence:** <confidence> <show ⚠️ if < 0.5>
|
|
141
|
+
|
|
142
|
+
<memory content>
|
|
143
|
+
|
|
144
|
+
---
|
|
145
|
+
*Memory reinforced — strength updated to <new_strength>, decay improved to <new_decay_rate>*
|
|
146
|
+
```
|
|
147
|
+
|
|
148
|
+
For consolidated responses (Case B):
|
|
149
|
+
|
|
150
|
+
```
|
|
151
|
+
## Synthesized from <N> memories
|
|
152
|
+
|
|
153
|
+
<consolidated narrative>
|
|
154
|
+
|
|
155
|
+
### Contributing Memories
|
|
156
|
+
1. **<title>** (.brain/<path>) — score: <score>, confidence: <confidence>
|
|
157
|
+
2. **<title>** (.brain/<path>) — score: <score>, confidence: <confidence>
|
|
158
|
+
...
|
|
159
|
+
|
|
160
|
+
---
|
|
161
|
+
*<N> memories reinforced, <M> association links strengthened*
|
|
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?*
|
|
176
|
+
```
|