renor-engine 1.1.0 → 1.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (39) hide show
  1. package/README.md +7 -2
  2. package/dist/.tsbuildinfo +1 -1
  3. package/dist/cli.js +26 -0
  4. package/dist/eval/indexSnapshots.js +1 -0
  5. package/dist/evidence/ollamaChat.js +1 -1
  6. package/dist/extraction/jevDecisionModel.js +307 -0
  7. package/dist/extraction/secretGuard.js +7 -3
  8. package/dist/learning/cli.js +113 -0
  9. package/dist/learning/schema.js +144 -0
  10. package/dist/learning/settings.js +45 -0
  11. package/dist/learning/store.js +267 -0
  12. package/dist/learning/tap.js +401 -0
  13. package/dist/memory/dreamer/adjudicate.js +215 -0
  14. package/dist/memory/dreamer/apply.js +120 -0
  15. package/dist/memory/dreamer/budget.js +64 -0
  16. package/dist/memory/dreamer/candidates.js +149 -0
  17. package/dist/memory/dreamer/collection.js +104 -0
  18. package/dist/memory/dreamer/dreamer.js +352 -0
  19. package/dist/memory/dreamer/review.js +111 -0
  20. package/dist/memory/factConflicts.js +2 -0
  21. package/dist/memory/lifecycle.js +28 -5
  22. package/dist/memory/writer.js +3 -2
  23. package/dist/mvp/agentMemory.js +3 -0
  24. package/dist/mvp/cli.js +11 -0
  25. package/dist/mvp/config.js +4 -0
  26. package/dist/mvp/exportAll.js +19 -0
  27. package/dist/mvp/server.js +118 -10
  28. package/dist/retrieval/orchestrator.js +69 -16
  29. package/dist/retrieval/rankingTrace.js +184 -0
  30. package/dist/sharing/cli.js +181 -0
  31. package/dist/sharing/examples.js +136 -0
  32. package/dist/sharing/fields.js +225 -0
  33. package/dist/sharing/loop.js +80 -0
  34. package/dist/sharing/project.js +327 -0
  35. package/dist/sharing/send.js +466 -0
  36. package/dist/sharing/state.js +222 -0
  37. package/dist/sharing/wording.js +48 -0
  38. package/package.json +1 -1
  39. package/dist/BUILD.json +0 -6
package/dist/cli.js CHANGED
@@ -35,6 +35,7 @@ const hashEmbedding_1 = require("./eval/hashEmbedding");
35
35
  const parser_1 = require("./conversation/parser");
36
36
  const writer_1 = require("./conversation/writer");
37
37
  const sessionRouter_1 = require("./router/sessionRouter");
38
+ const cli_1 = require("./sharing/cli");
38
39
  const digests_1 = require("./digests/digests");
39
40
  const buildIdentity_1 = require("./buildIdentity");
