brain-memory 0.1.0-beta.34 → 0.1.0-beta.36

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/src/harvest.js ADDED
@@ -0,0 +1,562 @@
1
+ /**
2
+ * Harvest — cold-start memory from the transcripts your agents already wrote.
3
+ *
4
+ * A fresh brain is empty, and an empty brain is worth nothing until someone
5
+ * feeds it. But every coding agent already keeps a local record of months of
6
+ * work: prompts, decisions, corrections, preferences. This module reads those
7
+ * records and turns them into a *digest* — a deterministic, budget-bounded
8
+ * summary of candidate sessions.
9
+ *
10
+ * What this module deliberately does NOT do is decide what is worth
11
+ * remembering. That is a semantic judgement, and Brain's whole design puts
12
+ * semantic judgement in the agent (see CLAUDE.md, "Agent-driven intelligence").
13
+ * Doing extraction here would mean shipping an embedding model or calling an
14
+ * LLM — the two things Brain exists to avoid. So the split is:
15
+ *
16
+ * harvest (this file, deterministic) → digest
17
+ * digest → agent reads it → `brain memorize` (existing path)
18
+ *
19
+ * The agent's distillation is `agent-inferred` provenance by construction, so
20
+ * imported memories inherit the existing ASI06 ceilings for free: an import can
21
+ * never pin, never entrench, and never outrank something the user said directly.
22
+ */
23
+
24
+ const fs = require('fs');
25
+ const os = require('os');
26
+ const path = require('path');
27
+
28
+ const { getBrainDir, atomicWriteSync } = require('./index-manager');
29
+
30
+ // --- Budgets ---
31
+ //
32
+ // A 500-session history would blow any context window, so the digest is capped
33
+ // on three independent axes. Sessions are the coarse cap, prompts the medium,
34
+ // and total characters the backstop that holds even if a single session is
35
+ // pathological.
36
+ const DEFAULTS = {
37
+ maxSessions: 40,
38
+ maxPromptsPerSession: 6,
39
+ maxPromptChars: 400,
40
+ maxDigestChars: 60000, // ~15k tokens at chars/4
41
+ };
42
+
43
+ // Sessions below this many real user prompts are almost always a mis-start, a
44
+ // one-line question, or an aborted run. They cost digest budget and yield
45
+ // nothing memorable.
46
+ const MIN_PROMPTS = 2;
47
+
48
+ // --- Text cleaning ---
49
+
50
+ // Harness-injected wrappers that are not user speech. Left in, they dominate the
51
+ // digest and teach the agent to memorize plumbing.
52
+ const STRIP_PATTERNS = [
53
+ /<system-reminder>[\s\S]*?<\/system-reminder>/g,
54
+ /<command-name>[\s\S]*?<\/command-name>/g,
55
+ /<command-message>[\s\S]*?<\/command-message>/g,
56
+ /<command-args>[\s\S]*?<\/command-args>/g,
57
+ /<local-command-stdout>[\s\S]*?<\/local-command-stdout>/g,
58
+ /<local-command-stderr>[\s\S]*?<\/local-command-stderr>/g,
59
+ /<user-prompt-submit-hook>[\s\S]*?<\/user-prompt-submit-hook>/g,
60
+ /\[Image #\d+\]/g,
61
+ /\[Request interrupted[^\]]*\]/g,
62
+ ];
63
+
64
+ // Whole prompts that carry no intent worth remembering.
65
+ const NOISE_PROMPTS = [
66
+ /^caveat: the messages below were generated by the user while running local commands/i,
67
+ /^\/[a-z0-9:_-]+\s*$/i, // a bare slash-command invocation
68
+ /^(y|n|yes|no|ok|okay|k|sure|thanks|thank you|ty|continue|go|go ahead|proceed|yep|yeah|nope)\b[.!]*$/i,
69
+ ];
70
+
71
+ /** Strip harness wrappers and normalize whitespace. Returns '' for pure noise. */
72
+ function cleanPromptText(raw) {
73
+ if (typeof raw !== 'string') return '';
74
+ let text = raw;
75
+ for (const pattern of STRIP_PATTERNS) text = text.replace(pattern, ' ');
76
+ text = text.replace(/\s+/g, ' ').trim();
77
+ if (!text) return '';
78
+ if (NOISE_PROMPTS.some((p) => p.test(text))) return '';
79
+ return text;
80
+ }
81
+
82
+ /** Truncate on a word boundary so the digest never ends mid-token. */
83
+ function truncate(text, max) {
84
+ if (text.length <= max) return text;
85
+ const cut = text.slice(0, max);
86
+ const lastSpace = cut.lastIndexOf(' ');
87
+ return (lastSpace > max * 0.6 ? cut.slice(0, lastSpace) : cut).trimEnd() + '…';
88
+ }
89
+
90
+ /**
91
+ * Pull the user-authored text out of one transcript record.
92
+ *
93
+ * `message.content` is either a bare string (older transcripts) or an array of
94
+ * blocks. Only `text` blocks are user speech — `tool_result` blocks are replayed
95
+ * command output that merely happens to be recorded under the user role.
96
+ */
97
+ function userTextFrom(record) {
98
+ const content = record && record.message && record.message.content;
99
+ if (typeof content === 'string') return cleanPromptText(content);
100
+ if (!Array.isArray(content)) return '';
101
+ return cleanPromptText(
102
+ content
103
+ .filter((block) => block && block.type === 'text' && typeof block.text === 'string')
104
+ .map((block) => block.text)
105
+ .join('\n')
106
+ );
107
+ }
108
+
109
+ // --- JSONL reading ---
110
+
111
+ /**
112
+ * Parse a JSONL transcript, skipping unparseable lines.
113
+ *
114
+ * Transcripts are appended to live by a running agent, so the final line of an
115
+ * in-flight session is routinely a partial write. That is expected, not an
116
+ * error: skip the line and keep the rest of the session.
117
+ */
118
+ function readJsonl(file) {
119
+ let raw;
120
+ try {
121
+ raw = fs.readFileSync(file, 'utf-8');
122
+ } catch (_) {
123
+ return [];
124
+ }
125
+ const records = [];
126
+ for (const line of raw.split('\n')) {
127
+ if (!line.trim()) continue;
128
+ try {
129
+ records.push(JSON.parse(line));
130
+ } catch (_) {
131
+ // Truncated tail or corrupt line — skip.
132
+ }
133
+ }
134
+ return records;
135
+ }
136
+
137
+ // --- Source adapters ---
138
+ //
139
+ // Each adapter turns one agent's on-disk history into a common session shape.
140
+ // Adding a source means adding an entry here; nothing downstream changes.
141
+
142
+ const FILE_EDIT_TOOLS = new Set(['Edit', 'Write', 'NotebookEdit', 'MultiEdit']);
143
+
144
+ /**
145
+ * Claude Code — one JSONL file per session under ~/.claude/projects/<slug>/.
146
+ *
147
+ * The directory slug is a lossy encoding of the working directory (every path
148
+ * separator and literal dash both become '-'), so it cannot be decoded back
149
+ * reliably. Records carry the real `cwd`, so we read it from there and keep the
150
+ * slug only as a last resort.
151
+ */
152
+ const claudeCode = {
153
+ id: 'claude-code',
154
+ label: 'Claude Code',
155
+ root: () => path.join(os.homedir(), '.claude', 'projects'),
156
+
157
+ listFiles(root) {
158
+ let dirs;
159
+ try {
160
+ dirs = fs.readdirSync(root, { withFileTypes: true });
161
+ } catch (_) {
162
+ return [];
163
+ }
164
+ const files = [];
165
+ for (const dir of dirs) {
166
+ if (!dir.isDirectory()) continue;
167
+ const dirPath = path.join(root, dir.name);
168
+ let entries;
169
+ try {
170
+ entries = fs.readdirSync(dirPath);
171
+ } catch (_) {
172
+ continue;
173
+ }
174
+ // Deliberately one level deep. Nested `<session-id>/subagents/*.jsonl`
175
+ // files are subagent transcripts — delegated tool traffic containing no
176
+ // user speech, and on this machine they outnumber real sessions almost
177
+ // 1:1. Recursing would double the scan cost to harvest pure noise.
178
+ for (const name of entries) {
179
+ if (name.endsWith('.jsonl')) files.push(path.join(dirPath, name));
180
+ }
181
+ }
182
+ return files.sort();
183
+ },
184
+
185
+ parse(file) {
186
+ const records = readJsonl(file);
187
+ if (records.length === 0) return null;
188
+
189
+ const session = {
190
+ source: 'claude-code',
191
+ session_id: null,
192
+ title: null,
193
+ cwd: null,
194
+ git_branch: null,
195
+ started: null,
196
+ ended: null,
197
+ models: new Set(),
198
+ prompts: [],
199
+ files_touched: new Set(),
200
+ turns: 0,
201
+ };
202
+
203
+ for (const record of records) {
204
+ if (!record || typeof record !== 'object') continue;
205
+ if (record.sessionId && !session.session_id) session.session_id = record.sessionId;
206
+
207
+ // Claude Code names sessions itself. That title is a free, already-curated
208
+ // summary — far better than anything we could derive with regexes.
209
+ if (record.type === 'ai-title' && record.aiTitle) session.title = record.aiTitle;
210
+
211
+ if (record.cwd) session.cwd = record.cwd;
212
+ if (record.gitBranch) session.git_branch = record.gitBranch;
213
+ if (record.timestamp) {
214
+ if (!session.started || record.timestamp < session.started) session.started = record.timestamp;
215
+ if (!session.ended || record.timestamp > session.ended) session.ended = record.timestamp;
216
+ }
217
+
218
+ // Sidechain records are subagent traffic, not the user talking.
219
+ if (record.isSidechain || record.isMeta) continue;
220
+
221
+ if (record.type === 'user') {
222
+ const text = userTextFrom(record);
223
+ if (text) session.prompts.push(text);
224
+ }
225
+
226
+ if (record.type === 'assistant') {
227
+ session.turns++;
228
+ const model = record.message && record.message.model;
229
+ if (model) session.models.add(model);
230
+ const content = (record.message && record.message.content) || [];
231
+ if (Array.isArray(content)) {
232
+ for (const block of content) {
233
+ if (block && block.type === 'tool_use' && FILE_EDIT_TOOLS.has(block.name)) {
234
+ const target = block.input && (block.input.file_path || block.input.notebook_path);
235
+ if (target) session.files_touched.add(target);
236
+ }
237
+ }
238
+ }
239
+ }
240
+ }
241
+
242
+ if (!session.session_id) session.session_id = path.basename(file, '.jsonl');
243
+ if (!session.cwd) session.cwd = slugToPathGuess(path.basename(path.dirname(file)));
244
+ return session;
245
+ },
246
+ };
247
+
248
+ /**
249
+ * Best-effort recovery of a working directory from a Claude Code project slug.
250
+ *
251
+ * Lossy by nature — '-Users-me-code-my-app' could be '/Users/me/code/my-app' or
252
+ * '/Users/me/code/my/app'. Only used when no record carried a real `cwd`, and
253
+ * only to label the session, never to write anything.
254
+ */
255
+ function slugToPathGuess(slug) {
256
+ if (!slug || !slug.startsWith('-')) return slug || null;
257
+ return '/' + slug.slice(1).replace(/-/g, '/');
258
+ }
259
+
260
+ const SOURCES = { [claudeCode.id]: claudeCode };
261
+
262
+ /** Sources that actually have a history store on this machine. */
263
+ function availableSources() {
264
+ return Object.values(SOURCES)
265
+ .map((adapter) => {
266
+ const root = adapter.root();
267
+ const present = fs.existsSync(root);
268
+ return {
269
+ id: adapter.id,
270
+ label: adapter.label,
271
+ root,
272
+ available: present,
273
+ sessions: present ? adapter.listFiles(root).length : 0,
274
+ };
275
+ });
276
+ }
277
+
278
+ // --- Import state ---
279
+ //
280
+ // Import is incremental. Without a cursor, a second run re-offers every session
281
+ // and the agent writes the same memories again — the fastest way to poison a
282
+ // brain with duplicates.
283
+
284
+ function importStatePath(projectRoot) {
285
+ return path.join(getBrainDir(projectRoot), '.import', 'state.json');
286
+ }
287
+
288
+ function readImportState(projectRoot) {
289
+ try {
290
+ const parsed = JSON.parse(fs.readFileSync(importStatePath(projectRoot), 'utf-8'));
291
+ if (parsed && typeof parsed === 'object' && parsed.sources) return parsed;
292
+ } catch (_) {
293
+ // Missing or corrupt — a fresh cursor is always safe, it only means the
294
+ // next run re-offers sessions the agent can recognize as already-known.
295
+ }
296
+ return { version: 1, sources: {} };
297
+ }
298
+
299
+ function writeImportState(state, projectRoot) {
300
+ const file = importStatePath(projectRoot);
301
+ fs.mkdirSync(path.dirname(file), { recursive: true });
302
+ atomicWriteSync(file, JSON.stringify(state, null, 2) + '\n');
303
+ }
304
+
305
+ /**
306
+ * Record sessions as imported so later runs skip them.
307
+ *
308
+ * Ids are checked against the source's real sessions first. A silently accepted
309
+ * typo or truncated id is the worst possible failure here: the caller is told
310
+ * the session is done, the cursor never matches it, and the session is re-offered
311
+ * forever — so unknown ids are reported back rather than written.
312
+ *
313
+ * When the source's history is not enumerable — an unregistered source, or a
314
+ * store that isn't on this machine — there is nothing to check against, so ids
315
+ * are accepted as given rather than rejected on no evidence.
316
+ *
317
+ * @param {string} sourceId
318
+ * @param {string[]} sessionIds
319
+ * @param {string} [projectRoot] - Filesystem root whose .brain/ to use
320
+ * @param {Set<string>} [knownIds] - Override the enumerated id set (tests)
321
+ * @returns {{ added: number, total: number, unknown: string[] }}
322
+ */
323
+ function markImported(sourceId, sessionIds, projectRoot, knownIds) {
324
+ let known = knownIds || null;
325
+ if (!known) {
326
+ const adapter = SOURCES[sourceId];
327
+ if (adapter) {
328
+ const root = adapter.root();
329
+ if (fs.existsSync(root)) {
330
+ known = new Set(adapter.listFiles(root).map((f) => path.basename(f, '.jsonl')));
331
+ }
332
+ }
333
+ }
334
+
335
+ const state = readImportState(projectRoot);
336
+ if (!state.sources[sourceId]) state.sources[sourceId] = { imported: {} };
337
+ const now = new Date().toISOString();
338
+
339
+ const unknown = [];
340
+ let added = 0;
341
+ for (const id of sessionIds) {
342
+ if (known && !known.has(id)) { unknown.push(id); continue; }
343
+ if (!state.sources[sourceId].imported[id]) added++;
344
+ state.sources[sourceId].imported[id] = now;
345
+ }
346
+ writeImportState(state, projectRoot);
347
+ return {
348
+ added,
349
+ total: Object.keys(state.sources[sourceId].imported).length,
350
+ unknown,
351
+ };
352
+ }
353
+
354
+ // --- Digest ---
355
+
356
+ /** Deduplicate consecutive near-identical prompts (retries, resends). */
357
+ function dedupePrompts(prompts) {
358
+ const out = [];
359
+ const seen = new Set();
360
+ for (const prompt of prompts) {
361
+ const key = prompt.slice(0, 120).toLowerCase();
362
+ if (seen.has(key)) continue;
363
+ seen.add(key);
364
+ out.push(prompt);
365
+ }
366
+ return out;
367
+ }
368
+
369
+ /**
370
+ * Pick which prompts represent the session.
371
+ *
372
+ * The opening prompt states the goal and the closing ones state what it became,
373
+ * so both edges are kept and the middle is sampled. Taking the first N instead
374
+ * would systematically lose every outcome.
375
+ */
376
+ function selectPrompts(prompts, max) {
377
+ if (prompts.length <= max) return prompts;
378
+ const head = Math.ceil(max / 2);
379
+ const tail = max - head;
380
+ return [...prompts.slice(0, head), ...prompts.slice(prompts.length - tail)];
381
+ }
382
+
383
+ /**
384
+ * Round-robin candidates across projects, preserving recency within each.
385
+ *
386
+ * Sorting by recency alone lets one busy repo eat the entire budget — on a real
387
+ * 261-session history, one project took 32 of 38 slots and five others got a
388
+ * single session between them. Cold-start value comes from breadth (the agent
389
+ * learning that you work on N things, and what each one is) far more than from
390
+ * depth in whichever repo you happened to touch last week.
391
+ */
392
+ function interleaveByProject(candidates) {
393
+ const byProject = new Map();
394
+ for (const candidate of candidates) {
395
+ const key = candidate.project || '(unknown)';
396
+ if (!byProject.has(key)) byProject.set(key, []);
397
+ byProject.get(key).push(candidate);
398
+ }
399
+
400
+ // Projects with recent activity lead, so the first round is the work most
401
+ // likely to still be live.
402
+ const queues = [...byProject.values()];
403
+ const ordered = [];
404
+ for (let round = 0; ordered.length < candidates.length; round++) {
405
+ for (const queue of queues) {
406
+ if (round < queue.length) ordered.push(queue[round]);
407
+ }
408
+ }
409
+ return ordered;
410
+ }
411
+
412
+ /** Human-facing project label — the directory name is what users call a project. */
413
+ function projectNameOf(session) {
414
+ if (!session.cwd) return null;
415
+ return path.basename(session.cwd) || null;
416
+ }
417
+
418
+ /**
419
+ * Build a budget-bounded digest of candidate sessions.
420
+ *
421
+ * @param {Object} [opts]
422
+ * @param {string} [opts.source='claude-code'] - Source adapter id
423
+ * @param {string} [opts.project] - Only sessions whose project name matches
424
+ * @param {string} [opts.since] - ISO date; only sessions ended at/after it
425
+ * @param {number} [opts.limit] - Max sessions in the digest
426
+ * @param {boolean} [opts.all=false] - Include already-imported sessions
427
+ * @param {string} [opts.projectRoot] - Filesystem root whose .brain/ to use
428
+ * @returns {Object} digest payload
429
+ */
430
+ function harvest(opts = {}) {
431
+ const sourceId = opts.source || 'claude-code';
432
+ const adapter = SOURCES[sourceId];
433
+ if (!adapter) {
434
+ return { error: `Unknown source "${sourceId}" (available: ${Object.keys(SOURCES).join(', ')})` };
435
+ }
436
+
437
+ const limit = opts.limit || DEFAULTS.maxSessions;
438
+ const root = adapter.root();
439
+ if (!fs.existsSync(root)) {
440
+ return {
441
+ source: sourceId,
442
+ scanned: { files: 0, sessions: 0, skipped: 0, already_imported: 0 },
443
+ sessions: [],
444
+ note: `No ${adapter.label} history found at ${root}.`,
445
+ };
446
+ }
447
+
448
+ const state = readImportState(opts.projectRoot);
449
+ const done = (state.sources[sourceId] && state.sources[sourceId].imported) || {};
450
+
451
+ const files = adapter.listFiles(root);
452
+ const candidates = [];
453
+ // Kept apart on purpose: `skipped` means "held nothing worth reading",
454
+ // `filtered` means "excluded by your --project/--since scoping". Merging them
455
+ // would report a scoped run as though it had discarded hundreds of bad
456
+ // sessions, which is both alarming and false.
457
+ let skipped = 0;
458
+ let filtered = 0;
459
+ let alreadyImported = 0;
460
+
461
+ for (const file of files) {
462
+ const session = adapter.parse(file);
463
+ if (!session) { skipped++; continue; }
464
+
465
+ if (!opts.all && done[session.session_id]) { alreadyImported++; continue; }
466
+
467
+ const prompts = dedupePrompts(session.prompts);
468
+ if (prompts.length < MIN_PROMPTS) { skipped++; continue; }
469
+
470
+ const project = projectNameOf(session);
471
+ if (opts.project && project !== opts.project) { filtered++; continue; }
472
+ if (opts.since && session.ended && session.ended < opts.since) { filtered++; continue; }
473
+
474
+ candidates.push({ session, prompts, project });
475
+ }
476
+
477
+ // Most recent first: recent work is both likelier to matter and likelier to
478
+ // still be true. An import that runs out of budget should run out on the
479
+ // oldest sessions, not the newest.
480
+ candidates.sort((a, b) => String(b.session.ended || '').localeCompare(String(a.session.ended || '')));
481
+
482
+ const ordered = interleaveByProject(candidates);
483
+
484
+ const sessions = [];
485
+ let chars = 0;
486
+ let budgetTruncated = false;
487
+
488
+ for (const candidate of ordered) {
489
+ if (sessions.length >= limit) { budgetTruncated = true; break; }
490
+
491
+ const { session, prompts, project } = candidate;
492
+ const selected = selectPrompts(prompts, DEFAULTS.maxPromptsPerSession)
493
+ .map((p) => truncate(p, DEFAULTS.maxPromptChars));
494
+
495
+ const entry = {
496
+ session_id: session.session_id,
497
+ title: session.title || null,
498
+ project,
499
+ cwd: session.cwd,
500
+ git_branch: session.git_branch || null,
501
+ started: session.started,
502
+ ended: session.ended,
503
+ turns: session.turns,
504
+ prompt_count: prompts.length,
505
+ models: [...session.models],
506
+ files_touched: [...session.files_touched]
507
+ .map((f) => (session.cwd && f.startsWith(session.cwd) ? path.relative(session.cwd, f) : f))
508
+ .slice(0, 12),
509
+ prompts: selected,
510
+ };
511
+
512
+ const cost = JSON.stringify(entry).length;
513
+ if (chars + cost > DEFAULTS.maxDigestChars && sessions.length > 0) {
514
+ budgetTruncated = true;
515
+ break;
516
+ }
517
+ chars += cost;
518
+ sessions.push(entry);
519
+ }
520
+
521
+ return {
522
+ source: sourceId,
523
+ source_label: adapter.label,
524
+ scanned: {
525
+ files: files.length,
526
+ candidates: candidates.length,
527
+ returned: sessions.length,
528
+ skipped,
529
+ filtered,
530
+ already_imported: alreadyImported,
531
+ remaining: Math.max(0, candidates.length - sessions.length),
532
+ },
533
+ budget: {
534
+ max_sessions: limit,
535
+ max_digest_chars: DEFAULTS.maxDigestChars,
536
+ used_chars: chars,
537
+ token_estimate: Math.ceil(chars / 4),
538
+ truncated: budgetTruncated,
539
+ },
540
+ sessions,
541
+ };
542
+ }
543
+
544
+ module.exports = {
545
+ harvest,
546
+ availableSources,
547
+ markImported,
548
+ readImportState,
549
+ writeImportState,
550
+ importStatePath,
551
+ // Exported for tests
552
+ cleanPromptText,
553
+ userTextFrom,
554
+ selectPrompts,
555
+ dedupePrompts,
556
+ truncate,
557
+ slugToPathGuess,
558
+ readJsonl,
559
+ SOURCES,
560
+ DEFAULTS,
561
+ MIN_PROMPTS,
562
+ };
@@ -0,0 +1,79 @@
1
+ /**
2
+ * Brain Memory — Provenance Policy (OWASP ASI06: memory poisoning)
3
+ *
4
+ * Single source of truth for what a memory's origin allows it to claim — at
5
+ * write time (bin/memorize.js clamps salience/confidence and refuses
6
+ * entrenchment) and at recall time (src/scorer.js weighs trust into ranking,
7
+ * bin/recall.js and bin/session-start.js flag low-trust results).
8
+ *
9
+ * The failure mode this defends against: content the agent *read* (an email, a
10
+ * web page, a tool result) persuades it to write a fact, and that fact then
11
+ * hardens — pinned into every session, exempt from decay, immune to pruning,
12
+ * never flagged as uncertain, and boosted by its own planted neighbors at
13
+ * recall. See MemGhost (arXiv:2607.05189).
14
+ *
15
+ * `origin` is asserted by the caller, so it does not defend against a fully
16
+ * hostile agent — but the dominant real case is an *honest* agent relaying
17
+ * poisoned content, and there it holds.
18
+ */
19
+
20
+ const ORIGIN_POLICY = {
21
+ // The user asked for this directly, in-session.
22
+ user: { max_salience: 1.0, max_confidence: 1.0, allow_entrench: true, decay_multiplier: 1.0, trust_factor: 1.0 },
23
+ // The agent inferred or summarized it from session context. Default.
24
+ 'agent-inferred': { max_salience: 0.6, max_confidence: 0.8, allow_entrench: false, decay_multiplier: 1.0, trust_factor: 0.95 },
25
+ // Derived from tool output — file reads, command results, MCP responses.
26
+ 'tool-output': { max_salience: 0.5, max_confidence: 0.6, allow_entrench: false, decay_multiplier: 0.997, trust_factor: 0.85 },
27
+ // Derived from untrusted external content — email, web pages, issue text.
28
+ external: { max_salience: 0.4, max_confidence: 0.4, allow_entrench: false, decay_multiplier: 0.99, trust_factor: 0.75 },
29
+ };
30
+
31
+ // Absent origin means the agent didn't tell us — assume the weaker claim, never
32
+ // the stronger one. A memory that deserves `user` is one keystroke away.
33
+ const DEFAULT_ORIGIN = 'agent-inferred';
34
+
35
+ // Salience >= 0.7 is exempt from auto-pruning, so every non-user ceiling sits
36
+ // below it: an unattended poisoned memory must remain collectable.
37
+ const PRUNE_EXEMPT_SALIENCE = 0.7;
38
+
39
+ // Origins whose content came from outside the user/agent dialogue — surfaced
40
+ // with a low_trust flag at recall and a ⚠ marker on receipts.
41
+ const LOW_TRUST_ORIGINS = new Set(['tool-output', 'external']);
42
+
43
+ /**
44
+ * Recall-time trust weight for an origin (0.75-1.0).
45
+ *
46
+ * Applied as a multiplier on the composite recall score and on spreading-
47
+ * activation source strength. Trust bounds *entrenchment and volume*, not
48
+ * relevance: a genuinely more relevant external memory can still rank first —
49
+ * it just can't get there on bulk or clique self-amplification.
50
+ *
51
+ * Unknown/missing origins weigh as DEFAULT_ORIGIN: legacy memories (written
52
+ * before origin existed) rank exactly as if memorize had stamped its default,
53
+ * so their relative order is unchanged.
54
+ *
55
+ * @param {string} [origin] - Memory origin (frontmatter/index `origin` field)
56
+ * @returns {number} Trust factor
57
+ */
58
+ function trustFactor(origin) {
59
+ const policy = ORIGIN_POLICY[origin] || ORIGIN_POLICY[DEFAULT_ORIGIN];
60
+ return policy.trust_factor;
61
+ }
62
+
63
+ /**
64
+ * Whether an origin is low-trust (content sourced outside the dialogue).
65
+ *
66
+ * @param {string} [origin] - Memory origin
67
+ * @returns {boolean}
68
+ */
69
+ function isLowTrust(origin) {
70
+ return LOW_TRUST_ORIGINS.has(origin);
71
+ }
72
+
73
+ module.exports = {
74
+ ORIGIN_POLICY,
75
+ DEFAULT_ORIGIN,
76
+ PRUNE_EXEMPT_SALIENCE,
77
+ trustFactor,
78
+ isLowTrust,
79
+ };
package/src/receipt.js CHANGED
@@ -9,6 +9,11 @@
9
9
  *
