@blockrun/franklin 3.33.0 → 3.34.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 (78) hide show
  1. package/README.md +23 -2
  2. package/dist/agent/approvals.d.ts +47 -0
  3. package/dist/agent/approvals.js +66 -0
  4. package/dist/agent/commands.js +230 -7
  5. package/dist/agent/input-queue.d.ts +26 -0
  6. package/dist/agent/input-queue.js +65 -0
  7. package/dist/agent/loop.js +196 -3
  8. package/dist/agent/streaming-executor.d.ts +4 -0
  9. package/dist/agent/streaming-executor.js +52 -0
  10. package/dist/agent/tool-guard.d.ts +7 -0
  11. package/dist/agent/tool-guard.js +21 -0
  12. package/dist/agent/types.d.ts +26 -0
  13. package/dist/audit/approvals.d.ts +20 -0
  14. package/dist/audit/approvals.js +21 -0
  15. package/dist/commands/start.d.ts +10 -1
  16. package/dist/commands/start.js +53 -1
  17. package/dist/events/types.d.ts +38 -1
  18. package/dist/goal/engine.d.ts +39 -0
  19. package/dist/goal/engine.js +182 -0
  20. package/dist/goal/prompts.d.ts +16 -0
  21. package/dist/goal/prompts.js +206 -0
  22. package/dist/goal/runtime.d.ts +20 -0
  23. package/dist/goal/runtime.js +110 -0
  24. package/dist/goal/store.d.ts +22 -0
  25. package/dist/goal/store.js +79 -0
  26. package/dist/goal/types.d.ts +63 -0
  27. package/dist/goal/types.js +26 -0
  28. package/dist/hooks/loader.d.ts +19 -0
  29. package/dist/hooks/loader.js +115 -0
  30. package/dist/hooks/runner.d.ts +31 -0
  31. package/dist/hooks/runner.js +147 -0
  32. package/dist/hooks/types.d.ts +64 -0
  33. package/dist/hooks/types.js +35 -0
  34. package/dist/index.js +5 -1
  35. package/dist/memory/capture.d.ts +40 -0
  36. package/dist/memory/capture.js +95 -0
  37. package/dist/memory/dream.d.ts +24 -0
  38. package/dist/memory/dream.js +147 -0
  39. package/dist/memory/indexer.d.ts +29 -0
  40. package/dist/memory/indexer.js +144 -0
  41. package/dist/memory/store.d.ts +50 -0
  42. package/dist/memory/store.js +163 -0
  43. package/dist/monitors/registry.d.ts +42 -0
  44. package/dist/monitors/registry.js +104 -0
  45. package/dist/panel/html.js +299 -0
  46. package/dist/panel/server.js +41 -0
  47. package/dist/scheduler/service.d.ts +24 -0
  48. package/dist/scheduler/service.js +44 -0
  49. package/dist/scheduler/store.d.ts +26 -0
  50. package/dist/scheduler/store.js +116 -0
  51. package/dist/scheduler/types.d.ts +36 -0
  52. package/dist/scheduler/types.js +31 -0
  53. package/dist/serve/agent-host.d.ts +63 -0
  54. package/dist/serve/agent-host.js +270 -0
  55. package/dist/serve/server.js +131 -2
  56. package/dist/session/live-registry.d.ts +32 -0
  57. package/dist/session/live-registry.js +83 -0
  58. package/dist/session/search.d.ts +6 -0
  59. package/dist/session/search.js +3 -3
  60. package/dist/session/storage.d.ts +6 -0
  61. package/dist/session/storage.js +6 -0
  62. package/dist/tools/goal.d.ts +7 -0
  63. package/dist/tools/goal.js +29 -0
  64. package/dist/tools/index.js +11 -0
  65. package/dist/tools/memory.js +14 -4
  66. package/dist/tools/monitor.d.ts +11 -0
  67. package/dist/tools/monitor.js +96 -0
  68. package/dist/tools/scheduler.d.ts +12 -0
  69. package/dist/tools/scheduler.js +79 -0
  70. package/dist/tools/spend-tools.d.ts +33 -0
  71. package/dist/tools/spend-tools.js +114 -0
  72. package/dist/tools/tool-categories.js +7 -0
  73. package/dist/tools/trade-plan.d.ts +11 -0
  74. package/dist/tools/trade-plan.js +137 -0
  75. package/dist/tools/trading-execute.js +24 -0
  76. package/dist/trading/trade-plan.d.ts +75 -0
  77. package/dist/trading/trade-plan.js +290 -0
  78. package/package.json +2 -2