40
41
  /**
@@ -449,6 +450,31 @@ program
449
450
  process.exit(1);
450
451
  }
451
452
  });
453
+ program
454
+ .command("telemetry <action> [argument]")
455
+ .description("Choose whether to share anonymous signals or training data with Renor (off by default): status | signals | data | off | delete | preview [level] | send | fields [level]")
456
+ .option("--yes", "do not ask: you have read the words shown and confirm you are 18 or older")
457
+ .option("--local", "delete: also empty the local learning log")
458
+ .option("--dir <path>", "the sharing folder (default: RENOR_SHARING_DIR, else ~/.config/renor)")
459
+ .option("--memory-dir <path>", "the memory folder whose learning log is read (default: MVP_MEMORY_DIR)")
460
+ .action(async (action, argument, opts) => {
461
+ const readline = await import("node:readline");
462
+ const code = await (0, cli_1.runTelemetry)(action, argument, opts, {
463
+ out: (line) => process.stdout.write(`${line}\n`),
464
+ err: (line) => process.stderr.write(`${line}\n`),
465
+ env: process.env,
466
+ ask: (question) => {
467
+ if (!process.stdin.isTTY)
468
+ return Promise.resolve(null);
469
+ const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
470
+ return new Promise((resolve) => rl.question(question, (answer) => {
471
+ rl.close();
472
+ resolve(/^y(es)?$/i.test(answer.trim()));
473
+ }));
474
+ },
475
+ });
476
+ process.exit(code);
477
+ });
452
478
  program
453
479
  .command("log-conversation")
454
480
  .description("Log a Claude Code session to Obsidian vault (invoked by Stop hook)")
@@ -131,6 +131,7 @@ exports.READ_PATH_ONLY = [
131
131
  'src/retrieval/ledgerLiveness.ts',
132
132
  'src/retrieval/ledgerPresentation.ts',
133
133
  'src/retrieval/plainWording.ts',
134
+ 'src/retrieval/rankingTrace.ts', // orchestrator records search-time learning diagnostics; tracing is inert while index runs
134
135
  'src/retrieval/semantic.ts',
135
136
  ];
136
137
  /**
@@ -37,7 +37,7 @@ function createOllamaChat(opts) {
37
37
  try {
38
38
  const resp = await fetch(`${baseUrl}/chat/completions`, {
39
39
  method: 'POST',
40
- headers: { Authorization: `Bearer ${key}`, 'Content-Type': 'application/json' },
40
+ headers: { Authorization: `Bearer ${key}`, 'Content-Type': 'application/json', ...opts.headers },
41
41
  body,
42
42
  signal: controller.signal,
43
43
  });
@@ -0,0 +1,307 @@
1
+ "use strict";
2
+ var __importDefault = (this && this.__importDefault) || function (mod) {
3
+ return (mod && mod.__esModule) ? mod : { "default": mod };
4
+ };
5
+ Object.defineProperty(exports, "__esModule", { value: true });
6
+ exports.JevDecisionModel = exports.JEV_INPUT_USD_PER_MTOK = exports.JEV_COOLDOWN_MS = exports.JEV_TIMEOUT_MS = exports.JEV_STORE_MIN = exports.JEV_MODEL = exports.JEV_BASE_URL = void 0;
7
+ exports.resolveJevOptin = resolveJevOptin;
8
+ exports.readJevKey = readJevKey;
9
+ exports.jevDecisionLogPath = jevDecisionLogPath;
10
+ exports.jevDecisionLog = jevDecisionLog;
11
+ exports.saveDecisionModel = saveDecisionModel;
12
+ /**
13
+ * Jev (TypeSafe System One) behind the DecisionModel seam, for the save path of ONE opted-in workspace.
14
+ *
15
+ * Off unless the workspace's own env file says so (owner decision, 21 Oct 2026: "your own workspace only, now"):
16
+ *
17
+ * RENOR_JEV_OPTIN=<workspace slug> must equal MVP_INSTANCE_ID, so an env file copied to another workspace stays off
18
+ * RENOR_JEV_KEY_FILE=<path> the TypeSafe key, by its path (a file, so the env file never holds the secret)
19
+ *
20
+ * Both are needed, and so is MVP_MEMORY_DIR (every decision is recorded there, so a decision that cannot be recorded is not made).
21
+ * Anything else, or a setting that does not parse, is off with one stderr line naming the setting, never a value.
22
+ *
23
+ * What it does, once per text about to be stored, in one request (the two questions are independent):
24
+ *
25
+ * sensitivity a credential or a personal identifier. The scanner (secretGuard.ts) has already answered and a scanner
26
+ * `sensitive` stays final; this adds a second opinion. `store` is allowed only at P(store) >= 0.7, the rule
27
+ * that caught 243/243 planted items at 2/200 false blocks (LEDGER block F). A block refuses the save, as the
28
+ * scanner does, and nothing is redacted.
29
+ * capture gate whether the text is worth saving. RECORDED ONLY: it never drops a save, because a wrong "not worth it"
30
+ * loses a memory silently and the scout measured 93% recall, not 100%.
31
+ *
32
+ * What it never does: it reads nothing, so no read path reaches it; it sends no text that is already stored; it never owns a
33
+ * dedupe or supersede verdict (dedupe_adjudication is the local rules, byte for byte: Jev made 16/55 wrong supersedes on real
34
+ * pairs); and it never blocks or loses a save for any reason of its own: a timeout, an error, a bad reply or a cool-down all
35
+ * fall back to today's local rules (the scanner has already run). Every call is recorded as numbers and labels, never text.
36
+ */
37
+ const node_fs_1 = __importDefault(require("node:fs"));
38
+ const node_path_1 = __importDefault(require("node:path"));
39
+ const decision_model_1 = require("./decision-model");
40
+ exports.JEV_BASE_URL = 'https://api.typesafe.ai';
41
+ exports.JEV_MODEL = 'jev-latest';
42
+ /** P(store) below this blocks (LEDGER block F: 243/243 planted items caught at 2/200 false blocks). */
43
+ exports.JEV_STORE_MIN = 0.7;
44
+ /** A save never waits longer than this for Jev (the scout measured p95 about 0.3 s). */
45
+ exports.JEV_TIMEOUT_MS = 1500;
46
+ /** After a failed call, saves skip Jev for this long, so an outage costs one timeout, not one per save. */
47
+ exports.JEV_COOLDOWN_MS = 30_000;
48
+ /** $0.042 per million input tokens (COST-MODEL lane-Jev arm; output is free). */
49
+ exports.JEV_INPUT_USD_PER_MTOK = 0.042;
50
+ const SENSITIVITY_QUESTION = {
51
+ type: 'choice',
52
+ instructions: 'Decide how to persist this text. "block" = do not store it at all (it contains a '
53
+ + 'secret credential: API key, token, password, private key, or live account '
54
+ + 'identifier). "redact" = the text is useful but contains personal identifiers '
55
+ + '(phone, email, card, government id) that must be masked before storing. '
56
+ + '"store" = no secrets or personal identifiers; safe to store verbatim.',
57
+ criteria: {
58
+ store: 'No secrets or personal identifiers; safe to store verbatim.',
59
+ block: 'Contains a secret credential; must not be stored at all.',
60
+ redact: 'Useful text containing personal identifiers that must be masked first.',
61
+ },
62
+ };
63
+ const CAPTURE_QUESTION = {
64
+ type: 'choice',
65
+ instructions: 'What durable information about the user or their world does this user message state?',
66
+ criteria: {
67
+ none: 'Nothing durable: questions, small talk, opinions, transient requests.',
68
+ fact: 'A stable attribute or circumstance.',
69
+ event: 'Something that happened or is scheduled.',
70
+ preference: 'A liking, dislike, habit or standing choice.',
71
+ commitment: 'A plan or promise for future action.',
72
+ sensitive: 'A credential or private identifier.',
73
+ },
74
+ };
75
+ function asChoice(answer) {
76
+ const a = answer;
77
+ return a && a.type === 'choice' && typeof a.choice === 'string' ? a : null;
78
+ }
79
+ function probability(answer, label) {
80
+ const p = answer.probabilities?.[label];
81
+ if (typeof p === 'number' && p >= 0 && p <= 1)
82
+ return p;
83
+ // No distribution in the reply: the chosen label gets its confidence, every other label gets nothing.
84
+ return answer.choice === label ? Math.max(0, Math.min(1, answer.confidence ?? 0)) : 0;
85
+ }
86
+ class JevFallback extends Error {
87
+ reason;
88
+ status;
89
+ constructor(reason, status) {
90
+ super(reason);
91
+ this.reason = reason;
92
+ this.status = status;
93
+ }
94
+ }
95
+ class JevDecisionModel {
96
+ opts;
97
+ local;
98
+ baseUrl;
99
+ timeoutMs;
100
+ cooldownMs;
101
+ now;
102
+ coolUntil = 0;
103
+ constructor(opts) {
104
+ this.opts = opts;
105
+ this.local = opts.local ?? (0, decision_model_1.defaultDecisionModel)();
106
+ this.baseUrl = (opts.baseUrl ?? exports.JEV_BASE_URL).replace(/\/+$/, '');
107
+ this.timeoutMs = opts.timeoutMs ?? exports.JEV_TIMEOUT_MS;
108
+ this.cooldownMs = opts.cooldownMs ?? exports.JEV_COOLDOWN_MS;
109
+ this.now = opts.now ?? Date.now;
110
+ }
111
+ /** Never throws. Dedupe and note classification are the local rules, whatever Jev would say. */
112
+ async decide(request) {
113
+ // Resolve the local decision before branching so every fallback below has the concrete
114
+ // DecisionResult promised by this adapter, rather than its nested asynchronous form.
115
+ const fallback = await this.local.decide(request);
116
+ if (request.task !== 'capture_gate')
117
+ return fallback;
118
+ const text = request.text;
119
+ if (!text.trim())
120
+ return fallback;
121
+ const started = this.now();
122
+ if (started < this.coolUntil) {
123
+ this.record({ outcome: 'fallback', reason: 'cooldown', latencyMs: 0, inputTokens: 0, chars: text.length });
124
+ return fallback;
125
+ }
126
+ // A decision that cannot be recorded is not made: no text leaves the machine without its local record.
127
+ if (!this.canRecord())
128
+ return fallback;
129
+ try {
130
+ const call = await this.call(text);
131
+ const sensitivity = asChoice(call.answers.sensitivity);
132
+ const capture = asChoice(call.answers.capture_gate);
133
+ if (!sensitivity)
134
+ throw new JevFallback('bad_reply');
135
+ const pStore = probability(sensitivity, 'store');
136
+ const blocked = pStore < exports.JEV_STORE_MIN;
137
+ const inputTokens = call.inputTokens;
138
+ const costUSDCents = (inputTokens * exports.JEV_INPUT_USD_PER_MTOK) / 1_000_000 * 100;
139
+ const latencyMs = this.now() - started;
140
+ this.record({
141
+ outcome: 'applied', latencyMs, inputTokens, costUSDCents, chars: text.length,
142
+ sensitivity: { choice: sensitivity.choice, pStore, confidence: sensitivity.confidence ?? 0, blocked },
143
+ ...(capture ? { capture: { choice: capture.choice, pDurable: 1 - probability(capture, 'none'), confidence: capture.confidence ?? 0 } } : {}),
144
+ });
145
+ if (!blocked)
146
+ return fallback;
147
+ // Refused like a scanner hit: the guard reads `sensitive` and refuses the save. `redact` is a refusal too (nothing is altered).
148
+ const verdict = { task: 'capture_gate', decision: 'sensitive', confidence: 1 - pStore, latencyMs, costUSDCents };
149
+ return verdict;
150
+ }
151
+ catch (err) {
152
+ this.coolUntil = this.now() + this.cooldownMs;
153
+ const known = err instanceof JevFallback ? err : null;
154
+ this.record({
155
+ outcome: 'fallback', reason: known?.reason ?? 'error', ...(known?.status !== undefined ? { status: known.status } : {}),
156
+ latencyMs: this.now() - started, inputTokens: 0, chars: text.length,
157
+ });
158
+ return fallback;
159
+ }
160
+ }
161
+ async call(text) {
162
+ let res;
163
+ try {
164
+ res = await (this.opts.fetchImpl ?? fetch)(`${this.baseUrl}/v1/systemone`, {
165
+ method: 'POST',
166
+ headers: { 'content-type': 'application/json', authorization: `Bearer ${this.opts.apiKey}` },
167
+ body: JSON.stringify({ model: exports.JEV_MODEL, state: text, questions: { sensitivity: SENSITIVITY_QUESTION, capture_gate: CAPTURE_QUESTION } }),
168
+ signal: AbortSignal.timeout(this.timeoutMs),
169
+ });
170
+ }
171
+ catch (err) {
172
+ const name = err instanceof Error ? err.name : '';
173
+ throw new JevFallback(name === 'TimeoutError' || name === 'AbortError' ? 'timeout' : 'error');
174
+ }
175
+ if (!res.ok)
176
+ throw new JevFallback('http', res.status);
177
+ let json;
178
+ try {
179
+ json = (await res.json());
180
+ }
181
+ catch (err) {
182
+ const name = err instanceof Error ? err.name : '';
183
+ throw new JevFallback(name === 'TimeoutError' || name === 'AbortError' ? 'timeout' : 'bad_reply');
184
+ }
185
+ if (!json || typeof json.answers !== 'object' || json.answers === null)
186
+ throw new JevFallback('bad_reply');
187
+ return { answers: json.answers, inputTokens: Number.isFinite(json.usage?.input_tokens) ? Number(json.usage?.input_tokens) : 0 };
188
+ }
189
+ canRecord() {
190
+ try {
191
+ return this.opts.canRecord() === true;
192
+ }
193
+ catch {
194
+ return false;
195
+ }
196
+ }
197
+ record(partial) {
198
+ try {
199
+ this.opts.record({
200
+ v: 1, at: new Date(this.now()).toISOString(), workspace: this.opts.workspace, task: 'save_screen', costUSDCents: 0, ...partial,
201
+ });
202
+ }
203
+ catch { /* a log that cannot be written never costs a save */ }
204
+ }
205
+ }
206
+ exports.JevDecisionModel = JevDecisionModel;
207
+ const toldOff = new Set();
208
+ /** null when the workspace has not opted in or the setting cannot be honoured; says why on stderr, never a value. */
209
+ function resolveJevOptin(env = process.env) {
210
+ const workspace = (env.RENOR_JEV_OPTIN ?? '').trim().toLowerCase();
211
+ if (workspace === '')
212
+ return null;
213
+ const off = (why) => {
214
+ if (!toldOff.has(why)) {
215
+ toldOff.add(why);
216
+ process.stderr.write(`[jev] RENOR_JEV_OPTIN is set but ${why}: the save screen stays off\n`);
217
+ }
218
+ return null;
219
+ };
220
+ if ((env.MVP_INSTANCE_ID ?? '').trim().toLowerCase() !== workspace)
221
+ return off('it does not name this workspace (MVP_INSTANCE_ID)');
222
+ const keyFile = (env.RENOR_JEV_KEY_FILE ?? '').trim();
223
+ if (!node_path_1.default.isAbsolute(keyFile))
224
+ return off('RENOR_JEV_KEY_FILE is not an absolute path');
225
+ const memoryDir = (env.MVP_MEMORY_DIR ?? '').trim();
226
+ if (!node_path_1.default.isAbsolute(memoryDir))
227
+ return off('MVP_MEMORY_DIR is not an absolute path, so decisions could not be recorded');
228
+ return { workspace, keyFile, memoryDir };
229
+ }
230
+ /** The key in the file: one token. Null (with one stderr line naming the path, never the content) when it cannot be used. */
231
+ function readJevKey(keyFile) {
232
+ try {
233
+ const st = node_fs_1.default.statSync(keyFile);
234
+ if (!st.isFile())
235
+ throw new Error('not a regular file');
236
+ // A service credential readable by anyone but its owner is not used (the contract: mode 0600, the tenant's account only).
237
+ if ((st.mode & 0o077) !== 0)
238
+ throw new Error('readable or writable by group or others; chmod 600 it');
239
+ if (typeof process.getuid === 'function' && st.uid !== process.getuid())
240
+ throw new Error('not owned by this account');
241
+ const key = node_fs_1.default.readFileSync(keyFile, 'utf8').trim();
242
+ if (key === '' || /\s/.test(key))
243
+ throw new Error('empty or not a single token');
244
+ return key;
245
+ }
246
+ catch (err) {
247
+ process.stderr.write(`[jev] the key file ${keyFile} cannot be used (${err instanceof Error ? err.message.replace(keyFile, 'it') : 'unreadable'}): the save screen stays off\n`);
248
+ return null;
249
+ }
250
+ }
251
+ /** Where a workspace's Jev decisions are kept: beside its index, which the walker, the watcher and release packing already skip. */
252
+ function jevDecisionLogPath(memoryDir) {
253
+ return node_path_1.default.join(node_path_1.default.resolve(memoryDir), '.memory-index', 'jev-decisions.jsonl');
254
+ }
255
+ /**
256
+ * One JSON line per call, owner-only. `ready` opens the log for append before any text is sent, so a log that cannot be
257
+ * written turns the screen off for that save (Jev is not asked; the local rules decide). Told once on stderr; never reaches the save.
258
+ */
259
+ function jevDecisionLog(memoryDir) {
260
+ const file = jevDecisionLogPath(memoryDir);
261
+ let told = false;
262
+ const tell = (err) => {
263
+ if (told)
264
+ return;
265
+ told = true;
266
+ process.stderr.write(`[jev] a decision could not be recorded (${err instanceof Error ? err.name : 'error'}): Jev is not asked, saves go on\n`);
267
+ };
268
+ return {
269
+ ready: () => {
270
+ try {
271
+ node_fs_1.default.mkdirSync(node_path_1.default.dirname(file), { recursive: true, mode: 0o700 });
272
+ node_fs_1.default.closeSync(node_fs_1.default.openSync(file, 'a', 0o600));
273
+ return true;
274
+ }
275
+ catch (err) {
276
+ tell(err);
277
+ return false;
278
+ }
279
+ },
280
+ write: entry => {
281
+ try {
282
+ node_fs_1.default.appendFileSync(file, `${JSON.stringify(entry)}\n`, { mode: 0o600 });
283
+ }
284
+ catch (err) {
285
+ tell(err);
286
+ }
287
+ },
288
+ };
289
+ }
290
+ let cached;
291
+ /**
292
+ * The model the save path uses, or null (the common case) when this workspace has not opted in. One instance per process, so
293
+ * its cool-down is shared by every save; rebuilt only when the settings change.
294
+ */
295
+ function saveDecisionModel(env = process.env) {
296
+ const optin = resolveJevOptin(env);
297
+ if (!optin)
298
+ return null;
299
+ const signature = `${optin.workspace}\0${optin.keyFile}\0${optin.memoryDir}`;
300
+ if (cached?.signature === signature)
301
+ return cached.model;
302
+ const key = readJevKey(optin.keyFile);
303
+ const log = jevDecisionLog(optin.memoryDir);
304
+ const model = key ? new JevDecisionModel({ workspace: optin.workspace, apiKey: key, record: log.write, canRecord: log.ready }) : null;
305
+ cached = { signature, model };
306
+ return model;
307
+ }
@@ -132,19 +132,23 @@ function refuseUnchecked(field, action) {
132
132
  /**
133
133
  * Throws SecretRefusedError when the guard is on and any of `texts` is sensitive; resolves otherwise.
134
134
  * It fails closed: if the check itself throws, the save is refused. Call it before the first write.
135
+ * `contentModel`, when a save path passes one, only adds a second opinion on the texts that are not `nameOnly`.
135
136
  * With the guard off it returns at once, so callers that must not add a step to the unguarded path
136
137
  * check `secretGuardEnabled()` first and skip the call.
137
138
  */
138
- async function assertStorable(texts, action = 'save') {
139
+ async function assertStorable(texts, action = 'save', contentModel = null) {
139
140
  if (!secretGuardEnabled())
140
141
  return;
141
142
  const model = new SecretGuardDecisionModel();
142
- for (const { field, text } of texts) {
143
+ // A second opinion on content only (jevDecisionModel.ts, one opted-in workspace's saves): the scanner still answers first
144
+ // and a scanner `sensitive` is final, because SecretGuardDecisionModel asks the inner model only about text it did not flag.
145
+ const withContentModel = contentModel ? new SecretGuardDecisionModel(contentModel) : model;
146
+ for (const { field, text, nameOnly } of texts) {
143
147
  if (text === undefined || text === '')
144
148
  continue;
145
149
  let verdict;
146
150
  try {
147
- verdict = await model.decide({ task: 'capture_gate', text });
151
+ verdict = await (nameOnly ? model : withContentModel).decide({ task: 'capture_gate', text });
148
152
  }
149
153
  catch (cause) {
150
154
  refuse(field, 'unavailable', action, cause);
@@ -0,0 +1,113 @@
1
+ "use strict";
2
+ var __importDefault = (this && this.__importDefault) || function (mod) {
3
+ return (mod && mod.__esModule) ? mod : { "default": mod };
4
+ };
5
+ Object.defineProperty(exports, "__esModule", { value: true });
6
+ exports.run = run;
7
+ const node_fs_1 = __importDefault(require("node:fs"));
8
+ const settings_1 = require("./settings");
9
+ const store_1 = require("./store");
10
+ /**
11
+ * Manage one memory folder's learning log: `status`, `export`, `prune` and `delete-all`. They work whether or not recording is
12
+ * on, so a log written before it was switched off can still be read or deleted, and they never create a log that does not exist.
13
+ *
14
+ * MVP_MEMORY_DIR=<memory folder> npx tsx src/learning/cli.ts status
15
+ * MVP_MEMORY_DIR=<memory folder> npx tsx src/learning/cli.ts export [--out <file>] (the file is written owner-only)
16
+ * MVP_MEMORY_DIR=<memory folder> npx tsx src/learning/cli.ts prune
17
+ * MVP_MEMORY_DIR=<memory folder> npx tsx src/learning/cli.ts delete-all --yes
18
+ *
19
+ * Stop a running server before deleting, as the data-deletion runbook does; a running server would otherwise keep its open
20
+ * handle to the file. The counts and the export never contain a key secret or a memory's text.
21
+ */
22
+ const USAGE = 'usage: learning-cli <status | export [--out <file>] | prune | delete-all --yes>';
23
+ function print(value) {
24
+ process.stdout.write(`${JSON.stringify(value, null, 2)}\n`);
25
+ }
26
+ function run(argv, env = process.env) {
27
+ const memoryDir = (env.MVP_MEMORY_DIR ?? '').trim();
28
+ if (memoryDir === '')
29
+ throw new Error('MVP_MEMORY_DIR is required: the memory folder whose learning log this manages');
30
+ const [command, ...rest] = argv;
31
+ const file = (0, settings_1.learningDbPath)(memoryDir);
32
+ const open = () => {
33
+ const log = store_1.LearningLog.open(file, { retentionDays: (0, settings_1.learningRetentionDays)(env), rawQueries: false, create: false });
34
+ if (log === null)
35
+ throw new Error(`no learning log at ${file}: nothing has been recorded there`);
36
+ return log;
37
+ };
38
+ switch (command) {
39
+ case 'status': {
40
+ const log = store_1.LearningLog.open(file, { retentionDays: (0, settings_1.learningRetentionDays)(env), rawQueries: false, create: false });
41
+ if (log === null) {
42
+ print({ present: false, file });
43
+ return;
44
+ }
45
+ try {
46
+ print({ present: true, file, retentionDays: (0, settings_1.learningRetentionDays)(env), counts: log.counts() });
47
+ }
48
+ finally {
49
+ log.close();
50
+ }
51
+ return;
52
+ }
53
+ case 'export': {
54
+ const out = rest[0] === '--out' ? rest[1] : undefined;
55
+ if (rest[0] === '--out' && (out === undefined || out === ''))
56
+ throw new Error(USAGE);
57
+ const log = open();
58
+ let text;
59
+ try {
60
+ text = `${JSON.stringify(log.exportLog(), null, 2)}\n`;
61
+ }
62
+ finally {
63
+ log.close();
64
+ }
65
+ if (out === undefined) {
66
+ process.stdout.write(text);
67
+ }
68
+ else {
69
+ node_fs_1.default.writeFileSync(out, text, { mode: 0o600 });
70
+ process.stderr.write(`wrote ${out}\n`);
71
+ }
72
+ return;
73
+ }
74
+ case 'prune': {
75
+ const log = open();
76
+ try {
77
+ print(log.prune());
78
+ }
79
+ finally {
80
+ log.close();
81
+ }
82
+ return;
83
+ }
84
+ case 'delete-all': {
85
+ if (rest[0] !== '--yes')
86
+ throw new Error('delete-all removes every recorded row and needs --yes');
87
+ const log = store_1.LearningLog.open(file, { retentionDays: (0, settings_1.learningRetentionDays)(env), rawQueries: false, create: false });
88
+ if (log === null) {
89
+ print({ deleted: false, file, reason: 'no learning log' });
90
+ return;
91
+ }
92
+ try {
93
+ log.deleteAll();
94
+ print({ deleted: true, file, counts: log.counts() });
95
+ }
96
+ finally {
97
+ log.close();
98
+ }
99
+ return;
100
+ }
101
+ default:
102
+ throw new Error(USAGE);
103
+ }
104
+ }
105
+ if (require.main === module) {
106
+ try {
107
+ run(process.argv.slice(2));
108
+ }
109
+ catch (err) {
110
+ process.stderr.write(`${err instanceof Error ? err.message : String(err)}\n`);
111
+ process.exitCode = 1;
112
+ }
113
+ }
@@ -0,0 +1,144 @@
1
+ "use strict";
2
+ Object.defineProperty(exports, "__esModule", { value: true });
3
+ exports.LEARNING_DDL = exports.LEARNING_TABLES = exports.TERM_COLUMNS = exports.OUTCOME_BASES = exports.OUTCOME_VALUES = exports.CITE_TARGETS = exports.OPERATIONS = exports.OPERATION_KINDS = exports.CANDIDATE_KINDS = exports.ACTORS = exports.SAVE_TOOLS = exports.WRITE_TOOLS = exports.RETRIEVAL_TOOLS = exports.RANKER_BASELINE = exports.LEARNING_SCHEMA_VERSION = exports.LEARNING_SCHEMA_NAME = void 0;
4
+ const rankingTrace_1 = require("../retrieval/rankingTrace");
5
+ /**
6
+ * The learning log's on-disk contract, version 2 (docs/learning/FEEDBACK-LOG.md is the prose version).
7
+ *
8
+ * The log holds identifiers, keyed hashes and numbers about what the agent retrieved, what it wrote, what it cited and what
9
+ * outcomes were reported. It never holds memory text, a subject or predicate in clear, a path in clear, a credential or a
10
+ * query in clear. The one exception is `query_text`, which exists only when RENOR_LEARNING_RAW_QUERY is on, and then only when
11
+ * the secret scanner does not flag the query (`query_redacted` says when it did).
12
+ *
13
+ * Every `*_key` column is a keyed hash (HMAC-SHA256, 128 bits) under a secret that is random per log and never exported:
14
+ * the same memory, query or session gets the same key within one log, and different keys in any other log.
15
+ *
16
+ * Version 2 adds, for every candidate the ranker scored or presented, its base score and one numeric column per additive term
17
+ * the ranker applied (`term_*`, from RANKING_TERMS), so that base + the terms is the score it ranked by and the weights can be
18
+ * refitted from the log. It also records the candidate's rank in the scored pool, its position in the presented window and
19
+ * whether the budget kept it. Version 1 was never released; a version 1 file is refused, not migrated.
20
+ */
21
+ exports.LEARNING_SCHEMA_NAME = 'renor-learning-log';
22
+ exports.LEARNING_SCHEMA_VERSION = 2;
23
+ /** The ranking procedure that ordered a reply. The shipped product ranking is `baseline`; a learned ranker writes its own name. */
24
+ exports.RANKER_BASELINE = 'baseline';
25
+ /** Tools whose successful replies are recorded as retrievals (one row each, with its candidates). */
26
+ exports.RETRIEVAL_TOOLS = ['get_context', 'search_memory', 'retrieve_memory'];
27
+ /** Tools whose successful calls are recorded as memory operations or, for the save tools, as explicit citations too. */
28
+ exports.WRITE_TOOLS = [
29
+ 'remember', 'save_memory', 'remember_note', 'retire_memory', 'restore_memory', 'delete_retired_memory', 'read_memory',
30
+ ];
31
+ exports.SAVE_TOOLS = ['remember', 'save_memory', 'remember_note'];
32
+ /** Who made the call: the agent over MCP, or the owner's dashboard (the platform acting for the owner). */
33
+ exports.ACTORS = ['agent', 'dashboard'];
34
+ /** What a candidate or an operation refers to. `unkeyed`: the reply named nothing a memory key can be made from. */
35
+ exports.CANDIDATE_KINDS = ['fact', 'note', 'unkeyed'];
36
+ exports.OPERATION_KINDS = ['fact', 'note', 'event', 'unkeyed'];
37
+ exports.OPERATIONS = ['create', 'supersede', 'delete', 'restore', 'erase', 'retrieve'];
38
+ exports.CITE_TARGETS = ['note', 'event', 'subject', 'unkeyed'];
39
+ exports.OUTCOME_VALUES = ['success', 'failure', 'partial', 'unknown'];
40
+ /**
41
+ * Where an outcome came from. `verifier` (a check that ran) and `user` (the owner said so) are observed. `proxy` is anything
42
+ * inferred from behaviour, such as "no correction followed"; it is stored with observed = 0 and is never a success by itself.
43
+ */
44
+ exports.OUTCOME_BASES = ['verifier', 'user', 'proxy'];
45
+ /** The column of each ranker term in `candidates`: `term_<name>`, in RANKING_TERMS order. */
46
+ exports.TERM_COLUMNS = rankingTrace_1.RANKING_TERMS.map(term => `term_${term}`);
47
+ /** The tables, in the order an export lists them. `meta` holds the schema name, its version, the creation instant and the key secret. */
48
+ exports.LEARNING_TABLES = ['retrievals', 'candidates', 'memory_ops', 'feedback', 'outcomes'];
49
+ const list = (values) => values.map(value => `'${value}'`).join(', ');
50
+ exports.LEARNING_DDL = `
51
+ CREATE TABLE IF NOT EXISTS meta (
52
+ key TEXT PRIMARY KEY,
53
+ value TEXT NOT NULL
54
+ ) WITHOUT ROWID;
55
+
56
+ CREATE TABLE IF NOT EXISTS retrievals (
57
+ id INTEGER PRIMARY KEY,
58
+ at INTEGER NOT NULL, -- unix ms
59
+ tool TEXT NOT NULL CHECK (tool IN (${list(exports.RETRIEVAL_TOOLS)})),
60
+ actor TEXT NOT NULL CHECK (actor IN (${list(exports.ACTORS)})),
61
+ session_key TEXT, -- keyed hash of the MCP session; NULL when the server keeps none
62
+ agent_key TEXT, -- keyed hash of the agent name the connection presented ('unnamed' when none)
63
+ query_key TEXT, -- keyed hash of the normalized query; NULL when the call had none
64
+ query_text TEXT, -- the raw query: RENOR_LEARNING_RAW_QUERY only, never when query_redacted = 1
65
+ query_redacted INTEGER NOT NULL DEFAULT 0 CHECK (query_redacted IN (0, 1)),
66
+ scope_key TEXT, -- keyed hash of the normalized scope ('global' when none was named)
67
+ retrieval TEXT, -- the reply's retrieval mode, when it names one
68
+ ranker TEXT NOT NULL, -- which procedure ordered the candidates (RANKER_BASELINE for the shipped one)
69
+ model TEXT, -- embedding model identity (<provider>:<model>:<dims>); NULL when keyword only
70
+ build TEXT, -- commit of the running build, NULL when unstamped
71
+ served INTEGER NOT NULL, -- candidates the reply served (rows in candidates with a rank)
72
+ ms REAL NOT NULL, -- wall time of the handler
73
+ reply_tokens INTEGER, -- o200k tokens of the whole reply, as the max_tokens budget counts them
74
+ relevant INTEGER CHECK (relevant IS NULL OR relevant IN (0, 1)), -- the engine's own verdict, when it judged
75
+ truncated INTEGER CHECK (truncated IS NULL OR truncated IN (0, 1)),
76
+ lean_items INTEGER NOT NULL DEFAULT 0 CHECK (lean_items IN (0, 1)) -- RENOR_CONTEXT_LEAN_ITEMS was on: no note paths in the reply
77
+ );
78
+
79
+ CREATE TABLE IF NOT EXISTS candidates (
80
+ id INTEGER PRIMARY KEY,
81
+ retrieval_id INTEGER NOT NULL REFERENCES retrievals(id) ON DELETE CASCADE,
82
+ rank INTEGER, -- 1-based position in the reply (facts first, then memories, as served); NULL when not served
83
+ kind TEXT NOT NULL CHECK (kind IN (${list(exports.CANDIDATE_KINDS)})),
84
+ memory_key TEXT, -- fact: scope + subject + predicate; note: the note path
85
+ subject_key TEXT, -- fact only: the subject within its scope (joins cites that name it, in that scope)
86
+ section_key TEXT, -- note only: the heading path inside the note, when there is one
87
+ score REAL, -- the score the candidate was ranked by: the reply's, or base + terms when not served
88
+ base REAL, -- the score before any term: a cosine, 0.3 for a graph hit, the fact lane's, 0 for a statement; NULL when untraced
89
+ ${exports.TERM_COLUMNS.map(column => `${column} REAL NOT NULL DEFAULT 0,`).join('\n ')}
90
+ pool_rank INTEGER, -- 1-based rank in the scored pool (score order, before the window cut); NULL when not scored
91
+ window_pos INTEGER, -- 1-based position in the order the reply presents its hits, before any budget cut; NULL when not presented
92
+ budget_kept INTEGER CHECK (budget_kept IS NULL OR budget_kept IN (0, 1)), -- 1 kept by max_tokens, 0 cut; NULL when the read had no budget
93
+ reason TEXT, -- the lane that matched (fact, fts, semantic, semantic+content+recency, ...)
94
+ matched INTEGER CHECK (matched IS NULL OR matched IN (0, 1)), -- 0: the reply marked it as not matched
95
+ current INTEGER CHECK (current IS NULL OR current IN (0, 1)) -- retrieve_memory: 0 for a superseded value
96
+ );
97
+
98
+ CREATE TABLE IF NOT EXISTS memory_ops (
99
+ id INTEGER PRIMARY KEY,
100
+ at INTEGER NOT NULL,
101
+ actor TEXT NOT NULL CHECK (actor IN (${list(exports.ACTORS)})),
102
+ session_key TEXT,
103
+ agent_key TEXT,
104
+ tool TEXT NOT NULL CHECK (tool IN (${list(exports.WRITE_TOOLS)})),
105
+ op TEXT NOT NULL CHECK (op IN (${list(exports.OPERATIONS)})),
106
+ kind TEXT NOT NULL CHECK (kind IN (${list(exports.OPERATION_KINDS)})),
107
+ memory_key TEXT,
108
+ subject_key TEXT,
109
+ replaced_key TEXT, -- supersede only: the memory identity whose value the new save replaces
110
+ ms REAL NOT NULL
111
+ );
112
+
113
+ CREATE TABLE IF NOT EXISTS feedback (
114
+ id INTEGER PRIMARY KEY,
115
+ at INTEGER NOT NULL,
116
+ actor TEXT NOT NULL CHECK (actor IN (${list(exports.ACTORS)})),
117
+ session_key TEXT,
118
+ agent_key TEXT,
119
+ tool TEXT NOT NULL CHECK (tool IN (${list(exports.SAVE_TOOLS)})),
120
+ kind TEXT NOT NULL CHECK (kind IN ('cite')), -- the explicit cites argument of a save
121
+ target TEXT NOT NULL CHECK (target IN (${list(exports.CITE_TARGETS)})),
122
+ memory_key TEXT,
123
+ subject_key TEXT,
124
+ observed INTEGER NOT NULL DEFAULT 1 CHECK (observed IN (0, 1))
125
+ );
126
+
127
+ CREATE TABLE IF NOT EXISTS outcomes (
128
+ id INTEGER PRIMARY KEY,
129
+ at INTEGER NOT NULL,
130
+ session_key TEXT,
131
+ task_key TEXT, -- keyed hash of an opaque task reference the caller supplies; NULL when none
132
+ outcome TEXT NOT NULL CHECK (outcome IN (${list(exports.OUTCOME_VALUES)})),
133
+ basis TEXT NOT NULL CHECK (basis IN (${list(exports.OUTCOME_BASES)})),
134
+ observed INTEGER NOT NULL CHECK (observed IN (0, 1)) -- 1 unless basis = proxy
135
+ );
136
+
137
+ CREATE INDEX IF NOT EXISTS retrievals_at ON retrievals (at);
138
+ CREATE INDEX IF NOT EXISTS candidates_retrieval ON candidates (retrieval_id, rank);
139
+ CREATE INDEX IF NOT EXISTS candidates_memory ON candidates (memory_key);
140
+ CREATE INDEX IF NOT EXISTS memory_ops_at ON memory_ops (at);
141
+ CREATE INDEX IF NOT EXISTS memory_ops_memory ON memory_ops (memory_key);
142
+ CREATE INDEX IF NOT EXISTS feedback_at ON feedback (at);
143
+ CREATE INDEX IF NOT EXISTS outcomes_at ON outcomes (at);
144
+ `;