brain-memory 0.1.0-beta.9 → 0.1.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 +555 -0
- package/README.md +385 -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 +163 -0
- package/bin/import.js +132 -0
- package/bin/install.js +63 -31
- package/bin/memorize.js +637 -0
- package/bin/pin.js +44 -0
- package/bin/recall.js +287 -0
- package/bin/reinforce.js +191 -0
- package/bin/restore.js +122 -0
- package/bin/session-start.js +337 -0
- package/bin/skill.js +67 -0
- package/bin/unpin.js +38 -0
- package/bin/verify.js +154 -0
- package/commands/brain/forget.md +243 -13
- package/commands/brain/import.md +125 -0
- package/commands/brain/memorize.md +95 -137
- package/commands/brain/pin.md +79 -0
- package/commands/brain/remember.md +53 -103
- 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 +57 -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 +201 -0
- package/prompts/claude.md +107 -40
- package/prompts/copilot.md +203 -0
- package/prompts/kilo.md +202 -0
- package/prompts/openai.md +112 -45
- package/prompts/opencode.md +200 -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 +81 -0
- package/src/scorer.js +69 -12
- package/src/skills.js +208 -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/bin/memorize.js
ADDED
|
@@ -0,0 +1,637 @@
|
|
|
1
|
+
#!/usr/bin/env node
|
|
2
|
+
|
|
3
|
+
/**
|
|
4
|
+
* brain memorize — Store memories from AI agent input
|
|
5
|
+
*
|
|
6
|
+
* Accepts a JSON payload via stdin with memory definitions.
|
|
7
|
+
* Handles all plumbing: ID generation, directory creation, file writing,
|
|
8
|
+
* index updates, association edges, search index, and optional sync.
|
|
9
|
+
*
|
|
10
|
+
* Usage:
|
|
11
|
+
* brain memorize [--sync] <<'EOF'
|
|
12
|
+
* { "memories": [{ "title": "...", "type": "learning", ... }] }
|
|
13
|
+
* EOF
|
|
14
|
+
*
|
|
15
|
+
* The AI agent decides WHAT to remember. This CLI handles HOW to write it.
|
|
16
|
+
*/
|
|
17
|
+
|
|
18
|
+
const fs = require('fs');
|
|
19
|
+
const path = require('path');
|
|
20
|
+
const { execSync, execFileSync } = require('child_process');
|
|
21
|
+
const {
|
|
22
|
+
getBrainDir,
|
|
23
|
+
readIndex,
|
|
24
|
+
writeIndex,
|
|
25
|
+
addMemory,
|
|
26
|
+
generateId,
|
|
27
|
+
readMeta,
|
|
28
|
+
writeMeta,
|
|
29
|
+
readAssociations,
|
|
30
|
+
writeAssociations,
|
|
31
|
+
reinforceEdge,
|
|
32
|
+
readPinned,
|
|
33
|
+
writePinned,
|
|
34
|
+
readConfig,
|
|
35
|
+
atomicWriteSync,
|
|
36
|
+
validateBrainPath,
|
|
37
|
+
} = require('../src/index-manager');
|
|
38
|
+
const { addDocument, createSearchIndex, readSearchIndex, writeSearchIndex } = require('../src/tfidf');
|
|
39
|
+
const { appendAudit } = require('../src/audit');
|
|
40
|
+
const { lintMemoryContent } = require('../src/content-lint');
|
|
41
|
+
const { quarantineDecision } = require('../src/quarantine');
|
|
42
|
+
const { setFrontmatterFields } = require('../src/pinning');
|
|
43
|
+
|
|
44
|
+
// Best-effort detection of the host AI agent, recorded on each memory's
|
|
45
|
+
// encoding_context for "where your brain is used" analytics. An explicit
|
|
46
|
+
// BRAIN_AGENT env var always wins (a per-agent install can set it); otherwise we
|
|
47
|
+
// sniff known markers. Unrecognized hosts record "unknown" (the cloud tolerates
|
|
48
|
+
// it). The non-Claude markers are best-effort.
|
|
49
|
+
function detectAgent() {
|
|
50
|
+
const e = process.env;
|
|
51
|
+
if (e.BRAIN_AGENT) return e.BRAIN_AGENT;
|
|
52
|
+
if (e.CLAUDECODE || e.CLAUDE_CODE_ENTRYPOINT) return 'claude-code';
|
|
53
|
+
if (e.GEMINI_CLI || e.GEMINI_CLI_VERSION) return 'gemini-cli';
|
|
54
|
+
if (e.CODEX_HOME || e.CODEX_SANDBOX) return 'codex';
|
|
55
|
+
if (e.OPENCODE || e.OPENCODE_BIN) return 'opencode';
|
|
56
|
+
return 'unknown';
|
|
57
|
+
}
|
|
58
|
+
const HOST_AGENT = detectAgent();
|
|
59
|
+
|
|
60
|
+
// --- Type defaults ---
|
|
61
|
+
|
|
62
|
+
const TYPE_DEFAULTS = {
|
|
63
|
+
decision: { strength: 0.85, decay_rate: 0.995 },
|
|
64
|
+
insight: { strength: 0.90, decay_rate: 0.997 },
|
|
65
|
+
goal: { strength: 0.80, decay_rate: 0.993 },
|
|
66
|
+
experience: { strength: 0.75, decay_rate: 0.985 },
|
|
67
|
+
learning: { strength: 0.70, decay_rate: 0.990 },
|
|
68
|
+
relationship: { strength: 0.70, decay_rate: 0.997 },
|
|
69
|
+
preference: { strength: 0.60, decay_rate: 0.998 },
|
|
70
|
+
observation: { strength: 0.40, decay_rate: 0.950 },
|
|
71
|
+
};
|
|
72
|
+
|
|
73
|
+
const COGNITIVE_ADJUSTMENTS = {
|
|
74
|
+
episodic: { strength_delta: +0.10, decay_multiplier: 0.995 },
|
|
75
|
+
semantic: { strength_delta: 0, decay_multiplier: 1.0 },
|
|
76
|
+
procedural: { strength_delta: -0.10, decay_multiplier: 1.003 },
|
|
77
|
+
};
|
|
78
|
+
|
|
79
|
+
// --- Provenance (OWASP ASI06: memory poisoning) ---
|
|
80
|
+
//
|
|
81
|
+
// Where a memory came from decides how much it is allowed to entrench itself.
|
|
82
|
+
// The policy table lives in src/provenance.js (shared with the recall-side
|
|
83
|
+
// trust weighting in src/scorer.js). The pin/stable restriction is the part
|
|
84
|
+
// that holds regardless of caller honesty: entrenchment is simply not
|
|
85
|
+
// reachable from this path without an explicit user origin.
|
|
86
|
+
const { ORIGIN_POLICY, DEFAULT_ORIGIN } = require('../src/provenance');
|
|
87
|
+
|
|
88
|
+
// --- Args ---
|
|
89
|
+
|
|
90
|
+
function parseArgs(argv) {
|
|
91
|
+
const args = { sync: false };
|
|
92
|
+
for (const arg of argv) {
|
|
93
|
+
if (arg === '--sync') args.sync = true;
|
|
94
|
+
}
|
|
95
|
+
return args;
|
|
96
|
+
}
|
|
97
|
+
|
|
98
|
+
// --- Helpers ---
|
|
99
|
+
|
|
100
|
+
/**
|
|
101
|
+
* Resolve a memory's origin and clamp its trust-bearing fields to what that
|
|
102
|
+
* origin is permitted to claim.
|
|
103
|
+
*
|
|
104
|
+
* Returns `{ origin, policy, mem, clamps }` where `mem` is a sanitized copy and
|
|
105
|
+
* `clamps` lists every explicit over-ask the policy lowered — surfaced in the
|
|
106
|
+
* CLI output so a downgrade is never silent. Returns `{ error }` for requests
|
|
107
|
+
* that have no benign reading.
|
|
108
|
+
*/
|
|
109
|
+
function applyOriginPolicy(mem) {
|
|
110
|
+
const origin = mem.origin || DEFAULT_ORIGIN;
|
|
111
|
+
const policy = ORIGIN_POLICY[origin];
|
|
112
|
+
if (!policy) {
|
|
113
|
+
return { error: `Unknown origin "${origin}" (expected one of: ${Object.keys(ORIGIN_POLICY).join(', ')})` };
|
|
114
|
+
}
|
|
115
|
+
|
|
116
|
+
// Entrenchment — loading into every session, or exemption from decay — is a
|
|
117
|
+
// capability, not a magnitude. Tool output and inbound email have no benign
|
|
118
|
+
// reason to request it, so this is refused loudly rather than quietly capped.
|
|
119
|
+
if (!policy.allow_entrench && (mem.pinned || mem.stable)) {
|
|
120
|
+
const asked = [mem.pinned && 'pinned', mem.stable && 'stable'].filter(Boolean).join(' + ');
|
|
121
|
+
return {
|
|
122
|
+
error: `Origin "${origin}" may not set ${asked}. Entrenching a memory requires origin ` +
|
|
123
|
+
`"user" — or pin it deliberately afterwards with \`brain pin <id>\`.`,
|
|
124
|
+
};
|
|
125
|
+
}
|
|
126
|
+
|
|
127
|
+
const clamps = [];
|
|
128
|
+
const clamp = (field, requested, fallback, max) => {
|
|
129
|
+
const value = requested ?? fallback;
|
|
130
|
+
if (value <= max) return value;
|
|
131
|
+
// Only report a downgrade the caller actually asked for. A lowered default
|
|
132
|
+
// is the policy working as designed, not a rejected claim.
|
|
133
|
+
if (requested != null) clamps.push({ field, requested, allowed: max, origin });
|
|
134
|
+
return max;
|
|
135
|
+
};
|
|
136
|
+
|
|
137
|
+
return {
|
|
138
|
+
origin,
|
|
139
|
+
policy,
|
|
140
|
+
clamps,
|
|
141
|
+
mem: {
|
|
142
|
+
...mem,
|
|
143
|
+
salience: clamp('salience', mem.salience, 0.5, policy.max_salience),
|
|
144
|
+
confidence: clamp('confidence', mem.confidence, 0.7, policy.max_confidence),
|
|
145
|
+
// A non-user origin may lower a memory's base strength but never raise it.
|
|
146
|
+
strength_adjustment: clamp(
|
|
147
|
+
'strength_adjustment', mem.strength_adjustment, 0,
|
|
148
|
+
policy.allow_entrench ? Infinity : 0
|
|
149
|
+
),
|
|
150
|
+
},
|
|
151
|
+
};
|
|
152
|
+
}
|
|
153
|
+
|
|
154
|
+
function computeStrengthAndDecay(type, cognitiveType, strengthAdjustment = 0, originDecayMultiplier = 1.0) {
|
|
155
|
+
const typeDefaults = TYPE_DEFAULTS[type] || TYPE_DEFAULTS.observation;
|
|
156
|
+
const cogAdj = COGNITIVE_ADJUSTMENTS[cognitiveType] || COGNITIVE_ADJUSTMENTS.semantic;
|
|
157
|
+
|
|
158
|
+
const strength = Math.max(0, Math.min(1.0,
|
|
159
|
+
typeDefaults.strength + cogAdj.strength_delta + strengthAdjustment
|
|
160
|
+
));
|
|
161
|
+
// Cap strictly below 1.0. Procedural memories are meant to decay *slowly*, but
|
|
162
|
+
// a multiplier that pushed decay_rate >= 1.0 would make effective strength GROW
|
|
163
|
+
// over time (strength * decay_rate^days) — inverted decay. 0.9999/day is
|
|
164
|
+
// "extremely slow" (a memory loses ~3% of its strength per year) without ever
|
|
165
|
+
// inverting.
|
|
166
|
+
// The origin multiplier rides on top: memory sourced from untrusted content
|
|
167
|
+
// fades faster, so a planted fact loses to a genuine one over time even if
|
|
168
|
+
// nothing ever detects it as an attack.
|
|
169
|
+
const decay_rate = Math.min(
|
|
170
|
+
0.9999,
|
|
171
|
+
typeDefaults.decay_rate * cogAdj.decay_multiplier * originDecayMultiplier
|
|
172
|
+
);
|
|
173
|
+
|
|
174
|
+
return { strength: Math.round(strength * 100) / 100, decay_rate };
|
|
175
|
+
}
|
|
176
|
+
|
|
177
|
+
function buildMemoryFileContent(mem, id, now, origin, originDecayMultiplier, quarantine) {
|
|
178
|
+
const { strength, decay_rate } = computeStrengthAndDecay(
|
|
179
|
+
mem.type, mem.cognitive_type, mem.strength_adjustment, originDecayMultiplier
|
|
180
|
+
);
|
|
181
|
+
|
|
182
|
+
const fmLines = [
|
|
183
|
+
'---',
|
|
184
|
+
`id: ${id}`,
|
|
185
|
+
`type: ${mem.type}`,
|
|
186
|
+
`cognitive_type: ${mem.cognitive_type || 'semantic'}`,
|
|
187
|
+
`created: "${now}"`,
|
|
188
|
+
`last_accessed: "${now}"`,
|
|
189
|
+
`access_count: 0`,
|
|
190
|
+
`recall_history: []`,
|
|
191
|
+
`strength: ${strength}`,
|
|
192
|
+
`decay_rate: ${decay_rate}`,
|
|
193
|
+
`salience: ${mem.salience ?? 0.5}`,
|
|
194
|
+
`confidence: ${mem.confidence ?? 0.7}`,
|
|
195
|
+
];
|
|
196
|
+
// CoALA Phase 1: pinned (always-loaded) and stable (decay-exempt) are emitted
|
|
197
|
+
// only when set, so ordinary memories keep their existing frontmatter shape.
|
|
198
|
+
if (mem.pinned) {
|
|
199
|
+
fmLines.push('pinned: true');
|
|
200
|
+
fmLines.push(`pin_scope: "${mem.pin_scope || 'global'}"`);
|
|
201
|
+
fmLines.push(`pin_priority: ${mem.pin_priority || 0}`);
|
|
202
|
+
}
|
|
203
|
+
if (mem.stable) fmLines.push('stable: true');
|
|
204
|
+
// ASI06 quarantine: pending-verification state travels with the memory —
|
|
205
|
+
// same conditional-field pattern as pinned/stable, so it syncs and restores
|
|
206
|
+
// with the file and syncs via the index entry.
|
|
207
|
+
if (quarantine && quarantine.quarantined) {
|
|
208
|
+
fmLines.push('quarantined: true');
|
|
209
|
+
fmLines.push(`quarantine_reasons: [${quarantine.reasons.map((r) => `"${r}"`).join(', ')}]`);
|
|
210
|
+
fmLines.push(`quarantine_flagged: "${now}"`);
|
|
211
|
+
}
|
|
212
|
+
// Temporal invalidation: record which memories this one replaces. The
|
|
213
|
+
// reciprocal `superseded_by` is stamped on those targets in main().
|
|
214
|
+
if (mem.supersedes && mem.supersedes.length) {
|
|
215
|
+
fmLines.push(`supersedes: [${mem.supersedes.map((s) => `"${s}"`).join(', ')}]`);
|
|
216
|
+
}
|
|
217
|
+
fmLines.push(
|
|
218
|
+
`tags: [${(mem.tags || []).map(t => `"${t}"`).join(', ')}]`,
|
|
219
|
+
`related: [${(mem.related || []).map(r => `"${r}"`).join(', ')}]`,
|
|
220
|
+
`origin: "${origin}"`,
|
|
221
|
+
`source: "${mem.source || ''}"`,
|
|
222
|
+
`encoding_context:`,
|
|
223
|
+
` project: "${(mem.encoding_context && mem.encoding_context.project) || ''}"`,
|
|
224
|
+
` topics: [${((mem.encoding_context && mem.encoding_context.topics) || []).map(t => `"${t}"`).join(', ')}]`,
|
|
225
|
+
` task_type: "${(mem.encoding_context && mem.encoding_context.task_type) || ''}"`,
|
|
226
|
+
` agent: "${HOST_AGENT}"`,
|
|
227
|
+
'---',
|
|
228
|
+
'',
|
|
229
|
+
);
|
|
230
|
+
const frontmatter = fmLines.join('\n');
|
|
231
|
+
|
|
232
|
+
return { fileContent: frontmatter + mem.content + '\n', strength, decay_rate };
|
|
233
|
+
}
|
|
234
|
+
|
|
235
|
+
function buildIndexEntry(mem, id, strength, decayRate, now, origin, quarantine) {
|
|
236
|
+
const entry = {
|
|
237
|
+
title: mem.title,
|
|
238
|
+
path: mem.path,
|
|
239
|
+
type: mem.type,
|
|
240
|
+
cognitive_type: mem.cognitive_type || 'semantic',
|
|
241
|
+
created: now,
|
|
242
|
+
last_accessed: now,
|
|
243
|
+
access_count: 0,
|
|
244
|
+
strength,
|
|
245
|
+
decay_rate: decayRate,
|
|
246
|
+
// Provenance travels with the index entry so recall can weigh and flag it
|
|
247
|
+
// without having to open every memory file.
|
|
248
|
+
origin,
|
|
249
|
+
salience: mem.salience ?? 0.5,
|
|
250
|
+
confidence: mem.confidence ?? 0.7,
|
|
251
|
+
tags: mem.tags || [],
|
|
252
|
+
related: mem.related || [],
|
|
253
|
+
encoding_context: { ...(mem.encoding_context || {}), agent: HOST_AGENT },
|
|
254
|
+
// CoALA Phase 0: cheap chars/4 token estimate for working-memory budgeting.
|
|
255
|
+
token_estimate: Math.ceil((mem.content || '').length / 4),
|
|
256
|
+
};
|
|
257
|
+
// CoALA Phase 1: only set when present — keeps existing index entries lean.
|
|
258
|
+
if (mem.pinned) {
|
|
259
|
+
entry.pinned = true;
|
|
260
|
+
entry.pin_scope = mem.pin_scope || 'global';
|
|
261
|
+
entry.pin_priority = mem.pin_priority || 0;
|
|
262
|
+
}
|
|
263
|
+
if (mem.stable) entry.stable = true;
|
|
264
|
+
if (quarantine && quarantine.quarantined) {
|
|
265
|
+
entry.quarantined = true;
|
|
266
|
+
entry.quarantine_reasons = quarantine.reasons;
|
|
267
|
+
entry.quarantine_flagged = now;
|
|
268
|
+
}
|
|
269
|
+
if (mem.supersedes && mem.supersedes.length) entry.supersedes = mem.supersedes;
|
|
270
|
+
return entry;
|
|
271
|
+
}
|
|
272
|
+
|
|
273
|
+
function updateMetaFiles(brainDir, memPath) {
|
|
274
|
+
const parts = memPath.split('/');
|
|
275
|
+
// Walk up the directory chain, updating _meta.json at each level
|
|
276
|
+
for (let i = 1; i <= parts.length - 1; i++) {
|
|
277
|
+
const dirParts = parts.slice(0, i);
|
|
278
|
+
const categoryPath = dirParts.join('/');
|
|
279
|
+
const fullDir = path.join(brainDir, categoryPath);
|
|
280
|
+
|
|
281
|
+
if (!fs.existsSync(fullDir)) continue;
|
|
282
|
+
|
|
283
|
+
const metaPath = path.join(fullDir, '_meta.json');
|
|
284
|
+
let meta;
|
|
285
|
+
try {
|
|
286
|
+
meta = JSON.parse(fs.readFileSync(metaPath, 'utf-8'));
|
|
287
|
+
} catch {
|
|
288
|
+
meta = { description: categoryPath, memory_count: 0, subcategories: [] };
|
|
289
|
+
}
|
|
290
|
+
|
|
291
|
+
meta.memory_count = (meta.memory_count || 0) + 1;
|
|
292
|
+
|
|
293
|
+
// Add subcategory if this isn't the leaf directory
|
|
294
|
+
if (i < parts.length - 1) {
|
|
295
|
+
const subcat = parts[i];
|
|
296
|
+
if (!meta.subcategories) meta.subcategories = [];
|
|
297
|
+
if (!meta.subcategories.includes(subcat)) {
|
|
298
|
+
meta.subcategories.push(subcat);
|
|
299
|
+
}
|
|
300
|
+
}
|
|
301
|
+
|
|
302
|
+
atomicWriteSync(metaPath, JSON.stringify(meta, null, 2) + '\n');
|
|
303
|
+
}
|
|
304
|
+
}
|
|
305
|
+
|
|
306
|
+
function findTagOverlaps(index, newTags, newId, minOverlap = 2) {
|
|
307
|
+
const overlaps = [];
|
|
308
|
+
if (!newTags || newTags.length < minOverlap) return overlaps;
|
|
309
|
+
|
|
310
|
+
const newTagSet = new Set(newTags);
|
|
311
|
+
for (const [id, entry] of Object.entries(index.memories)) {
|
|
312
|
+
if (id === newId) continue;
|
|
313
|
+
const entryTags = entry.tags || [];
|
|
314
|
+
const shared = entryTags.filter(t => newTagSet.has(t));
|
|
315
|
+
if (shared.length >= minOverlap) {
|
|
316
|
+
overlaps.push(id);
|
|
317
|
+
}
|
|
318
|
+
}
|
|
319
|
+
return overlaps;
|
|
320
|
+
}
|
|
321
|
+
|
|
322
|
+
function trySync() {
|
|
323
|
+
const brainDir = getBrainDir();
|
|
324
|
+
|
|
325
|
+
// Try cloud sync first
|
|
326
|
+
const cloudConfig = path.join(brainDir, '.cloud', 'config.json');
|
|
327
|
+
if (fs.existsSync(cloudConfig)) {
|
|
328
|
+
try {
|
|
329
|
+
execSync('brain cloud push', { stdio: 'pipe', timeout: 30000 });
|
|
330
|
+
return { method: 'cloud', success: true };
|
|
331
|
+
} catch (err) {
|
|
332
|
+
return { method: 'cloud', success: false, error: err.message };
|
|
333
|
+
}
|
|
334
|
+
}
|
|
335
|
+
|
|
336
|
+
// Try git sync
|
|
337
|
+
const gitConfig = path.join(brainDir, '.sync', 'config.json');
|
|
338
|
+
if (fs.existsSync(gitConfig)) {
|
|
339
|
+
try {
|
|
340
|
+
// push() is async; run it in a child so this CLI can stay synchronous.
|
|
341
|
+
// Paths travel as argv — never interpolated into a shell string, where a
|
|
342
|
+
// quote in $BRAIN_DIR would break out of it.
|
|
343
|
+
execFileSync(
|
|
344
|
+
process.execPath,
|
|
345
|
+
[
|
|
346
|
+
'-e',
|
|
347
|
+
"require(process.argv[1]).push(process.argv[2]).then(() => process.exit(0)).catch(() => process.exit(1))",
|
|
348
|
+
path.join(__dirname, '..', 'src', 'git-sync.js'),
|
|
349
|
+
brainDir,
|
|
350
|
+
],
|
|
351
|
+
{ stdio: 'pipe', timeout: 30000 }
|
|
352
|
+
);
|
|
353
|
+
return { method: 'git', success: true };
|
|
354
|
+
} catch (err) {
|
|
355
|
+
return { method: 'git', success: false, error: err.message };
|
|
356
|
+
}
|
|
357
|
+
}
|
|
358
|
+
|
|
359
|
+
return { method: 'none', success: false, error: 'No sync configured (cloud or git)' };
|
|
360
|
+
}
|
|
361
|
+
|
|
362
|
+
// --- Main ---
|
|
363
|
+
|
|
364
|
+
async function main() {
|
|
365
|
+
const args = parseArgs(process.argv.slice(2));
|
|
366
|
+
|
|
367
|
+
// Read JSON from stdin
|
|
368
|
+
let inputData = '';
|
|
369
|
+
if (process.stdin.isTTY) {
|
|
370
|
+
console.error(JSON.stringify({ error: 'No input provided. Pipe JSON via stdin.' }));
|
|
371
|
+
process.exit(1);
|
|
372
|
+
}
|
|
373
|
+
|
|
374
|
+
// Read from fd 0 rather than the '/dev/stdin' path: the path form fails with
|
|
375
|
+
// ENXIO on Linux CI runners and doesn't exist on Windows, whereas fd 0 reads
|
|
376
|
+
// piped stdin portably across Linux, macOS, and Windows.
|
|
377
|
+
inputData = fs.readFileSync(0, 'utf-8');
|
|
378
|
+
|
|
379
|
+
let input;
|
|
380
|
+
try {
|
|
381
|
+
input = JSON.parse(inputData);
|
|
382
|
+
} catch (err) {
|
|
383
|
+
console.error(JSON.stringify({ error: `Invalid JSON input: ${err.message}` }));
|
|
384
|
+
process.exit(1);
|
|
385
|
+
}
|
|
386
|
+
|
|
387
|
+
if (!input.memories || !Array.isArray(input.memories) || input.memories.length === 0) {
|
|
388
|
+
console.error(JSON.stringify({ error: 'Input must have a non-empty "memories" array' }));
|
|
389
|
+
process.exit(1);
|
|
390
|
+
}
|
|
391
|
+
|
|
392
|
+
const brainDir = getBrainDir();
|
|
393
|
+
|
|
394
|
+
// Validate brain exists
|
|
395
|
+
if (!fs.existsSync(path.join(brainDir, 'index.json'))) {
|
|
396
|
+
console.error(JSON.stringify({ error: `Brain not initialized. Run brain install first.` }));
|
|
397
|
+
process.exit(1);
|
|
398
|
+
}
|
|
399
|
+
|
|
400
|
+
// Read current state
|
|
401
|
+
let index;
|
|
402
|
+
try {
|
|
403
|
+
index = readIndex();
|
|
404
|
+
} catch (err) {
|
|
405
|
+
console.error(JSON.stringify({
|
|
406
|
+
error: `Corrupt index.json in ~/.brain/ — ${err.message}. Fix the JSON manually or restore from sync/backup.`,
|
|
407
|
+
}));
|
|
408
|
+
process.exit(1);
|
|
409
|
+
}
|
|
410
|
+
|
|
411
|
+
let associations;
|
|
412
|
+
try {
|
|
413
|
+
associations = readAssociations() || { version: 1, edges: {} };
|
|
414
|
+
} catch (err) {
|
|
415
|
+
console.error(JSON.stringify({
|
|
416
|
+
error: `Corrupt associations.json in ~/.brain/ — ${err.message}`,
|
|
417
|
+
}));
|
|
418
|
+
process.exit(1);
|
|
419
|
+
}
|
|
420
|
+
|
|
421
|
+
let searchIndex;
|
|
422
|
+
try {
|
|
423
|
+
searchIndex = readSearchIndex(brainDir) || createSearchIndex();
|
|
424
|
+
} catch (err) {
|
|
425
|
+
// Search index is non-critical — rebuild from scratch
|
|
426
|
+
searchIndex = createSearchIndex();
|
|
427
|
+
}
|
|
428
|
+
|
|
429
|
+
const now = new Date().toISOString();
|
|
430
|
+
// Quarantine mode ('off' | 'flag' | 'enforce', default 'flag') — read once;
|
|
431
|
+
// readConfig tolerates a missing/corrupt config.json by falling back to defaults.
|
|
432
|
+
const config = readConfig();
|
|
433
|
+
const results = [];
|
|
434
|
+
const newIds = [];
|
|
435
|
+
const pinnedToAdd = [];
|
|
436
|
+
const clampsReported = [];
|
|
437
|
+
const auditErrors = [];
|
|
438
|
+
|
|
439
|
+
for (const rawMem of input.memories) {
|
|
440
|
+
// Validate required fields
|
|
441
|
+
if (!rawMem.title || !rawMem.type || !rawMem.path || !rawMem.content) {
|
|
442
|
+
console.error(JSON.stringify({
|
|
443
|
+
error: `Memory missing required fields (title, type, path, content): ${JSON.stringify(rawMem.title || 'untitled')}`,
|
|
444
|
+
}));
|
|
445
|
+
process.exit(1);
|
|
446
|
+
}
|
|
447
|
+
|
|
448
|
+
if (!TYPE_DEFAULTS[rawMem.type]) {
|
|
449
|
+
console.error(JSON.stringify({ error: `Unknown memory type: ${rawMem.type}` }));
|
|
450
|
+
process.exit(1);
|
|
451
|
+
}
|
|
452
|
+
|
|
453
|
+
// Provenance gate (ASI06) — decide what this origin is allowed to claim
|
|
454
|
+
// before anything reaches disk.
|
|
455
|
+
const policy = applyOriginPolicy(rawMem);
|
|
456
|
+
if (policy.error) {
|
|
457
|
+
console.error(JSON.stringify({ error: `${policy.error} — memory: ${JSON.stringify(rawMem.title)}` }));
|
|
458
|
+
process.exit(1);
|
|
459
|
+
}
|
|
460
|
+
const { origin } = policy;
|
|
461
|
+
const mem = policy.mem;
|
|
462
|
+
for (const c of policy.clamps) clampsReported.push({ ...c, title: rawMem.title });
|
|
463
|
+
|
|
464
|
+
// ASI06 content lint + quarantine decision. Lint runs for every origin
|
|
465
|
+
// (cheap, and the flags feed forensics even when nothing is quarantined);
|
|
466
|
+
// the decision flags low-trust origins and injection-shaped content.
|
|
467
|
+
const lint = lintMemoryContent(mem);
|
|
468
|
+
const quarantine = quarantineDecision({ origin, lintResult: lint, config });
|
|
469
|
+
|
|
470
|
+
// Generate ID
|
|
471
|
+
const id = generateId();
|
|
472
|
+
newIds.push(id);
|
|
473
|
+
|
|
474
|
+
// Compute strength/decay
|
|
475
|
+
const { fileContent, strength, decay_rate } = buildMemoryFileContent(
|
|
476
|
+
mem, id, now, origin, policy.policy.decay_multiplier, quarantine
|
|
477
|
+
);
|
|
478
|
+
|
|
479
|
+
// Create directories
|
|
480
|
+
const fullPath = path.join(brainDir, mem.path);
|
|
481
|
+
validateBrainPath(fullPath, brainDir);
|
|
482
|
+
fs.mkdirSync(path.dirname(fullPath), { recursive: true });
|
|
483
|
+
|
|
484
|
+
// Write memory file
|
|
485
|
+
atomicWriteSync(fullPath, fileContent);
|
|
486
|
+
|
|
487
|
+
// Record the write before reporting success. An audit failure is surfaced
|
|
488
|
+
// rather than thrown: the memory is already on disk, and silently dropping
|
|
489
|
+
// the trail would be the worse outcome of the two.
|
|
490
|
+
try {
|
|
491
|
+
appendAudit(brainDir, {
|
|
492
|
+
ts: now,
|
|
493
|
+
event: 'memorize',
|
|
494
|
+
id,
|
|
495
|
+
origin,
|
|
496
|
+
agent: HOST_AGENT,
|
|
497
|
+
type: mem.type,
|
|
498
|
+
path: mem.path,
|
|
499
|
+
title: mem.title,
|
|
500
|
+
salience: mem.salience ?? 0.5,
|
|
501
|
+
confidence: mem.confidence ?? 0.7,
|
|
502
|
+
decay_rate,
|
|
503
|
+
entrenched: Boolean(mem.pinned || mem.stable),
|
|
504
|
+
clamped: policy.clamps.map((c) => c.field),
|
|
505
|
+
...(lint.flags.length ? { lint: lint.flags.map((f) => f.rule) } : {}),
|
|
506
|
+
...(quarantine.quarantined ? { quarantined: true, quarantine_reasons: quarantine.reasons } : {}),
|
|
507
|
+
});
|
|
508
|
+
} catch (err) {
|
|
509
|
+
auditErrors.push({ id, error: err.message });
|
|
510
|
+
}
|
|
511
|
+
|
|
512
|
+
// Update index
|
|
513
|
+
const indexEntry = buildIndexEntry(mem, id, strength, decay_rate, now, origin, quarantine);
|
|
514
|
+
addMemory(index, id, indexEntry);
|
|
515
|
+
|
|
516
|
+
// CoALA Phase 1: register a born-pinned memory in the pinned manifest
|
|
517
|
+
if (mem.pinned) {
|
|
518
|
+
pinnedToAdd.push({
|
|
519
|
+
id,
|
|
520
|
+
scope: mem.pin_scope || 'global',
|
|
521
|
+
priority: mem.pin_priority || 0,
|
|
522
|
+
token_estimate: indexEntry.token_estimate,
|
|
523
|
+
});
|
|
524
|
+
}
|
|
525
|
+
|
|
526
|
+
// Temporal invalidation: stamp `superseded_by` on each memory this one
|
|
527
|
+
// replaces (index + frontmatter), and link them. The scorer strongly
|
|
528
|
+
// demotes a superseded memory so the successor wins, without dropping it —
|
|
529
|
+
// "this was true until now" stays answerable. Unknown target ids are
|
|
530
|
+
// skipped silently (they may have been forgotten).
|
|
531
|
+
const supersededNow = [];
|
|
532
|
+
for (const targetId of (mem.supersedes || [])) {
|
|
533
|
+
const target = index.memories[targetId];
|
|
534
|
+
if (!target) continue;
|
|
535
|
+
target.superseded_by = id;
|
|
536
|
+
setFrontmatterFields(brainDir, target.path, { superseded_by: id });
|
|
537
|
+
reinforceEdge(associations, id, targetId, 'manual', 0.20);
|
|
538
|
+
supersededNow.push({ id: targetId, title: target.title });
|
|
539
|
+
}
|
|
540
|
+
|
|
541
|
+
// Update associations — explicit related links
|
|
542
|
+
for (const relatedId of (mem.related || [])) {
|
|
543
|
+
if (index.memories[relatedId]) {
|
|
544
|
+
reinforceEdge(associations, id, relatedId, 'manual', 0.20);
|
|
545
|
+
}
|
|
546
|
+
}
|
|
547
|
+
|
|
548
|
+
// Update associations — tag overlaps
|
|
549
|
+
const tagOverlaps = findTagOverlaps(index, mem.tags, id);
|
|
550
|
+
for (const overlapId of tagOverlaps) {
|
|
551
|
+
reinforceEdge(associations, id, overlapId, 'tag_overlap', 0.10);
|
|
552
|
+
}
|
|
553
|
+
|
|
554
|
+
// Tier B §10.2: surface potential contradictions with pinned/stable memories
|
|
555
|
+
// (high tag overlap) so the agent can adjudicate — never auto-resolved here.
|
|
556
|
+
const potentialConflicts = tagOverlaps
|
|
557
|
+
.filter((oid) => {
|
|
558
|
+
const e = index.memories[oid];
|
|
559
|
+
return e && (e.pinned || e.stable);
|
|
560
|
+
})
|
|
561
|
+
.map((oid) => ({ id: oid, title: index.memories[oid].title }));
|
|
562
|
+
|
|
563
|
+
// Update search index
|
|
564
|
+
addDocument(searchIndex, id, {
|
|
565
|
+
title: mem.title,
|
|
566
|
+
tags: mem.tags,
|
|
567
|
+
body: mem.content,
|
|
568
|
+
});
|
|
569
|
+
|
|
570
|
+
// Update _meta.json files
|
|
571
|
+
updateMetaFiles(brainDir, mem.path);
|
|
572
|
+
|
|
573
|
+
const edgesCreated = (mem.related || []).filter(r => index.memories[r]).length + tagOverlaps.length;
|
|
574
|
+
|
|
575
|
+
results.push({
|
|
576
|
+
id,
|
|
577
|
+
title: mem.title,
|
|
578
|
+
path: mem.path,
|
|
579
|
+
type: mem.type,
|
|
580
|
+
cognitive_type: mem.cognitive_type || 'semantic',
|
|
581
|
+
strength,
|
|
582
|
+
decay_rate,
|
|
583
|
+
origin,
|
|
584
|
+
salience: mem.salience ?? 0.5,
|
|
585
|
+
confidence: mem.confidence ?? 0.7,
|
|
586
|
+
tags: mem.tags || [],
|
|
587
|
+
edges_created: edgesCreated,
|
|
588
|
+
...(potentialConflicts.length ? { potential_conflicts: potentialConflicts } : {}),
|
|
589
|
+
// Surfaced so the agent can tell the user a write went to pending
|
|
590
|
+
// verification (and why) — mirrors provenance_clamps reporting.
|
|
591
|
+
...(quarantine.quarantined
|
|
592
|
+
? { quarantine_pending: true, quarantine_reasons: quarantine.reasons }
|
|
593
|
+
: {}),
|
|
594
|
+
...(lint.flags.length ? { lint_flags: lint.flags.map((f) => f.rule) } : {}),
|
|
595
|
+
...(supersededNow.length ? { superseded: supersededNow } : {}),
|
|
596
|
+
});
|
|
597
|
+
}
|
|
598
|
+
|
|
599
|
+
// Write all updated state
|
|
600
|
+
writeIndex(index);
|
|
601
|
+
writeAssociations(associations);
|
|
602
|
+
writeSearchIndex(brainDir, searchIndex);
|
|
603
|
+
|
|
604
|
+
// CoALA Phase 1: persist any born-pinned memories to the pinned manifest
|
|
605
|
+
if (pinnedToAdd.length > 0) {
|
|
606
|
+
const pinned = readPinned();
|
|
607
|
+
for (const p of pinnedToAdd) {
|
|
608
|
+
pinned.pins = pinned.pins.filter((x) => x.id !== p.id);
|
|
609
|
+
pinned.pins.push(p);
|
|
610
|
+
}
|
|
611
|
+
writePinned(pinned);
|
|
612
|
+
}
|
|
613
|
+
|
|
614
|
+
// Build output
|
|
615
|
+
const output = {
|
|
616
|
+
stored: results,
|
|
617
|
+
total: results.length,
|
|
618
|
+
index_count: index.memory_count,
|
|
619
|
+
// Only present when the provenance policy actually lowered something, so
|
|
620
|
+
// the agent can tell the user a claim was downgraded and why.
|
|
621
|
+
...(clampsReported.length ? { provenance_clamps: clampsReported } : {}),
|
|
622
|
+
...(auditErrors.length ? { audit_errors: auditErrors } : {}),
|
|
623
|
+
};
|
|
624
|
+
|
|
625
|
+
// Sync if requested
|
|
626
|
+
if (args.sync || input.auto_sync) {
|
|
627
|
+
const syncResult = trySync();
|
|
628
|
+
output.sync = syncResult;
|
|
629
|
+
}
|
|
630
|
+
|
|
631
|
+
console.log(JSON.stringify(output, null, 2));
|
|
632
|
+
}
|
|
633
|
+
|
|
634
|
+
main().catch((err) => {
|
|
635
|
+
console.error(JSON.stringify({ error: err.message }));
|
|
636
|
+
process.exit(1);
|
|
637
|
+
});
|
package/bin/pin.js
ADDED
|
@@ -0,0 +1,44 @@
|
|
|
1
|
+
#!/usr/bin/env node
|
|
2
|
+
|
|
3
|
+
/**
|
|
4
|
+
* brain pin — pin a memory into the always-present semantic tier (CoALA Phase 1).
|
|
5
|
+
*
|
|
6
|
+
* Usage:
|
|
7
|
+
* brain pin <id> [--scope global|project:<name>] [--priority N]
|
|
8
|
+
*/
|
|
9
|
+
|
|
10
|
+
const { pinMemory } = require('../src/pinning');
|
|
11
|
+
|
|
12
|
+
function parseArgs(argv) {
|
|
13
|
+
const args = { id: null, scope: 'global', priority: 0 };
|
|
14
|
+
for (let i = 0; i < argv.length; i++) {
|
|
15
|
+
switch (argv[i]) {
|
|
16
|
+
case '--scope': args.scope = argv[++i]; break;
|
|
17
|
+
case '--priority': args.priority = parseInt(argv[++i], 10) || 0; break;
|
|
18
|
+
default:
|
|
19
|
+
if (!argv[i].startsWith('--') && !args.id) args.id = argv[i];
|
|
20
|
+
break;
|
|
21
|
+
}
|
|
22
|
+
}
|
|
23
|
+
return args;
|
|
24
|
+
}
|
|
25
|
+
|
|
26
|
+
function main(argv) {
|
|
27
|
+
const args = parseArgs(argv || process.argv.slice(2));
|
|
28
|
+
if (!args.id) {
|
|
29
|
+
console.error(JSON.stringify({ error: 'Usage: brain pin <id> [--scope global|project:<name>] [--priority N]' }));
|
|
30
|
+
process.exit(1);
|
|
31
|
+
}
|
|
32
|
+
const result = pinMemory(undefined, args.id, { scope: args.scope, priority: args.priority });
|
|
33
|
+
if (result.error) {
|
|
34
|
+
console.error(JSON.stringify(result));
|
|
35
|
+
process.exit(1);
|
|
36
|
+
}
|
|
37
|
+
console.log(JSON.stringify(result, null, 2));
|
|
38
|
+
}
|
|
39
|
+
|
|
40
|
+
if (require.main === module) {
|
|
41
|
+
main(process.argv.slice(2));
|
|
42
|
+
}
|
|
43
|
+
|
|
44
|
+
module.exports = { main, parseArgs };
|