brain-memory 0.1.0-beta.9 → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (82) hide show
  1. package/CHANGELOG.md +632 -0
  2. package/README.md +390 -84
  3. package/SECURITY.md +100 -0
  4. package/assets/brand/README.md +28 -0
  5. package/assets/brand/icon-dark.svg +19 -0
  6. package/assets/brand/icon-light.svg +20 -0
  7. package/assets/brand/linkedin_cover.png +0 -0
  8. package/assets/brand/linkedin_cover_light.png +0 -0
  9. package/assets/brand/mark-dark.svg +19 -0
  10. package/assets/brand/mark-light.svg +20 -0
  11. package/assets/brand/png/icon-dark-1024.png +0 -0
  12. package/assets/brand/png/icon-dark-128.png +0 -0
  13. package/assets/brand/png/icon-dark-256.png +0 -0
  14. package/assets/brand/png/icon-dark-512.png +0 -0
  15. package/assets/brand/png/icon-dark-64.png +0 -0
  16. package/assets/brand/png/icon-light-1024.png +0 -0
  17. package/assets/brand/png/icon-light-128.png +0 -0
  18. package/assets/brand/png/icon-light-256.png +0 -0
  19. package/assets/brand/png/icon-light-512.png +0 -0
  20. package/assets/brand/png/icon-light-64.png +0 -0
  21. package/assets/brand/png/mark-dark-1024.png +0 -0
  22. package/assets/brand/png/mark-light-1024.png +0 -0
  23. package/assets/icon.png +0 -0
  24. package/assets/icon.svg +19 -0
  25. package/bin/audit.js +93 -0
  26. package/bin/brain.js +132 -0
  27. package/bin/cloud-sync.js +150 -0
  28. package/bin/forget.js +172 -0
  29. package/bin/import.js +132 -0
  30. package/bin/install.js +63 -31
  31. package/bin/memorize.js +670 -0
  32. package/bin/pin.js +44 -0
  33. package/bin/recall.js +319 -0
  34. package/bin/reinforce.js +191 -0
  35. package/bin/restore.js +122 -0
  36. package/bin/session-start.js +352 -0
  37. package/bin/skill.js +67 -0
  38. package/bin/unpin.js +38 -0
  39. package/bin/verify.js +186 -0
  40. package/commands/brain/forget.md +243 -13
  41. package/commands/brain/import.md +125 -0
  42. package/commands/brain/memorize.md +108 -130
  43. package/commands/brain/pin.md +79 -0
  44. package/commands/brain/remember.md +59 -100
  45. package/commands/brain/skills.md +60 -0
  46. package/commands/brain/sleep.md +93 -6
  47. package/commands/brain/status.md +15 -6
  48. package/commands/brain/sync.md +181 -17
  49. package/commands/brain/verify.md +63 -0
  50. package/integrations/README.md +29 -0
  51. package/integrations/agentskills/brain-memory/SKILL.md +115 -0
  52. package/integrations/agentskills/brain-memory/scripts/session-start.mjs +34 -0
  53. package/package.json +19 -7
  54. package/prompts/antigravity.md +222 -0
  55. package/prompts/claude.md +128 -40
  56. package/prompts/copilot.md +224 -0
  57. package/prompts/kilo.md +223 -0
  58. package/prompts/openai.md +133 -45
  59. package/prompts/opencode.md +221 -0
  60. package/src/anomaly.js +260 -0
  61. package/src/audit.js +71 -0
  62. package/src/cloud-sync.js +672 -0
  63. package/src/content-lint.js +118 -0
  64. package/src/export-import.js +45 -7
  65. package/src/git-sync.js +170 -11
  66. package/src/harvest.js +562 -0
  67. package/src/index-manager.js +250 -11
  68. package/src/installer.js +250 -29
  69. package/src/pinning.js +146 -0
  70. package/src/provenance.js +79 -0
  71. package/src/quarantine.js +111 -0
  72. package/src/receipt.js +87 -0
  73. package/src/scorer.js +137 -12
  74. package/src/skills.js +208 -0
  75. package/src/temporal.js +228 -0
  76. package/src/tfidf.js +520 -0
  77. package/commands/brain/consolidate.md +0 -153
  78. package/commands/brain/explore.md +0 -79
  79. package/commands/brain/init.md +0 -149
  80. package/commands/brain/review.md +0 -130
  81. package/commands/brain/sunshine.md +0 -337
  82. package/prompts/gemini.md +0 -134
