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.
- package/CHANGELOG.md +632 -0
- package/README.md +390 -84
- package/SECURITY.md +100 -0
- package/assets/brand/README.md +28 -0
- package/assets/brand/icon-dark.svg +19 -0
- package/assets/brand/icon-light.svg +20 -0
- package/assets/brand/linkedin_cover.png +0 -0
- package/assets/brand/linkedin_cover_light.png +0 -0
- package/assets/brand/mark-dark.svg +19 -0
- package/assets/brand/mark-light.svg +20 -0
- package/assets/brand/png/icon-dark-1024.png +0 -0
- package/assets/brand/png/icon-dark-128.png +0 -0
- package/assets/brand/png/icon-dark-256.png +0 -0
- package/assets/brand/png/icon-dark-512.png +0 -0
- package/assets/brand/png/icon-dark-64.png +0 -0
- package/assets/brand/png/icon-light-1024.png +0 -0
- package/assets/brand/png/icon-light-128.png +0 -0
- package/assets/brand/png/icon-light-256.png +0 -0
- package/assets/brand/png/icon-light-512.png +0 -0
- package/assets/brand/png/icon-light-64.png +0 -0
- package/assets/brand/png/mark-dark-1024.png +0 -0
- package/assets/brand/png/mark-light-1024.png +0 -0
- package/assets/icon.png +0 -0
- package/assets/icon.svg +19 -0
- package/bin/audit.js +93 -0
- package/bin/brain.js +132 -0
- package/bin/cloud-sync.js +150 -0
- package/bin/forget.js +172 -0
- package/bin/import.js +132 -0
- package/bin/install.js +63 -31
- package/bin/memorize.js +670 -0
- package/bin/pin.js +44 -0
- package/bin/recall.js +319 -0
- package/bin/reinforce.js +191 -0
- package/bin/restore.js +122 -0
- package/bin/session-start.js +352 -0
- package/bin/skill.js +67 -0
- package/bin/unpin.js +38 -0
- package/bin/verify.js +186 -0
- package/commands/brain/forget.md +243 -13
- package/commands/brain/import.md +125 -0
- package/commands/brain/memorize.md +108 -130
- package/commands/brain/pin.md +79 -0
- package/commands/brain/remember.md +59 -100
- package/commands/brain/skills.md +60 -0
- package/commands/brain/sleep.md +93 -6
- package/commands/brain/status.md +15 -6
- package/commands/brain/sync.md +181 -17
- package/commands/brain/verify.md +63 -0
- package/integrations/README.md +29 -0
- package/integrations/agentskills/brain-memory/SKILL.md +115 -0
- package/integrations/agentskills/brain-memory/scripts/session-start.mjs +34 -0
- package/package.json +19 -7
- package/prompts/antigravity.md +222 -0
- package/prompts/claude.md +128 -40
- package/prompts/copilot.md +224 -0
- package/prompts/kilo.md +223 -0
- package/prompts/openai.md +133 -45
- package/prompts/opencode.md +221 -0
- package/src/anomaly.js +260 -0
- package/src/audit.js +71 -0
- package/src/cloud-sync.js +672 -0
- package/src/content-lint.js +118 -0
- package/src/export-import.js +45 -7
- package/src/git-sync.js +170 -11
- package/src/harvest.js +562 -0
- package/src/index-manager.js +250 -11
- package/src/installer.js +250 -29
- package/src/pinning.js +146 -0
- package/src/provenance.js +79 -0
- package/src/quarantine.js +111 -0
- package/src/receipt.js +87 -0
- package/src/scorer.js +137 -12
- package/src/skills.js +208 -0
- package/src/temporal.js +228 -0
- package/src/tfidf.js +520 -0
- package/commands/brain/consolidate.md +0 -153
- package/commands/brain/explore.md +0 -79
- package/commands/brain/init.md +0 -149
- package/commands/brain/review.md +0 -130
- package/commands/brain/sunshine.md +0 -337
- package/prompts/gemini.md +0 -134
package/src/temporal.js
ADDED
|
@@ -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
|
+
};
|