@@ -0,0 +1,35 @@
1
+ /**
2
+ * Lifecycle hooks — user-authored guardrails and automations.
3
+ *
4
+ * Hooks are external commands the harness runs at fixed lifecycle points.
5
+ * They receive a JSON envelope on stdin and can veto the action (blocking
6
+ * events only) by exiting 2 or printing {"decision":"deny"} on stdout.
7
+ *
8
+ * Safety model: hooks are a convenience layer, not a security boundary.
9
+ * A hook that crashes, times out, or is missing FAILS OPEN — work proceeds
10
+ * and the failure is logged. Only an explicit deny blocks. This keeps a
11
+ * buggy hook from bricking the agent while still letting deliberate policy
12
+ * (spend caps, token blacklists) intercept actions.
13
+ */
14
+ /** Events whose handlers can veto the action. All others are notify-only. */
15
+ export const BLOCKING_EVENTS = new Set([
16
+ 'PreToolUse',
17
+ 'PreSpend',
18
+ ]);
19
+ /** Events that carry no tool context — a matcher on these is a config error. */
20
+ export const LIFECYCLE_EVENTS = new Set([
21
+ 'SessionStart',
22
+ 'UserPromptSubmit',
23
+ 'Stop',
24
+ 'SessionEnd',
25
+ ]);
26
+ export const HOOK_EVENTS = new Set([
27
+ 'SessionStart',
28
+ 'UserPromptSubmit',
29
+ 'PreToolUse',
30
+ 'PostToolUse',
31
+ 'Stop',
32
+ 'SessionEnd',
33
+ 'PreSpend',
34
+ 'PostSpend',
35
+ ]);
package/dist/index.js CHANGED
@@ -53,6 +53,7 @@ program
53
53
  .option('-c, --continue', 'Continue the most recent session in this directory')
54
54
  .option('--max-spend <usd>', 'Hard USD cap on total session API spend — session stops when exceeded')
55
55
  .option('-p, --prompt <text>', 'Run a single prompt non-interactively (for batch/scripted use)')
56
+ .option('--approve-trades', 'Non-interactive runs: auto-approve trade plans that fit within --max-spend (default: reject all trades)')
56
57
  .action((fromSessionId, options) => startCommand({ ...options, fromSessionId, version }));
57
58
  program
58
59
  .command('resume [sessionId]')
@@ -276,7 +277,7 @@ const args = process.argv.slice(2);
276
277
  const firstArg = args[0];
277
278
  const HELP_FLAGS = new Set(['-h', '--help']);
278
279
  const VERSION_FLAGS = new Set(['-V', '--version']);
279
- const START_ONLY_FLAGS = new Set(['--trust', '--debug', '-m', '--model', '--from', '-r', '--resume', '-c', '--continue', '-p', '--prompt', '--max-spend']);
280
+ const START_ONLY_FLAGS = new Set(['--trust', '--debug', '-m', '--model', '--from', '-r', '--resume', '-c', '--continue', '-p', '--prompt', '--max-spend', '--approve-trades']);
280
281
  function hasAnyFlag(argv, flags) {
281
282
  return argv.some(arg => flags.has(arg));
282
283
  }