package/prompts/gemini.md DELETED
@@ -1,134 +0,0 @@
1
- # Brain Memory System
2
-
3
- This project uses the **Brain Memory** plugin — a hierarchical, file-system-based memory system that mimics human cognition with neuroscience-inspired mechanisms including associative networks, spreading activation, context-dependent recall, spaced reinforcement, and cognitive memory types.
4
-
5
- ## Memory Location
6
-
7
- All memories are stored in a single global `~/.brain/` directory in the user's home folder, shared across all projects and all supported AI agents. The directory uses a deep nested structure organized by life domains (professional, personal, social, family) with on-demand subcategories.
8
-
9
- ## How It Works
10
-
11
- ### Memory Format
12
- Each memory is a Markdown file with YAML frontmatter containing: `id`, `type`, `cognitive_type` (episodic/semantic/procedural), `created`, `last_accessed`, `access_count`, `recall_history`, `strength` (0.0-1.0), `decay_rate` (per day), `salience` (0.0-1.0), `confidence` (0.0-1.0), `tags`, `related` memory IDs, `source`, and `encoding_context`.
13
-
14
- ### Strength & Decay Model
15
- - Memories have a base `strength` set at creation based on their impact/type/cognitive type
16
- - Strength decays over time: `effective = strength * (decay_rate ^ days_since_access)`
17
- - Recalled memories get **stronger** via spaced reinforcement — the longer since last recall, the bigger the boost
18
- - Memories become progressively more forgetting-resistant with each recall (decay_rate improves)
19
- - Weak memories can be consolidated into stronger combined memories
20
- - During sleep, global synaptic homeostasis prevents strength inflation
21
-
22
- ### Cognitive Types
23
- - **Episodic** — Event-specific memories. Higher initial strength, faster decay. The details fade but lessons persist.
24
- - **Semantic** — Abstracted knowledge. Default decay. Stable long-term storage.
25
- - **Procedural** — Skills and workflows. Lower initial strength but extremely slow decay once established.
26
-
27
- ### Memory Types & Default Strengths
28
- | Type | Strength | Decay/day | Description |
29
- |------|----------|-----------|-------------|
30
- | decision | 0.85 | 0.995 | Choices made and rationale |
31
- | insight | 0.90 | 0.997 | Deep realizations, patterns |
32
- | goal | 0.80 | 0.993 | Objectives and aspirations |
33
- | experience | 0.75 | 0.985 | Notable events or processes |
34
- | learning | 0.70 | 0.990 | New knowledge acquired |
35
- | relationship | 0.70 | 0.997 | Connections between entities |
36
- | preference | 0.60 | 0.998 | User preferences and style |
37
- | observation | 0.40 | 0.950 | Casual facts or notices |
38
-
39
- ### Associative Network
40
- Memories are connected via weighted edges in `~/.brain/associations.json`. When you recall memory A, **spreading activation** automatically surfaces related memories B and C — just like how the brain activates linked neurons. Links are strengthened through **Hebbian learning**: memories recalled together become more tightly connected over time.
41
-
42
- ### Context-Dependent Recall
43
- Memories store their encoding context (project, topics, task type). During recall, memories encoded in a similar context to the current session are scored higher — matching how human memory works better when recall context matches encoding context.
44
-
45
- ### Salience & Confidence
46
- - **Salience** (0.0-1.0): Emotional/motivational significance. High-salience memories (>= 0.7) are never auto-pruned.
47
- - **Confidence** (0.0-1.0): Epistemic certainty. Low-confidence memories are flagged during recall.
48
-
49
- ## Available Commands
50
-
51
- Commands are available via `/brain:` prefix:
52
- - `/brain:init` — Initialize the brain structure
53
- - `/brain:memorize [topic]` — Store memories from current context
54
- - `/brain:remember [query]` — Recall relevant memories with spreading activation and context matching
55
- - `/brain:review [scope]` — Spaced repetition review session for due memories
56
- - `/brain:explore [category]` — Browse the brain hierarchy
57
- - `/brain:consolidate [scope]` — Merge related weak memories into stronger ones
58
- - `/brain:forget [target]` — Decay or archive memories
59
- - `/brain:sunshine [target]` — Deep forensic erasure — trace and remove all references to a memory
60
- - `/brain:sleep [scope]` — Full maintenance cycle: replay, synaptic homeostasis, knowledge propagation, semantic crystallization, reorganize, consolidate, prune, REM dreaming, and expertise detection
61
- - `/brain:status` — Dashboard with brain health overview
62
- - `/brain:sync [subcommand]` — Sync memories via Git remote or export/import for portability
63
-
64
- ## Session Start Behavior
65
-
66
- **IMPORTANT: Perform these steps automatically at the beginning of every session.**
67
-
68
- If `~/.brain/index.json` exists:
69
-
70
- 1. **Read the index** to understand the current brain state (memory count, categories)
71
- 2. **Identify high-value memories** — the top 3-5 memories by effective strength that are relevant to the current project context
72
- 3. **Silently internalize** these memories so you can reference them naturally during the session — do NOT dump memory contents
73
- 4. **Check review queue** — read `~/.brain/review-queue.json` if it exists for memories due for review
74
- 5. **Capture session context** — note the current project name, inferred topics, and task type for context-dependent recall
75
- 6. **Output a brief status** (1-3 lines):
76
-
77
- If memories are due for review:
78
- ```
79
- 🧠 Brain active — <N> memories loaded (<M> in current project context)
80
- 📋 <X> memories due for review — run /brain:review
81
- ```
82
-
83
- Otherwise:
84
- ```
85
- 🧠 Brain active — <N> memories loaded (<M> in current project context)
86
- ```
87
-
88
- If any frequently-used memories (access_count >= 3) have confidence < 0.5:
89
- ```
90
- ⚠️ <N> frequently-used memories have low confidence — consider verifying
91
- ```
92
-
93
- **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.
94
-
95
- ## Session End Behavior
96
-
97
- When a session is ending or the user signals they are done, evaluate whether the session contained:
98
- - **Decisions** — Architecture choices, technology selections, trade-off resolutions
99
- - **Learnings** — New patterns, debugging insights, API discoveries
100
- - **Insights** — Realizations about the codebase, project, or process
101
- - **Experiences** — Significant events like incidents, deployments, milestones
102
- - **Goals** — New objectives discussed or planned
103
-
104
- If the session contained meaningful content in any of these categories, suggest:
105
- ```
106
- 💡 This session contained notable <type(s)>. Would you like to store them as brain memories?
107
- Run /brain:memorize to capture them before this context is lost.
108
- ```
109
-
110
- **Rules:**
111
- - Do NOT auto-memorize without user consent
112
- - Do NOT prompt for trivial sessions (quick fixes, typo corrections, simple questions)
113
- - Only suggest when there is genuinely valuable context worth preserving
114
- - Always save session context to `~/.brain/contexts.json` regardless (append a session summary, keep last 20 entries)
115
-
116
- ## When Recalling Memories
117
-
118
- When the user asks you to "remember" something, or when context from past sessions would be helpful:
119
- 1. Check `~/.brain/index.json` for relevant memories
120
- 2. Load `~/.brain/associations.json` for spreading activation
121
- 3. Score by v4 formula: `0.38*relevance + 0.18*decayed_strength + 0.08*recency + 0.14*spreading_bonus + 0.14*context_match + 0.08*salience`
122
- 4. Return strong individual matches or synthesize from multiple related memories
123
- 5. Apply spaced reinforcement (spacing-aware boost) and improve decay rate
124
- 6. Strengthen Hebbian links between co-retrieved memories
125
- 7. If no active matches, search the archive (`~/.brain/_archived/`)
126
-
127
- ## Portable Sync
128
-
129
- Brain memories can be synced across devices in two ways:
130
-
131
- 1. **Git remote** — Push/pull `~/.brain/` to any private Git repository (GitHub, GitLab, Codeberg, self-hosted). Run `/brain:sync setup <url>` to configure, then use `/brain:sync push` and `/brain:sync pull`.
132
- 2. **Export/Import** — Pack the entire `~/.brain/` into a single portable file for manual transfer. Run `/brain:sync export` and `/brain:sync import <path>`.
133
-
134
- Both methods support optional AES-256-GCM encryption. Sync is always manual — never automatic.