10
10
  * Format: ◉ memory: "<title>" (<type>, <age>)
11
11
  *
12
+ * Low-trust origins (tool-output, external — see src/provenance.js) carry a
13
+ * trailing warning segment so a poisoned-source memory is visibly marked
14
+ * wherever its receipt appears: ◉ memory: "<title>" (<type>, <age>, ⚠ external)
15
+ * User/agent-inferred receipts are byte-identical to the base format.
16
+ *
12
17
  * Age is derived from the memory's `created` timestamp (falling back to
13
18
  * `last_accessed`; omitted entirely when neither parses):
14
19
  * today | yesterday | <N>d ago (2-30 days) | <N>mo ago (31-364 days,
@@ -17,6 +22,8 @@
17
22
  * Deterministic: `now` is injectable for tests.
18
23
  */
19
24
 
25
+ const { isLowTrust } = require('./provenance');
26
+
20
27
  const MS_PER_DAY = 24 * 60 * 60 * 1000;
21
28
  const DAYS_PER_MONTH = 30.44; // mean Gregorian month
22
29
  const DAYS_PER_YEAR = 365.25;
@@ -59,10 +66,11 @@ function receiptFor(memoryLike, nowFn) {
59
66
 
60
67
  const type = typeof mem.type === 'string' && mem.type ? mem.type : 'memory';
61
68
  const age = ageLabel(mem.created ?? mem.last_accessed ?? NaN, now);
69
+ const trust = isLowTrust(mem.origin) ? `, ⚠ ${mem.origin}` : '';
62
70
 
63
71
  return age
64
- ? `◉ memory: "${title}" (${type}, ${age})`
65
- : `◉ memory: "${title}" (${type})`;
72
+ ? `◉ memory: "${title}" (${type}, ${age}${trust})`
73
+ : `◉ memory: "${title}" (${type}${trust})`;
66
74
  }
67
75
 
68
76
  module.exports = { receiptFor, ageLabel };