@@ -300,6 +301,9 @@ function parseStartFlags(argv, startIdx = 0) {
300
301
  else if (arg === '--max-spend' && argv[i + 1]) {
301
302
  opts.maxSpend = argv[++i];
302
303
  }
304
+ else if (arg === '--approve-trades') {
305
+ opts.approveTrades = true;
306
+ }
303
307
  else if (arg === '--from') {
304
308
  opts.from = argv[i + 1] && !argv[i + 1].startsWith('-') ? argv[++i] : '';
305
309
  const next = argv[i + 1];
@@ -0,0 +1,40 @@
1
+ /**
2
+ * Memory capture pipeline:
3
+ * - zero-LLM session summaries at session end (metadata only, free)
4
+ * - /flush — LLM capture of the session's durable learnings
5
+ * - trading capture — journal + thesis entries on trade execution
6
+ */
7
+ import type { Dialogue } from '../agent/types.js';
8
+ import type { ModelClient } from '../agent/llm.js';
9
+ /**
10
+ * Metadata-only session summary — no LLM call, no latency, no cost.
11
+ * Trivial sessions (fewer than 3 substantive prompts) are skipped.
12
+ */
13
+ export declare function writeSessionMetadataSummary(opts: {
14
+ workDir: string;
15
+ sessionId: string;
16
+ history: Dialogue[];
17
+ costUsd?: number;
18
+ }): boolean;
19
+ /** /flush — LLM capture of the session's durable content into a session log. */
20
+ export declare function flushSessionMemory(opts: {
21
+ client: ModelClient;
22
+ model: string;
23
+ workDir: string;
24
+ sessionId: string;
25
+ history: Dialogue[];
26
+ signal?: AbortSignal;
27
+ }): Promise<string | null>;
28
+ export interface TradeMemoryEvent {
29
+ kind: 'open' | 'close' | 'bet';
30
+ chain: string;
31
+ address: string;
32
+ asset: string;
33
+ amountUsd?: number;
34
+ thesis?: string;
35
+ pnlUsd?: number;
36
+ /** Reference into trades.jsonl / tx hash for the audit trail. */
37
+ ref?: string;
38
+ }
39
+ /** Append a curated journal entry (and thesis file on opens with a thesis). */
40
+ export declare function captureTradeEvent(event: TradeMemoryEvent): void;
@@ -0,0 +1,95 @@
1
+ /**
2
+ * Memory capture pipeline:
3
+ * - zero-LLM session summaries at session end (metadata only, free)
4
+ * - /flush — LLM capture of the session's durable learnings
5
+ * - trading capture — journal + thesis entries on trade execution
6
+ */
7
+ import { recordUsage } from '../stats/tracker.js';
8
+ import { estimateCost } from '../pricing.js';
9
+ import { appendUnderHeading, memoryEnabled, sessionLogPath, thesisPath, tradingJournalPath, writeSessionLog, } from './store.js';
10
+ function userPrompts(history) {
11
+ const prompts = [];
12
+ for (const msg of history) {
13
+ if (msg.role !== 'user' || typeof msg.content !== 'string')
14
+ continue;
15
+ const text = msg.content.trim();
16
+ // Skip harness-injected continuations and command noise.
17
+ if (!text || text.startsWith('/') || text.startsWith('Continue working the active goal'))
18
+ continue;
19
+ prompts.push(text);
20
+ }
21
+ return prompts;
22
+ }
23
+ /**
24
+ * Metadata-only session summary — no LLM call, no latency, no cost.
25
+ * Trivial sessions (fewer than 3 substantive prompts) are skipped.
26
+ */
27
+ export function writeSessionMetadataSummary(opts) {
28
+ if (!memoryEnabled())
29
+ return false;
30
+ const prompts = userPrompts(opts.history);
31
+ const totalUserBytes = prompts.reduce((n, p) => n + p.length, 0);
32
+ if (prompts.length < 3 || totalUserBytes < 50)
33
+ return false;
34
+ const topics = prompts.slice(0, 5).map(p => `- ${p.replace(/\s+/g, ' ').slice(0, 120)}`);
35
+ writeSessionLog(opts.workDir, opts.sessionId, [
36
+ `# Session ${opts.sessionId.slice(0, 8)} — ${new Date().toISOString()}`,
37
+ '',
38
+ `Messages: ${opts.history.length} · user prompts: ${prompts.length}` +
39
+ (opts.costUsd != null ? ` · cost: $${opts.costUsd.toFixed(4)}` : ''),
40
+ '',
41
+ '## Topics',
42
+ ...topics,
43
+ ].join('\n'));
44
+ return true;
45
+ }
46
+ const FLUSH_PROMPT = `Review the conversation above and extract ONLY the durable learnings worth
47
+ remembering across sessions: decisions made and why, facts discovered about the
48
+ user's holdings/preferences/projects, working theses, and outcomes of actions
49
+ taken. Skip process narration and anything trivially re-derivable. Output tight
50
+ markdown bullets grouped under ## headings (Preferences / Decisions / Findings /
51
+ Theses as applicable), max 2000 characters. If nothing is worth keeping, output
52
+ exactly: NOTHING_DURABLE`;
53
+ /** /flush — LLM capture of the session's durable content into a session log. */
54
+ export async function flushSessionMemory(opts) {
55
+ if (!memoryEnabled())
56
+ return null;
57
+ const { content, usage } = await opts.client.complete({
58
+ model: opts.model,
59
+ messages: [...opts.history, { role: 'user', content: FLUSH_PROMPT }],
60
+ max_tokens: 1024,
61
+ stream: true,
62
+ }, opts.signal ?? new AbortController().signal);
63
+ try {
64
+ recordUsage(opts.model, usage.inputTokens, usage.outputTokens, estimateCost(opts.model, usage.inputTokens, usage.outputTokens), 0);
65
+ }
66
+ catch { /* best-effort */ }
67
+ const text = content
68
+ .filter((p) => p.type === 'text')
69
+ .map(p => p.text)
70
+ .join('\n')
71
+ .trim();
72
+ if (!text || text.includes('NOTHING_DURABLE'))
73
+ return null;
74
+ writeSessionLog(opts.workDir, opts.sessionId, `# Session ${opts.sessionId.slice(0, 8)} — flushed ${new Date().toISOString()}\n\n${text.slice(0, 4000)}`);
75
+ return sessionLogPath(opts.workDir, opts.sessionId);
76
+ }
77
+ /** Append a curated journal entry (and thesis file on opens with a thesis). */
78
+ export function captureTradeEvent(event) {
79
+ if (!memoryEnabled())
80
+ return;
81
+ if (!event.address)
82
+ return;
83
+ const journal = tradingJournalPath(event.chain, event.address);
84
+ const amount = event.amountUsd != null ? ` $${event.amountUsd.toFixed(2)}` : '';
85
+ const pnl = event.pnlUsd != null ? ` · P&L ${event.pnlUsd >= 0 ? '+' : ''}$${event.pnlUsd.toFixed(2)}` : '';
86
+ const ref = event.ref ? ` · ref ${event.ref}` : '';
87
+ const heading = event.kind === 'close' ? 'Closed positions' : event.kind === 'bet' ? 'Bets' : 'Open positions';
88
+ appendUnderHeading(journal, heading, `${event.kind.toUpperCase()} ${event.asset}${amount}${pnl}${ref}`);
89
+ if (event.thesis && event.kind !== 'close') {
90
+ appendUnderHeading(thesisPath(event.chain, event.address, event.asset), 'Thesis', `${event.thesis.trim().slice(0, 600)}${ref}`);
91
+ }
92
+ if (event.kind === 'close' && event.pnlUsd != null) {
93
+ appendUnderHeading(thesisPath(event.chain, event.address, event.asset), 'Outcomes', `closed${amount}${pnl}${ref}`);
94
+ }
95
+ }
@@ -0,0 +1,24 @@
1
+ /**
2
+ * /dream — consolidation. Distills accumulated session logs into the
3
+ * curated workspace MEMORY.md (deduplicated, organized), then archives
4
+ * the consumed logs. Auto-gated: runs only when enough time and sessions
5
+ * have accumulated, with a cross-process lock so concurrent sessions
6
+ * can't double-dream.
7
+ */
8
+ import type { ModelClient } from '../agent/llm.js';
9
+ export declare const DREAM_MIN_HOURS = 4;
10
+ export declare const DREAM_MIN_SESSIONS = 3;
11
+ export declare function dreamGatesPass(workDir: string, now?: number): boolean;
12
+ export interface DreamResult {
13
+ consolidated: boolean;
14
+ logsConsumed: number;
15
+ reason?: string;
16
+ }
17
+ export declare function runDream(opts: {
18
+ client: ModelClient;
19
+ model: string;
20
+ workDir: string;
21
+ signal?: AbortSignal;
22
+ /** Skip the time/count gates (explicit /dream command). */
23
+ force?: boolean;
24
+ }): Promise<DreamResult>;
@@ -0,0 +1,147 @@
1
+ /**
2
+ * /dream — consolidation. Distills accumulated session logs into the
3
+ * curated workspace MEMORY.md (deduplicated, organized), then archives
4
+ * the consumed logs. Auto-gated: runs only when enough time and sessions
5
+ * have accumulated, with a cross-process lock so concurrent sessions
6
+ * can't double-dream.
7
+ */
8
+ import fs from 'node:fs';
9
+ import path from 'node:path';
10
+ import { recordUsage } from '../stats/tracker.js';
11
+ import { estimateCost } from '../pricing.js';
12
+ import { memoryEnabled, sessionLogsDir, workspaceDir, workspaceMemoryPath } from './store.js';
13
+ export const DREAM_MIN_HOURS = 4;
14
+ export const DREAM_MIN_SESSIONS = 3;
15
+ const LOCK_STALE_MS = 3600_000;
16
+ function lockPath(workDir) {
17
+ return path.join(workspaceDir(workDir), 'dream.lock');
18
+ }
19
+ function lastDreamPath(workDir) {
20
+ return path.join(workspaceDir(workDir), '.last-dream');
21
+ }
22
+ export function dreamGatesPass(workDir, now = Date.now()) {
23
+ if (!memoryEnabled())
24
+ return false;
25
+ let logs = [];
26
+ try {
27
+ logs = fs.readdirSync(sessionLogsDir(workDir)).filter(f => f.endsWith('.md'));
28
+ }
29
+ catch {
30
+ return false;
31
+ }
32
+ if (logs.length < DREAM_MIN_SESSIONS)
33
+ return false;
34
+ try {
35
+ const last = Number(fs.readFileSync(lastDreamPath(workDir), 'utf-8'));
36
+ if (Number.isFinite(last) && now - last < DREAM_MIN_HOURS * 3600_000)
37
+ return false;
38
+ }
39
+ catch { /* never dreamed */ }
40
+ return true;
41
+ }
42
+ function acquireLock(workDir) {
43
+ const p = lockPath(workDir);
44
+ try {
45
+ const stat = fs.statSync(p);
46
+ if (Date.now() - stat.mtimeMs < LOCK_STALE_MS)
47
+ return false; // held
48
+ fs.unlinkSync(p); // stale — reclaim
49
+ }
50
+ catch { /* no lock */ }
51
+ try {
52
+ fs.mkdirSync(path.dirname(p), { recursive: true });
53
+ fs.writeFileSync(p, String(process.pid), { flag: 'wx' });
54
+ return true;
55
+ }
56
+ catch {
57
+ return false;
58
+ }
59
+ }
60
+ function releaseLock(workDir) {
61
+ try {
62
+ fs.unlinkSync(lockPath(workDir));
63
+ }
64
+ catch { /* already gone */ }
65
+ }
66
+ const DREAM_PROMPT = (curated, logs) => `You are consolidating an agent's memory. Below is the CURATED long-term memory
67
+ file followed by accumulated raw session logs. Produce the NEW COMPLETE curated
68
+ memory file: merge durable knowledge from the logs into the curated content,
69
+ deduplicate aggressively, drop stale/superseded observations, keep it organized
70
+ under ## headings, and stay under 6000 characters. Output ONLY the new file
71
+ content (markdown, starting with a # title).
72
+
73
+ === CURATED MEMORY ===
74
+ ${curated || '(empty)'}
75
+
76
+ === SESSION LOGS ===
77
+ ${logs}`;
78
+ export async function runDream(opts) {
79
+ if (!memoryEnabled())
80
+ return { consolidated: false, logsConsumed: 0, reason: 'memory disabled' };
81
+ if (!opts.force && !dreamGatesPass(opts.workDir)) {
82
+ return { consolidated: false, logsConsumed: 0, reason: 'gates not met (needs ≥3 session logs and ≥4h since last dream)' };
83
+ }
84
+ if (!acquireLock(opts.workDir)) {
85
+ return { consolidated: false, logsConsumed: 0, reason: 'another session is consolidating' };
86
+ }
87
+ try {
88
+ const dir = sessionLogsDir(opts.workDir);
89
+ let files = [];
90
+ try {
91
+ files = fs.readdirSync(dir).filter(f => f.endsWith('.md')).sort();
92
+ }
93
+ catch { /* none */ }
94
+ if (files.length === 0)
95
+ return { consolidated: false, logsConsumed: 0, reason: 'no session logs' };
96
+ let curated = '';
97
+ try {
98
+ curated = fs.readFileSync(workspaceMemoryPath(opts.workDir), 'utf-8');
99
+ }
100
+ catch { /* fresh */ }
101
+ const logs = files
102
+ .map(f => {
103
+ try {
104
+ return `--- ${f} ---\n${fs.readFileSync(path.join(dir, f), 'utf-8').slice(0, 4000)}`;
105
+ }
106
+ catch {
107
+ return '';
108
+ }
109
+ })
110
+ .filter(Boolean)
111
+ .join('\n\n')
112
+ .slice(0, 40_000);
113
+ const { content, usage } = await opts.client.complete({
114
+ model: opts.model,
115
+ messages: [{ role: 'user', content: DREAM_PROMPT(curated, logs) }],
116
+ max_tokens: 2048,
117
+ stream: true,
118
+ }, opts.signal ?? new AbortController().signal);
119
+ try {
120
+ recordUsage(opts.model, usage.inputTokens, usage.outputTokens, estimateCost(opts.model, usage.inputTokens, usage.outputTokens), 0);
121
+ }
122
+ catch { /* best-effort */ }
123
+ const newMemory = content
124
+ .filter((p) => p.type === 'text')
125
+ .map(p => p.text)
126
+ .join('\n')
127
+ .trim();
128
+ if (!newMemory.startsWith('#')) {
129
+ return { consolidated: false, logsConsumed: 0, reason: 'consolidation produced no usable file' };
130
+ }
131
+ fs.writeFileSync(workspaceMemoryPath(opts.workDir), newMemory.slice(0, 12_000) + '\n');
132
+ // Archive consumed logs (kept for forensics, out of the search path).
133
+ const archive = path.join(dir, 'archived');
134
+ fs.mkdirSync(archive, { recursive: true });
135
+ for (const f of files) {
136
+ try {
137
+ fs.renameSync(path.join(dir, f), path.join(archive, f));
138
+ }
139
+ catch { /* best-effort */ }
140
+ }
141
+ fs.writeFileSync(lastDreamPath(opts.workDir), String(Date.now()));
142
+ return { consolidated: true, logsConsumed: files.length };
143
+ }
144
+ finally {
145
+ releaseLock(opts.workDir);
146
+ }
147
+ }
@@ -0,0 +1,29 @@
1
+ /**
2
+ * Document-memory search — pure-TS chunked TF scoring (no native deps).
3
+ *
4
+ * Chunks of ~1600 chars with 320 overlap; term-frequency scoring reusing
5
+ * the session-search tokenizer; TEMPORAL DECAY applies ONLY to session-log
6
+ * chunks (half-life 7 days) — curated global/workspace/trading files are
7
+ * long-term knowledge and never decay. Old session hits carry a staleness
8
+ * note so the model verifies before trusting. An mtime-keyed cache keeps
9
+ * re-index cost at zero for unchanged files.
10
+ */
11
+ import { type MemoryFileRef } from './store.js';
12
+ export declare const CHUNK_CHARS = 1600;
13
+ export declare const CHUNK_OVERLAP = 320;
14
+ export declare const SESSION_HALF_LIFE_DAYS = 7;
15
+ export interface MemoryHit {
16
+ file: string;
17
+ scope: MemoryFileRef['scope'];
18
+ snippet: string;
19
+ score: number;
20
+ /** Present on old session hits — surfaced verbatim to the model. */
21
+ stalenessNote?: string;
22
+ }
23
+ export declare function resetMemoryIndexCache(): void;
24
+ export declare function searchMemory(query: string, workDir: string, opts?: {
25
+ limit?: number;
26
+ minScore?: number;
27
+ }): MemoryHit[];
28
+ /** Compact context block for prompt injection; ~1.5k-token budget. */
29
+ export declare function formatMemoryContext(hits: MemoryHit[], budgetChars?: number): string;
@@ -0,0 +1,144 @@
1
+ /**
2
+ * Document-memory search — pure-TS chunked TF scoring (no native deps).
3
+ *
4
+ * Chunks of ~1600 chars with 320 overlap; term-frequency scoring reusing
5
+ * the session-search tokenizer; TEMPORAL DECAY applies ONLY to session-log
6
+ * chunks (half-life 7 days) — curated global/workspace/trading files are
7
+ * long-term knowledge and never decay. Old session hits carry a staleness
8
+ * note so the model verifies before trusting. An mtime-keyed cache keeps
9
+ * re-index cost at zero for unchanged files.
10
+ */
11
+ import fs from 'node:fs';
12
+ import { parseQuery, tokenize } from '../session/search.js';
13
+ import { listMemoryFiles, memoryEnabled } from './store.js';
14
+ export const CHUNK_CHARS = 1600;
15
+ export const CHUNK_OVERLAP = 320;
16
+ export const SESSION_HALF_LIFE_DAYS = 7;
17
+ const STALE_AFTER_DAYS = 3;
18
+ // mtime-keyed chunk cache per file.
19
+ const chunkCache = new Map();
20
+ export function resetMemoryIndexCache() {
21
+ chunkCache.clear();
22
+ }
23
+ function chunkFile(ref) {
24
+ const cached = chunkCache.get(ref.path);
25
+ if (cached && cached.mtimeMs === ref.mtimeMs)
26
+ return cached.chunks;
27
+ let content = '';
28
+ try {
29
+ content = fs.readFileSync(ref.path, 'utf-8');
30
+ }
31
+ catch {
32
+ return [];
33
+ }
34
+ const chunks = [];
35
+ for (let start = 0; start < content.length; start += CHUNK_CHARS - CHUNK_OVERLAP) {
36
+ const text = content.slice(start, start + CHUNK_CHARS);
37
+ if (!text.trim())
38
+ continue;
39
+ const tokens = new Map();
40
+ for (const tok of tokenize(text)) {
41
+ tokens.set(tok, (tokens.get(tok) ?? 0) + 1);
42
+ }
43
+ chunks.push({ file: ref.path, scope: ref.scope, mtimeMs: ref.mtimeMs, text, tokens });
44
+ if (text.length < CHUNK_CHARS)
45
+ break;
46
+ }
47
+ chunkCache.set(ref.path, { mtimeMs: ref.mtimeMs, chunks });
48
+ return chunks;
49
+ }
50
+ function ageDays(mtimeMs) {
51
+ return Math.max(0, (Date.now() - mtimeMs) / 86_400_000);
52
+ }
53
+ function scoreChunk(chunk, terms, phrases) {
54
+ let score = 0;
55
+ for (const term of terms) {
56
+ const tf = chunk.tokens.get(term) ?? 0;
57
+ if (tf > 0)
58
+ score += 1 + Math.log(1 + tf);
59
+ }
60
+ const lower = chunk.text.toLowerCase();
61
+ for (const phrase of phrases) {
62
+ if (lower.includes(phrase.toLowerCase()))
63
+ score += 3;
64
+ }
65
+ if (score === 0)
66
+ return 0;
67
+ if (chunk.scope === 'session') {
68
+ // Exponential half-life decay — ephemeral observations fade.
69
+ score *= Math.pow(0.5, ageDays(chunk.mtimeMs) / SESSION_HALF_LIFE_DAYS);
70
+ }
71
+ return score;
72
+ }
73
+ function snippetAround(text, terms, maxLen = 280) {
74
+ const lower = text.toLowerCase();
75
+ let at = -1;
76
+ for (const term of terms) {
77
+ at = lower.indexOf(term);
78
+ if (at !== -1)
79
+ break;
80
+ }
81
+ if (at === -1)
82
+ at = 0;
83
+ const start = Math.max(0, at - Math.floor(maxLen / 3));
84
+ const cut = text.slice(start, start + maxLen).trim();
85
+ return `${start > 0 ? '…' : ''}${cut}${start + maxLen < text.length ? '…' : ''}`;
86
+ }
87
+ export function searchMemory(query, workDir, opts = {}) {
88
+ if (!memoryEnabled())
89
+ return [];
90
+ const { terms, phrases } = parseQuery(query);
91
+ if (terms.length === 0 && phrases.length === 0)
92
+ return [];
93
+ const limit = opts.limit ?? 6;
94
+ const minScore = opts.minScore ?? 0.5;
95
+ const hits = [];
96
+ for (const ref of listMemoryFiles(workDir)) {
97
+ for (const chunk of chunkFile(ref)) {
98
+ const score = scoreChunk(chunk, terms, phrases);
99
+ if (score < minScore)
100
+ continue;
101
+ const hit = {
102
+ file: ref.path,
103
+ scope: ref.scope,
104
+ snippet: snippetAround(chunk.text, terms),
105
+ score,
106
+ };
107
+ if (ref.scope === 'session' && ageDays(ref.mtimeMs) > STALE_AFTER_DAYS) {
108
+ const days = Math.round(ageDays(ref.mtimeMs));
109
+ hit.stalenessNote = `note: this is a session memory from ~${days} days ago — verify current state before relying on it`;
110
+ }
111
+ hits.push(hit);
112
+ }
113
+ }
114
+ hits.sort((a, b) => b.score - a.score);
115
+ // One hit per file — chunk overlap otherwise floods the result set with
116
+ // near-duplicates from the same document.
117
+ const seen = new Set();
118
+ const deduped = [];
119
+ for (const hit of hits) {
120
+ if (seen.has(hit.file))
121
+ continue;
122
+ seen.add(hit.file);
123
+ deduped.push(hit);
124
+ if (deduped.length >= limit)
125
+ break;
126
+ }
127
+ return deduped;
128
+ }
129
+ /** Compact context block for prompt injection; ~1.5k-token budget. */
130
+ export function formatMemoryContext(hits, budgetChars = 6000) {
131
+ if (hits.length === 0)
132
+ return '';
133
+ const lines = ['<memory-recall>'];
134
+ let used = 0;
135
+ for (const hit of hits) {
136
+ const entry = `[${hit.scope}] ${hit.snippet}${hit.stalenessNote ? `\n (${hit.stalenessNote})` : ''}`;
137
+ if (used + entry.length > budgetChars)
138
+ break;
139
+ lines.push(entry);
140
+ used += entry.length;
141
+ }
142
+ lines.push('</memory-recall>');
143
+ return lines.length > 2 ? lines.join('\n') : '';
144
+ }
@@ -0,0 +1,50 @@
1
+ /**
2
+ * Document memory — curated markdown files with identity-keyed scoping.
3
+ *
4
+ * Layout under ~/.blockrun/memory/:
5
+ * MEMORY.md global, cross-project facts
6
+ * <slug>-<hash8>/MEMORY.md workspace-scoped (curated)
7
+ * <slug>-<hash8>/sessions/YYYY-MM-DD-*.md per-session logs (decaying)
8
+ * trading-<chain>-<addr8>/JOURNAL.md trade journal (curated)
9
+ * trading-<chain>-<addr8>/theses/<asset>.md one thesis file per asset
10
+ *
11
+ * Identity keying: a workspace is keyed by its git origin (org/repo form)
12
+ * so clones and worktrees of the same repo share memory; non-repos fall
13
+ * back to the directory path. Trading memory is keyed by WALLET ADDRESS —
14
+ * the journal follows the money, not the directory.
15
+ *
16
+ * This subsystem is additive to the Brain entity graph (src/brain/): the
17
+ * graph answers "what do I know about entity X", documents answer "what
18
+ * was my SOL thesis" / "what did we do last week". MemoryRecall facades
19
+ * both. Kill switch: FRANKLIN_MEMORY=0.
20
+ */
21
+ export declare function memoryEnabled(): boolean;
22
+ export declare function memoryRoot(): string;
23
+ export declare function globalMemoryPath(): string;
24
+ /** org/repo from the git origin remote, or null outside a repo. */
25
+ export declare function repoIdentity(workDir: string): string | null;
26
+ export declare function workspaceKey(workDir: string): {
27
+ slug: string;
28
+ hash8: string;
29
+ };
30
+ export declare function workspaceDir(workDir: string): string;
31
+ export declare function workspaceMemoryPath(workDir: string): string;
32
+ export declare function sessionLogsDir(workDir: string): string;
33
+ export declare function tradingDir(chain: string, address: string): string;
34
+ export declare function tradingJournalPath(chain: string, address: string): string;
35
+ export declare function thesisPath(chain: string, address: string, asset: string): string;
36
+ /**
37
+ * Append a note under a markdown heading, creating file/heading as needed.
38
+ * Used by /remember and the trading capture.
39
+ */
40
+ export declare function appendUnderHeading(filePath: string, heading: string, note: string): void;
41
+ /** Dated session log path for today. */
42
+ export declare function sessionLogPath(workDir: string, sessionId: string): string;
43
+ export declare function writeSessionLog(workDir: string, sessionId: string, content: string): void;
44
+ export interface MemoryFileRef {
45
+ path: string;
46
+ /** Curated files never decay; session logs do. */
47
+ scope: 'global' | 'workspace' | 'trading' | 'session';
48
+ mtimeMs: number;
49
+ }
50
+ export declare function listMemoryFiles(workDir: string): MemoryFileRef[];