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
@@ -0,0 +1,228 @@
1
+ /**
2
+ * Brain Memory — Bitemporal Validity (valid time vs record time)
3
+ *
4
+ * Two independent time axes per memory, the distinction the flat model can't
5
+ * make:
6
+ *
7
+ * record time — WHEN THE BRAIN LEARNED IT. `created` (already on every
8
+ * memory). Immutable; the audit axis.
9
+ * valid time — WHEN THE FACT WAS TRUE. `valid_from` / `valid_until`.
10
+ * Optional, half-open [from, until): a memory is current at
11
+ * instant t when from <= t < until. Either bound may be absent
12
+ * (unbounded in that direction) — absent is the default, and a
13
+ * memory with neither is simply "true as far as we know".
14
+ *
15
+ * Why it matters: "we deploy to Fly.io" recorded in June and "we deploy to
16
+ * Render" recorded in August are not a contradiction to resolve — they are one
17
+ * fact with a boundary. Without valid time, recall can only rank them; with it,
18
+ * recall can answer "what was true in July" exactly, and say when a fact
19
+ * stopped being true rather than quietly serving a stale one.
20
+ *
21
+ * Relationship to supersession: `supersedes`/`superseded_by` is the *pointer*
22
+ * (this fact replaced that one); valid time is the *interval* it implies. When
23
+ * B supersedes A, A's `valid_until` is stamped with B's start — see
24
+ * applySupersession — so the existing corpus gains real validity windows
25
+ * without re-authoring a single memory. A stamp made this way is marked
26
+ * `valid_until_auto` so it can be withdrawn if the successor is later archived,
27
+ * while an interval the author set by hand is never touched.
28
+ *
29
+ * Recall (src/scorer.js) uses this three ways:
30
+ * - default: expired memories are demoted, not dropped ("that was
31
+ * true until August" stays answerable)
32
+ * - --as-of T: valid-time travel — only facts whose window contains T
33
+ * - --as-known-of T: record-time travel — only memories created by T
34
+ * Passing both reconstructs exactly what the brain believed, and when.
35
+ */
36
+
37
+ const { setFrontmatterFields } = require('./pinning');
38
+
39
+ // Demotion applied to a memory whose validity window has elapsed. Matched to
40
+ // SUPERSEDED_PENALTY in src/scorer.js: both mean "no longer current", and a
41
+ // memory carrying both signals must not be demoted twice (the scorer takes the
42
+ // strongest single penalty, never the product).
43
+ const EXPIRED_PENALTY = 0.25;
44
+
45
+ /**
46
+ * Parse a timestamp into epoch ms, tolerating the shapes that reach us from
47
+ * frontmatter, JSON payloads, and CLI flags (ISO instants, plain YYYY-MM-DD).
48
+ *
49
+ * @param {string|number|Date} [value]
50
+ * @returns {number|null} Epoch ms, or null when absent/unparseable
51
+ */
52
+ function parseInstant(value) {
53
+ if (value == null || value === '') return null;
54
+ const t = value instanceof Date ? value.getTime() : new Date(value).getTime();
55
+ return Number.isFinite(t) ? t : null;
56
+ }
57
+
58
+ /**
59
+ * The validity window of a memory, as epoch ms bounds (null = unbounded).
60
+ *
61
+ * @param {Object} mem - Memory or index entry
62
+ * @returns {{from: number|null, until: number|null}}
63
+ */
64
+ function validityOf(mem) {
65
+ return {
66
+ from: parseInstant(mem && mem.valid_from),
67
+ until: parseInstant(mem && mem.valid_until),
68
+ };
69
+ }
70
+
71
+ /**
72
+ * Where an instant falls relative to a memory's validity window.
73
+ *
74
+ * Half-open [from, until): a fact that stopped being true at 09:00 is not true
75
+ * at 09:00. Memories with no window are always 'current'.
76
+ *
77
+ * @param {Object} mem - Memory or index entry
78
+ * @param {number} at - Epoch ms
79
+ * @returns {'future'|'current'|'expired'}
80
+ */
81
+ function temporalState(mem, at) {
82
+ const { from, until } = validityOf(mem);
83
+ if (from != null && at < from) return 'future';
84
+ if (until != null && at >= until) return 'expired';
85
+ return 'current';
86
+ }
87
+
88
+ /** True when the memory's validity window contains `at`. */
89
+ function isValidAt(mem, at) {
90
+ return temporalState(mem, at) === 'current';
91
+ }
92
+
93
+ /**
94
+ * Validate an author-supplied validity window.
95
+ *
96
+ * An inverted or unparseable interval is rejected at write time rather than
97
+ * silently stored: a bad window would make the memory invisible to every
98
+ * as-of query, which is far harder to notice than a failed write.
99
+ *
100
+ * @param {Object} mem - Raw memory payload
101
+ * @returns {{error: string}|null}
102
+ */
103
+ function validateValidity(mem) {
104
+ for (const field of ['valid_from', 'valid_until']) {
105
+ if (mem[field] == null || mem[field] === '') continue;
106
+ if (parseInstant(mem[field]) == null) {
107
+ return { error: `Invalid ${field}: ${JSON.stringify(mem[field])} — expected an ISO date or timestamp` };
108
+ }
109
+ }
110
+ const { from, until } = validityOf(mem);
111
+ if (from != null && until != null && until <= from) {
112
+ return { error: `valid_until (${mem.valid_until}) must be after valid_from (${mem.valid_from})` };
113
+ }
114
+ return null;
115
+ }
116
+
117
+ /**
118
+ * The instant at which a successor takes over from what it replaces — its own
119
+ * `valid_from` when the author gave one, else when it was recorded.
120
+ *
121
+ * @param {Object} successor - The superseding memory (needs valid_from/created)
122
+ * @returns {string|null} ISO instant, or null when neither is parseable
123
+ */
124
+ function supersessionInstant(successor) {
125
+ for (const candidate of [successor && successor.valid_from, successor && successor.created]) {
126
+ const t = parseInstant(candidate);
127
+ if (t != null) return new Date(t).toISOString();
128
+ }
129
+ return null;
130
+ }
131
+
132
+ /**
133
+ * Stamp supersession onto the memories a successor replaces: the
134
+ * `superseded_by` back-pointer, plus the valid-time boundary it implies.
135
+ *
136
+ * `valid_until` is only stamped when the target has no window of its own — an
137
+ * author-set interval always wins — and an automatic stamp is marked
138
+ * `valid_until_auto` so clearSupersessionsBy can withdraw it later without
139
+ * touching hand-authored data.
140
+ *
141
+ * Mutates `index` in place and mirrors into frontmatter; the caller writes the
142
+ * index. Unknown target ids are skipped silently (they may have been forgotten).
143
+ *
144
+ * @param {string} brainDir
145
+ * @param {Object} index - Live index (mutated)
146
+ * @param {string} successorId
147
+ * @param {string[]} targetIds
148
+ * @param {Object} [opts] - { validUntil: ISO instant the successor starts at }
149
+ * @returns {Array<{id: string, title: string}>} Targets actually stamped
150
+ */
151
+ function applySupersession(brainDir, index, successorId, targetIds, opts = {}) {
152
+ const { validUntil = null } = opts;
153
+ const applied = [];
154
+
155
+ for (const targetId of targetIds || []) {
156
+ const target = index.memories[targetId];
157
+ if (!target) continue;
158
+
159
+ target.superseded_by = successorId;
160
+ const fields = { superseded_by: successorId };
161
+
162
+ // Valid-time edge: the predecessor stopped being true when its successor
163
+ // started being true. Never overwrite an explicit window.
164
+ if (validUntil && !target.valid_until) {
165
+ target.valid_until = validUntil;
166
+ target.valid_until_auto = true;
167
+ fields.valid_until = validUntil;
168
+ fields.valid_until_auto = true;
169
+ }
170
+
171
+ setFrontmatterFields(brainDir, target.path, fields);
172
+ applied.push({ id: targetId, title: target.title });
173
+ }
174
+
175
+ return applied;
176
+ }
177
+
178
+ /**
179
+ * Withdraw every supersession a memory imposed — used when that memory is
180
+ * archived or rejected.
181
+ *
182
+ * Without this the victims stay demoted forever (0.25x at recall) behind a
183
+ * back-pointer to an id that no longer exists, so rejecting a poisoned write
184
+ * would leave its damage in place. Only auto-stamped validity is withdrawn;
185
+ * an interval the author set by hand survives.
186
+ *
187
+ * Mutates `index` in place and mirrors into frontmatter; the caller writes the
188
+ * index.
189
+ *
190
+ * @param {string} brainDir
191
+ * @param {Object} index - Live index (mutated)
192
+ * @param {string} successorId - The memory going away
193
+ * @returns {string[]} Ids of memories released
194
+ */
195
+ function clearSupersessionsBy(brainDir, index, successorId) {
196
+ const cleared = [];
197
+
198
+ for (const [id, entry] of Object.entries((index && index.memories) || {})) {
199
+ if (entry.superseded_by !== successorId) continue;
200
+
201
+ delete entry.superseded_by;
202
+ const fields = { superseded_by: null };
203
+
204
+ if (entry.valid_until_auto) {
205
+ delete entry.valid_until;
206
+ delete entry.valid_until_auto;
207
+ fields.valid_until = null;
208
+ fields.valid_until_auto = null;
209
+ }
210
+
211
+ if (entry.path) setFrontmatterFields(brainDir, entry.path, fields);
212
+ cleared.push(id);
213
+ }
214
+
215
+ return cleared;
216
+ }
217
+
218
+ module.exports = {
219
+ EXPIRED_PENALTY,
220
+ parseInstant,
221
+ validityOf,
222
+ temporalState,
223
+ isValidAt,
224
+ validateValidity,
225
+ supersessionInstant,
226
+ applySupersession,
227
+ clearSupersessionsBy,
228
+ };