open-memex 0.8.2 → 0.9.0-alpha.2
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/AGENTS.md +21 -5
- package/CHANGELOG.md +10 -0
- package/README.md +46 -13
- package/README.zh-CN.md +25 -11
- package/dist/.build-stamp +1 -1
- package/dist/cli.js +103 -6
- package/dist/config.js +9 -0
- package/dist/doctor.js +4 -2
- package/dist/index.js +6 -1
- package/dist/init.js +13 -3
- package/dist/mcp.js +28 -5
- package/dist/opencode-v2.js +6 -2
- package/dist/plugin-core.js +28 -1
- package/dist/retrieve/inject.js +6 -0
- package/dist/retrieve/search.js +13 -2
- package/dist/review.js +7 -0
- package/dist/store/audit.js +14 -0
- package/dist/store/db.js +19 -0
- package/dist/store/lifecycle.js +8 -0
- package/dist/store/usage.js +151 -0
- package/dist/tools/memory.js +21 -2
- package/dist/tools/ops.js +123 -1
- package/dist/working-state.js +118 -0
- package/docs/CONCEPTS.md +16 -0
- package/docs/CONCEPTS.zh-CN.md +13 -0
- package/docs/V2-DESIGN.md +42 -1039
- package/docs/design/decisions.md +1146 -0
- package/docs/design/knowledge-graph.md +86 -0
- package/package.json +66 -66
- package/scripts/smoke-mcp.ts +67 -4
- package/scripts/smoke-pure.ts +70 -0
- package/scripts/test-full.ts +83 -0
- package/server.json +2 -2
- package/skills/open-memex/SKILL.md +19 -0
- package/src/cli.ts +111 -6
- package/src/config.ts +16 -0
- package/src/doctor.ts +4 -2
- package/src/index.ts +6 -0
- package/src/init.ts +13 -3
- package/src/mcp.ts +41 -4
- package/src/opencode-v2.ts +7 -2
- package/src/plugin-core.ts +32 -1
- package/src/retrieve/inject.ts +7 -0
- package/src/retrieve/search.ts +19 -3
- package/src/review.ts +6 -0
- package/src/store/audit.ts +20 -0
- package/src/store/db.ts +20 -0
- package/src/store/lifecycle.ts +9 -0
- package/src/store/usage.ts +178 -0
- package/src/tools/memory.ts +26 -1
- package/src/tools/ops.ts +158 -1
- package/src/working-state.ts +153 -0
package/src/store/db.ts
CHANGED
|
@@ -127,6 +127,25 @@ END;
|
|
|
127
127
|
/** Current index schema version. Bump when TABLE_SCHEMA/FTS_SCHEMA change. */
|
|
128
128
|
const SCHEMA_VERSION = 9;
|
|
129
129
|
|
|
130
|
+
// D77-L2: reuse counters live in their own table, keyed by memory id. It is
|
|
131
|
+
// created on every open (CREATE IF NOT EXISTS) and deliberately NOT part of
|
|
132
|
+
// the rebuildable index: `rebuildIndexSchema` drops memories/memories_fts
|
|
133
|
+
// and re-derives them from the Markdown files, but the counters are
|
|
134
|
+
// accumulated telemetry with no source-of-truth file to rebuild from — so
|
|
135
|
+
// they must survive a rebuild (ids are stable: the files carry them).
|
|
136
|
+
// No SCHEMA_VERSION bump: the table is additive with IF NOT EXISTS.
|
|
137
|
+
const USAGE_SCHEMA = `
|
|
138
|
+
CREATE TABLE IF NOT EXISTS memory_usage (
|
|
139
|
+
id TEXT PRIMARY KEY,
|
|
140
|
+
retrieved_count INTEGER NOT NULL DEFAULT 0,
|
|
141
|
+
useful_self INTEGER NOT NULL DEFAULT 0,
|
|
142
|
+
useful_team INTEGER NOT NULL DEFAULT 0,
|
|
143
|
+
last_retrieved_at TEXT NOT NULL DEFAULT '',
|
|
144
|
+
last_useful_at TEXT,
|
|
145
|
+
updated_at TEXT NOT NULL DEFAULT ''
|
|
146
|
+
);
|
|
147
|
+
`;
|
|
148
|
+
|
|
130
149
|
function userVersion(d: AnyDatabase): number {
|
|
131
150
|
const row = d.prepare("PRAGMA user_version").get() as { user_version: number };
|
|
132
151
|
return row.user_version;
|
|
@@ -181,6 +200,7 @@ export function db(): AnyDatabase {
|
|
|
181
200
|
if (hasTable && userVersion(d) < SCHEMA_VERSION) rebuildIndexSchema(d);
|
|
182
201
|
d.exec(TABLE_SCHEMA);
|
|
183
202
|
d.exec(FTS_SCHEMA);
|
|
203
|
+
d.exec(USAGE_SCHEMA);
|
|
184
204
|
if (userVersion(d) < SCHEMA_VERSION) rebuildIndexSchema(d);
|
|
185
205
|
_db = d;
|
|
186
206
|
return d;
|
package/src/store/lifecycle.ts
CHANGED
|
@@ -10,6 +10,7 @@ import {
|
|
|
10
10
|
import { loadConfig } from "../config.ts";
|
|
11
11
|
import { cjkIndexText } from "../retrieve/cjk.ts";
|
|
12
12
|
import { isTurnEcho } from "../capture/handoff.ts";
|
|
13
|
+
import { recordUseful, usefulKindFor } from "./usage.ts";
|
|
13
14
|
import {
|
|
14
15
|
parse,
|
|
15
16
|
serialize,
|
|
@@ -282,6 +283,10 @@ export function supersede(
|
|
|
282
283
|
`cannot supersede memory with status '${oldMf.fm.status}' (id ${oldId}); only active memories can be superseded`,
|
|
283
284
|
);
|
|
284
285
|
}
|
|
286
|
+
// D77-L2: the replacement's chain pointer back to this memory is a
|
|
287
|
+
// behavioral useful signal — something here was worth carrying forward.
|
|
288
|
+
// Classified from the OLD memory's state (captured before any flips).
|
|
289
|
+
const usefulKind = usefulKindFor(oldMf.fm.scope, oldMf.fm.review_state);
|
|
285
290
|
|
|
286
291
|
const now = msToRfc3339(Date.now());
|
|
287
292
|
const newFm: Frontmatter = {
|
|
@@ -329,6 +334,10 @@ export function supersede(
|
|
|
329
334
|
oldMf.fm.updated_at = now;
|
|
330
335
|
rewriteMemoryFile(oldMf);
|
|
331
336
|
|
|
337
|
+
// Behavioral useful (D77) — recorded after both aliases of the chain are
|
|
338
|
+
// settled, so a crash mid-supersede never half-records.
|
|
339
|
+
recordUseful(oldId, usefulKind, "supersede");
|
|
340
|
+
|
|
332
341
|
return { oldMf, newMf };
|
|
333
342
|
}
|
|
334
343
|
|
|
@@ -0,0 +1,178 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* D77-L2: per-memory online reuse counters — `retrieved_count` (exposure:
|
|
3
|
+
* returned by search / list / first-turn injection) and useful counts,
|
|
4
|
+
* split into `useful_self` (the author's own reuse — personal memories and
|
|
5
|
+
* unpublished project drafts) and `useful_team` (reuse of reviewed project
|
|
6
|
+
* knowledge). Derived: reuse_rate = (useful_self + useful_team) /
|
|
7
|
+
* retrieved_count; "zombie memories" (retrieved, never useful) surface in
|
|
8
|
+
* the D77-L3 report.
|
|
9
|
+
*
|
|
10
|
+
* Counters live in SQLite, NOT in frontmatter (D77): they are volatile
|
|
11
|
+
* local telemetry, the Markdown source of truth never rewrites itself with
|
|
12
|
+
* every retrieval, and they never leave the machine. The table is keyed by
|
|
13
|
+
* memory id and deliberately sits OUTSIDE the rebuildable index schema —
|
|
14
|
+
* `rebuildIndexSchema` drops `memories`/`memories_fts` but must not touch
|
|
15
|
+
* counters (the ids survive a rebuild because the files carry them).
|
|
16
|
+
*
|
|
17
|
+
* Restraint rules (D77): useful only via explicit signal — `memory_useful`,
|
|
18
|
+
* a human approve at review, or a behavioral reference (supersede).
|
|
19
|
+
* Passive surfacing increments ONLY retrieved_count; unguarded exposure
|
|
20
|
+
* must never refresh usefulness (the self-reinforcing retrieval loop).
|
|
21
|
+
*
|
|
22
|
+
* `reuse_rate` is the useful/retrieved ratio, not a probability: an explicit
|
|
23
|
+
* confirmation does not require a matching recorded exposure in the same
|
|
24
|
+
* counter window (a human can confirm a memory that paid off before counters
|
|
25
|
+
* existed, or confirm the same payoff twice), so the ratio can exceed 1.0.
|
|
26
|
+
* Read it as signal strength, not a percentage.
|
|
27
|
+
*/
|
|
28
|
+
import { db } from "./db.ts";
|
|
29
|
+
|
|
30
|
+
export type UsefulKind = "self" | "team";
|
|
31
|
+
|
|
32
|
+
export interface MemoryUsage {
|
|
33
|
+
id: string;
|
|
34
|
+
retrieved_count: number;
|
|
35
|
+
useful_self: number;
|
|
36
|
+
useful_team: number;
|
|
37
|
+
last_retrieved_at: string; // RFC 3339, "" when never
|
|
38
|
+
last_useful_at: string | null; // RFC 3339
|
|
39
|
+
updated_at: string; // RFC 3339
|
|
40
|
+
}
|
|
41
|
+
|
|
42
|
+
export function usefulKindFor(scope: unknown, reviewState: unknown): UsefulKind {
|
|
43
|
+
if (scope === "personal") return "self";
|
|
44
|
+
// No identity system (D77): reviewed project knowledge reused = the team
|
|
45
|
+
// story; everything else still reads as the author's own utility.
|
|
46
|
+
if (reviewState === "approved" || reviewState === "published") return "team";
|
|
47
|
+
return "self";
|
|
48
|
+
}
|
|
49
|
+
|
|
50
|
+
const INSERT_RETRIEVED_SQL = `
|
|
51
|
+
INSERT INTO memory_usage (id, retrieved_count, useful_self, useful_team, last_retrieved_at, last_useful_at, updated_at)
|
|
52
|
+
VALUES (?, 1, 0, 0, ?, NULL, ?)
|
|
53
|
+
ON CONFLICT(id) DO UPDATE SET
|
|
54
|
+
retrieved_count = memory_usage.retrieved_count + 1,
|
|
55
|
+
last_retrieved_at = excluded.last_retrieved_at,
|
|
56
|
+
updated_at = excluded.updated_at
|
|
57
|
+
`;
|
|
58
|
+
|
|
59
|
+
function insertUsefulSql(self: boolean): string {
|
|
60
|
+
const col = self ? "useful_self" : "useful_team";
|
|
61
|
+
return `
|
|
62
|
+
INSERT INTO memory_usage (id, retrieved_count, useful_self, useful_team, last_retrieved_at, last_useful_at, updated_at)
|
|
63
|
+
VALUES (?, 0, ${self ? 1 : 0}, ${self ? 0 : 1}, '', ?, ?)
|
|
64
|
+
ON CONFLICT(id) DO UPDATE SET
|
|
65
|
+
${col} = memory_usage.${col} + 1,
|
|
66
|
+
last_useful_at = excluded.last_useful_at,
|
|
67
|
+
updated_at = excluded.updated_at
|
|
68
|
+
`;
|
|
69
|
+
}
|
|
70
|
+
|
|
71
|
+
function rfc(ms: number): string {
|
|
72
|
+
return new Date(ms).toISOString().replace(/\.000Z$/, "Z");
|
|
73
|
+
}
|
|
74
|
+
|
|
75
|
+
/**
|
|
76
|
+
* Count one exposure each for the ids actually returned to a caller
|
|
77
|
+
* (already limited/filtered — callers record the final hits, not the
|
|
78
|
+
* candidate pool). Unknown/id-side dupes are absorbed: ids arrive deduped
|
|
79
|
+
* (resolution collapses chains anyway); anything not in the index yet is
|
|
80
|
+
* still counted — a just-saved memory can be hit in the same query that
|
|
81
|
+
* created it only after upsert, so the index row exists by contract; a
|
|
82
|
+
* missing one gets a row with last_retrieved_at set and no harm done.
|
|
83
|
+
*/
|
|
84
|
+
export function recordRetrieved(ids: readonly string[], atMs: number = Date.now()): number {
|
|
85
|
+
if (ids.length === 0) return 0;
|
|
86
|
+
// No explicit transaction wrapper: both drivers' .transaction() returns a
|
|
87
|
+
// deferred callable (calling it must NOT execute), and the common surface
|
|
88
|
+
// here is stmt-exec only. Per-row autocommit on WAL is plenty for the
|
|
89
|
+
// ≤50 ids one retrieval returns.
|
|
90
|
+
const d = db();
|
|
91
|
+
const at = rfc(atMs);
|
|
92
|
+
const stmt = d.prepare(INSERT_RETRIEVED_SQL);
|
|
93
|
+
for (const id of ids) stmt.run(id, at, at);
|
|
94
|
+
return new Set(ids).size;
|
|
95
|
+
}
|
|
96
|
+
|
|
97
|
+
export const VIA_VALUES = ["tool", "supersede", "promote"] as const;
|
|
98
|
+
export type UsefulVia = (typeof VIA_VALUES)[number];
|
|
99
|
+
|
|
100
|
+
/**
|
|
101
|
+
* Count one explicit useful signal. Returns the updated row, or null when
|
|
102
|
+
* the id is not in the index (callers surface that as not-found — a useful
|
|
103
|
+
* tick for a memory nobody has must not create phantom telemetry).
|
|
104
|
+
*/
|
|
105
|
+
export function recordUseful(
|
|
106
|
+
id: string,
|
|
107
|
+
kind: UsefulKind,
|
|
108
|
+
_via: UsefulVia,
|
|
109
|
+
atMs: number = Date.now(),
|
|
110
|
+
): MemoryUsage | null {
|
|
111
|
+
const d = db();
|
|
112
|
+
const mem = d.prepare(`SELECT id FROM memories WHERE id = ?`).get(id) as
|
|
113
|
+
| { id: string }
|
|
114
|
+
| undefined;
|
|
115
|
+
if (!mem) return null;
|
|
116
|
+
const at = rfc(atMs);
|
|
117
|
+
d.prepare(insertUsefulSql(kind === "self")).run(id, at, at);
|
|
118
|
+
return getUsage(id);
|
|
119
|
+
}
|
|
120
|
+
|
|
121
|
+
export function getUsage(id: string): MemoryUsage | null {
|
|
122
|
+
const row = db()
|
|
123
|
+
.prepare(
|
|
124
|
+
`SELECT id, retrieved_count, useful_self, useful_team,
|
|
125
|
+
last_retrieved_at, last_useful_at, updated_at
|
|
126
|
+
FROM memory_usage WHERE id = ?`,
|
|
127
|
+
)
|
|
128
|
+
.get(id) as MemoryUsage | undefined;
|
|
129
|
+
if (!row) return null;
|
|
130
|
+
row.retrieved_count = Number(row.retrieved_count) || 0;
|
|
131
|
+
row.useful_self = Number(row.useful_self) || 0;
|
|
132
|
+
row.useful_team = Number(row.useful_team) || 0;
|
|
133
|
+
return row;
|
|
134
|
+
}
|
|
135
|
+
|
|
136
|
+
/** D77: useful_count = useful_self + useful_team — both count as useful. */
|
|
137
|
+
export function usefulCount(u: Pick<MemoryUsage, "useful_self" | "useful_team">): number {
|
|
138
|
+
return u.useful_self + u.useful_team;
|
|
139
|
+
}
|
|
140
|
+
|
|
141
|
+
/** reuse_rate = useful / retrieved (0 when the memory was never retrieved). */
|
|
142
|
+
export function reuseRate(u: MemoryUsage): number | null {
|
|
143
|
+
const n = usefulCount(u);
|
|
144
|
+
if (u.retrieved_count <= 0) return null;
|
|
145
|
+
return n / u.retrieved_count;
|
|
146
|
+
}
|
|
147
|
+
|
|
148
|
+
/** D77-L3's selection helpers ride the same table scan for free. */
|
|
149
|
+
export function listUsage(scopeKey?: string): MemoryUsage[] {
|
|
150
|
+
const sql = scopeKey
|
|
151
|
+
? `SELECT u.id, u.retrieved_count, u.useful_self, u.useful_team,
|
|
152
|
+
u.last_retrieved_at, u.last_useful_at, u.updated_at
|
|
153
|
+
FROM memory_usage u JOIN memories m ON m.id = u.id
|
|
154
|
+
WHERE m.scope_key = ?`
|
|
155
|
+
: `SELECT u.id, u.retrieved_count, u.useful_self, u.useful_team,
|
|
156
|
+
u.last_retrieved_at, u.last_useful_at, u.updated_at
|
|
157
|
+
FROM memory_usage u`;
|
|
158
|
+
const args = scopeKey ? [scopeKey] : [];
|
|
159
|
+
const rows = db().prepare(sql).all(...(args as unknown[])) as MemoryUsage[];
|
|
160
|
+
for (const r of rows) {
|
|
161
|
+
r.retrieved_count = Number(r.retrieved_count) || 0;
|
|
162
|
+
r.useful_self = Number(r.useful_self) || 0;
|
|
163
|
+
r.useful_team = Number(r.useful_team) || 0;
|
|
164
|
+
}
|
|
165
|
+
return rows;
|
|
166
|
+
}
|
|
167
|
+
|
|
168
|
+
/**
|
|
169
|
+
* Drop one memory's telemetry. ONLY the hard-forget path calls this (the
|
|
170
|
+
* memory is gone for good); plain index removal — which fires on a branch
|
|
171
|
+
* switch, when in-repo files transiently disappear — must NOT prune here,
|
|
172
|
+
* or switching branches would wipe counters the files will resurrect.
|
|
173
|
+
* Superseded/deprecated/retracted memories keep their rows: their history
|
|
174
|
+
* is part of the reuse story.
|
|
175
|
+
*/
|
|
176
|
+
export function deleteUsage(id: string): void {
|
|
177
|
+
db().prepare(`DELETE FROM memory_usage WHERE id = ?`).run(id);
|
|
178
|
+
}
|
package/src/tools/memory.ts
CHANGED
|
@@ -10,11 +10,15 @@ import {
|
|
|
10
10
|
listMemories,
|
|
11
11
|
supersedeMemory,
|
|
12
12
|
forgetMemory,
|
|
13
|
+
markMemoryUseful,
|
|
14
|
+
workingStateMemory,
|
|
13
15
|
memoryAddArgs,
|
|
14
16
|
memorySearchArgs,
|
|
15
17
|
memoryListArgs,
|
|
16
18
|
memorySupersedeArgs,
|
|
17
19
|
memoryForgetArgs,
|
|
20
|
+
memoryUsefulArgs,
|
|
21
|
+
memoryWorkingStateArgs,
|
|
18
22
|
TOOL_DESCRIPTIONS,
|
|
19
23
|
withOutboxNote,
|
|
20
24
|
} from "./ops.ts";
|
|
@@ -100,5 +104,26 @@ export function makeTools(getScope: () => Scope, cfg: MyOMemoryConfig) {
|
|
|
100
104
|
},
|
|
101
105
|
});
|
|
102
106
|
|
|
103
|
-
|
|
107
|
+
// D77-L2: explicit useful confirmation. Needs a fresh index read to
|
|
108
|
+
// classify (scope/review_state), hence syncFirst like the mutators.
|
|
109
|
+
const memory_useful = tool({
|
|
110
|
+
description: TOOL_DESCRIPTIONS.memory_useful,
|
|
111
|
+
args: memoryUsefulArgs,
|
|
112
|
+
async execute(args) {
|
|
113
|
+
syncFirst();
|
|
114
|
+
return markMemoryUseful(args);
|
|
115
|
+
},
|
|
116
|
+
});
|
|
117
|
+
|
|
118
|
+
// §3.6 (D89): no scope/index work needed — the note lives beside the
|
|
119
|
+
// store, not in it.
|
|
120
|
+
const memory_workingstate = tool({
|
|
121
|
+
description: TOOL_DESCRIPTIONS.memory_workingstate,
|
|
122
|
+
args: memoryWorkingStateArgs,
|
|
123
|
+
async execute(args) {
|
|
124
|
+
return workingStateMemory(getScope, cfg, args);
|
|
125
|
+
},
|
|
126
|
+
});
|
|
127
|
+
|
|
128
|
+
return { memory_add, memory_search, memory_list, memory_forget, memory_supersede, memory_useful, memory_workingstate };
|
|
104
129
|
}
|
package/src/tools/ops.ts
CHANGED
|
@@ -25,11 +25,24 @@ import {
|
|
|
25
25
|
import { upsertFromFile, deleteFromIndex } from "../store/sync.ts";
|
|
26
26
|
import { findDuplicates, findTurnEcho, supersede, setStatus } from "../store/lifecycle.ts";
|
|
27
27
|
import { TURN_ECHO_WINDOW_MS } from "../capture/handoff.ts";
|
|
28
|
+
import {
|
|
29
|
+
getUsage,
|
|
30
|
+
recordUseful,
|
|
31
|
+
reuseRate,
|
|
32
|
+
usefulKindFor,
|
|
33
|
+
usefulCount,
|
|
34
|
+
deleteUsage,
|
|
35
|
+
} from "../store/usage.ts";
|
|
28
36
|
import { db } from "../store/db.ts";
|
|
29
37
|
import { redact } from "../redact.ts";
|
|
30
38
|
import { getSyncStatus, formatSyncStatus, submitMemories, outboxDraftCount } from "../submit.ts";
|
|
31
39
|
import { getPrStatus, formatPrStatus, applyPrStatus } from "../github.ts";
|
|
32
40
|
import { isInRepoMemoryFile } from "../paths.ts";
|
|
41
|
+
import {
|
|
42
|
+
writeWorkingState,
|
|
43
|
+
readWorkingState,
|
|
44
|
+
clearWorkingState,
|
|
45
|
+
} from "../working-state.ts";
|
|
33
46
|
import {
|
|
34
47
|
proposeMemories,
|
|
35
48
|
promoteMemory,
|
|
@@ -87,6 +100,10 @@ export const TOOL_DESCRIPTIONS = {
|
|
|
87
100
|
"List git-conflicted memory files, or attempt a field-level 3-way merge of one. Semantic conflicts are reported, never auto-resolved. Run it when a git pull or merge leaves memory files conflicted; the merged file is written in place (undo with git if the merge is wrong). For PR review state rather than file conflicts, use memory_pr_status. (MCP server and the `open-memex resolve` CLI; the opencode native plugin does not expose this tool.)",
|
|
88
101
|
memory_pr_status:
|
|
89
102
|
"Read the current branch's GitHub PR and map its review state onto each in-repo memory: merged PR → published, PR approval → approved (approved_by = reviewer), changes-requested → suggestion only. Report by default — that mode changes nothing; apply=true writes the mapped transitions to the local files (still no push). (MCP server and the `open-memex pr-status` CLI; the opencode native plugin does not expose this tool.)",
|
|
103
|
+
memory_workingstate:
|
|
104
|
+
"Read, write, or clear the one ephemeral per-project working-state note (§3.6, D89): where an interrupted task stands, so a fresh session can resume. Scratch state, NOT durable knowledge — it never enters memory retrieval or a review ladder; any conclusion here that should outlive the task goes through the normal memory_add/checkpoint-proposal path instead. WRITE it (action=write, content required) when the user signals the session or task is wrapping up — body rubric: task summary (one paragraph), open files, last commands, where the work stands, next step; short by design, a scratch note, not a transcript. READ it when resuming work or when the user asks what they were doing. CLEAR it on the user's request only. The note lives outside memories/, the user can edit the plain file directly, and it expires after ttl_days (default 7) — expired notes are ignored and `audit` reports them.",
|
|
105
|
+
memory_useful:
|
|
106
|
+
"Mark an existing memory as useful (D77): record that it demonstrably paid off. Call it ONLY on an explicit signal — the user confirmed it helped ('that was the one', 'saved me again'), or your completed/accepted work clearly relied on that memory and the user saw the result. NEVER call it because a memory appeared in memory_search results, a memory_list inventory, or the session-start block: passive exposure never refreshes usefulness. Exposure is counted automatically under retrieved_count; the useful buckets increment only through this tool, a human approval at review, or a supersede. Useful is split automatically: useful_self for personal memories and unpublished project drafts (the author's own utility), useful_team for approved/published project memories (team knowledge reused) — pass kind only to override. Returns the cumulative counts and reuse_rate (useful / retrieved). The counters live in the local SQLite index, not in the Markdown source of truth, and never leave this machine.",
|
|
90
107
|
} as const;
|
|
91
108
|
|
|
92
109
|
/** Shared zod input shapes (raw shape, not z.object — hosts wrap as needed). */
|
|
@@ -263,6 +280,36 @@ export const memoryPrStatusArgs = {
|
|
|
263
280
|
};
|
|
264
281
|
export type MemoryPrStatusArgs = z.infer<z.ZodObject<typeof memoryPrStatusArgs>>;
|
|
265
282
|
|
|
283
|
+
export const memoryWorkingStateArgs = {
|
|
284
|
+
action: z
|
|
285
|
+
.enum(["read", "write", "clear"])
|
|
286
|
+
.default("read")
|
|
287
|
+
.describe(
|
|
288
|
+
"read = show the current note (empty when none); write = create or refresh it; clear = delete it.",
|
|
289
|
+
),
|
|
290
|
+
content: z
|
|
291
|
+
.string()
|
|
292
|
+
.optional()
|
|
293
|
+
.describe(
|
|
294
|
+
"Note body, Markdown, short by design (required for write). Rubric: task summary (one paragraph), open files, last commands, where the work stands, next step. A scratch note, not a transcript.",
|
|
295
|
+
),
|
|
296
|
+
};
|
|
297
|
+
export type MemoryWorkingStateArgs = z.infer<z.ZodObject<typeof memoryWorkingStateArgs>>;
|
|
298
|
+
|
|
299
|
+
export const memoryUsefulArgs = {
|
|
300
|
+
id: z
|
|
301
|
+
.string()
|
|
302
|
+
.min(1)
|
|
303
|
+
.describe("ID of the memory being confirmed useful (memory_search / memory_list return ids)."),
|
|
304
|
+
kind: z
|
|
305
|
+
.enum(["self", "team"])
|
|
306
|
+
.optional()
|
|
307
|
+
.describe(
|
|
308
|
+
"Which useful counter. Default: auto — personal memories and unpublished project drafts count useful_self; approved/published project memories count useful_team. Pass only to override the auto split.",
|
|
309
|
+
),
|
|
310
|
+
};
|
|
311
|
+
export type MemoryUsefulArgs = z.infer<z.ZodObject<typeof memoryUsefulArgs>>;
|
|
312
|
+
|
|
266
313
|
function resolveScope(
|
|
267
314
|
getScope: () => Scope,
|
|
268
315
|
kind?: "project" | "personal",
|
|
@@ -400,10 +447,12 @@ export async function searchMemories(
|
|
|
400
447
|
: args.scope === "project"
|
|
401
448
|
? [project.key]
|
|
402
449
|
: [project.key, PERSONAL_SCOPE.key];
|
|
450
|
+
// D77-L2: every surface that hands hits to a caller counts as exposure.
|
|
403
451
|
const hits = search(args.query, {
|
|
404
452
|
scopeKeys,
|
|
405
453
|
limit: args.limit,
|
|
406
454
|
type: args.type,
|
|
455
|
+
record: true,
|
|
407
456
|
});
|
|
408
457
|
if (hits.length === 0) {
|
|
409
458
|
return {
|
|
@@ -431,7 +480,7 @@ export async function listMemories(
|
|
|
431
480
|
// #3" names exactly one memory. A per-section counter emitted two "#1"s.
|
|
432
481
|
let seq = 0;
|
|
433
482
|
const render = (scopeKey: string) => {
|
|
434
|
-
const hits = list(scopeKey, { type: args.type, limit: args.limit, include });
|
|
483
|
+
const hits = list(scopeKey, { type: args.type, limit: args.limit, include, record: true });
|
|
435
484
|
const total = countList(scopeKey, { type: args.type, include });
|
|
436
485
|
const lines = hits.map((h) => formatInventoryLine(seq++, h, PERSONAL_SCOPE.key));
|
|
437
486
|
const note = truncationNote(hits.length, total);
|
|
@@ -569,6 +618,10 @@ export async function forgetMemory(args: MemoryForgetArgs): Promise<ToolResult>
|
|
|
569
618
|
}
|
|
570
619
|
}
|
|
571
620
|
deleteFromIndex(args.id);
|
|
621
|
+
// D77-L2: the memory is gone for good — its telemetry has no subject left.
|
|
622
|
+
// Only the hard path prunes the usage row; status flips and index removal
|
|
623
|
+
// (branch switches remove in-repo files transiently) keep it.
|
|
624
|
+
deleteUsage(args.id);
|
|
572
625
|
// D64: forgetting an in-repo memory deletes a file inside the user's
|
|
573
626
|
// git working tree. Say so — the deletion should ride a commit, or the
|
|
574
627
|
// file silently diverges from what teammates have.
|
|
@@ -586,6 +639,46 @@ export async function forgetMemory(args: MemoryForgetArgs): Promise<ToolResult>
|
|
|
586
639
|
// sync loop: status → ask user → submit → push/PR on approval).
|
|
587
640
|
// ---------------------------------------------------------------------------
|
|
588
641
|
|
|
642
|
+
/**
|
|
643
|
+
* D77-L2: the explicit confirmation route to the useful counters. The
|
|
644
|
+
* restraint rules live in the tool description and the MCP handshake —
|
|
645
|
+
* an unguarded call path here would create the self-reinforcing retrieval
|
|
646
|
+
* loop D77 warns about, so nothing silently routes exposure into useful.
|
|
647
|
+
* Classification proxy (no identity system): personal scope / unreviewed
|
|
648
|
+
* project draft → useful_self; approved/published project memory → useful_team.
|
|
649
|
+
*/
|
|
650
|
+
export async function markMemoryUseful(
|
|
651
|
+
args: MemoryUsefulArgs,
|
|
652
|
+
): Promise<ToolResult> {
|
|
653
|
+
const row = db()
|
|
654
|
+
.prepare(`SELECT scope, review_state FROM memories WHERE id = ?`)
|
|
655
|
+
.get(args.id) as { scope: string; review_state: string } | undefined;
|
|
656
|
+
if (!row) {
|
|
657
|
+
return {
|
|
658
|
+
title: "memory: useful not found",
|
|
659
|
+
output: `No memory with id ${args.id} in the index — memory_search or memory_list returns current ids.`,
|
|
660
|
+
};
|
|
661
|
+
}
|
|
662
|
+
const kind = args.kind ?? usefulKindFor(row.scope, row.review_state);
|
|
663
|
+
const after = recordUseful(args.id, kind, "tool");
|
|
664
|
+
// recordUseful re-checks existence; both branches above agree on not-found.
|
|
665
|
+
if (!after) {
|
|
666
|
+
return {
|
|
667
|
+
title: "memory: useful not found",
|
|
668
|
+
output: `No memory with id ${args.id} in the index.`,
|
|
669
|
+
};
|
|
670
|
+
}
|
|
671
|
+
const u = getUsage(args.id)!;
|
|
672
|
+
const rate = reuseRate(u);
|
|
673
|
+
const useful = usefulCount(u);
|
|
674
|
+
return {
|
|
675
|
+
title: `memory: useful (${kind}) ${args.id}`,
|
|
676
|
+
output:
|
|
677
|
+
`Marked useful (${kind}). retrieved: ${u.retrieved_count}, useful_self: ${u.useful_self}, useful_team: ${u.useful_team}, reuse_rate: ${rate === null ? "n/a (never retrieved)" : rate.toFixed(2)}.` +
|
|
678
|
+
`\nA supersede or a human approval also counts — no need to duplicate those with an explicit call.`,
|
|
679
|
+
};
|
|
680
|
+
}
|
|
681
|
+
|
|
589
682
|
export async function statusMemories(): Promise<ToolResult> {
|
|
590
683
|
const st = getSyncStatus();
|
|
591
684
|
const n =
|
|
@@ -682,3 +775,67 @@ export async function prStatusOp(args: MemoryPrStatusArgs): Promise<ToolResult>
|
|
|
682
775
|
}
|
|
683
776
|
return { title: "memory: pr-status", output: lines.join("\n") };
|
|
684
777
|
}
|
|
778
|
+
|
|
779
|
+
/**
|
|
780
|
+
* §3.6 (D89): the one ephemeral per-project working-state note. Scratch
|
|
781
|
+
* state, not knowledge — it never enters the review ladder or the
|
|
782
|
+
* retrieval index; durable conclusions still go through memory_add (agent
|
|
783
|
+
* proposes, user approves). The tool description and the session-start
|
|
784
|
+
* block must keep saying the same thing on this.
|
|
785
|
+
*/
|
|
786
|
+
export async function workingStateMemory(
|
|
787
|
+
getScope: () => Scope,
|
|
788
|
+
cfg: MyOMemoryConfig,
|
|
789
|
+
args: MemoryWorkingStateArgs,
|
|
790
|
+
): Promise<ToolResult> {
|
|
791
|
+
if (!cfg.workingStateEnabled) {
|
|
792
|
+
return {
|
|
793
|
+
title: "memory: working-state",
|
|
794
|
+
output:
|
|
795
|
+
"The working-state note is disabled (config workingStateEnabled=false). Enable it in the config file, or record durable facts with memory_add instead.",
|
|
796
|
+
};
|
|
797
|
+
}
|
|
798
|
+
const scope = getScope();
|
|
799
|
+
if (args.action === "clear") {
|
|
800
|
+
const gone = clearWorkingState(scope.key);
|
|
801
|
+
return {
|
|
802
|
+
title: "memory: working-state",
|
|
803
|
+
output: gone
|
|
804
|
+
? `Working-state note for ${scope.projectName} deleted.`
|
|
805
|
+
: "Failed to delete the working-state note — it may still be on disk.",
|
|
806
|
+
};
|
|
807
|
+
}
|
|
808
|
+
if (args.action === "write") {
|
|
809
|
+
const content = (args.content ?? "").trim();
|
|
810
|
+
if (!content) {
|
|
811
|
+
return {
|
|
812
|
+
title: "memory: working-state",
|
|
813
|
+
output:
|
|
814
|
+
"Refusing an empty working-state note: pass content (task summary, open files, last commands, where the work stands, next step).",
|
|
815
|
+
};
|
|
816
|
+
}
|
|
817
|
+
const r = writeWorkingState(scope.key, content, cfg.workingStateTtlDays, cfg.redactPatterns);
|
|
818
|
+
const secretNote = r.hadSecret
|
|
819
|
+
? `\n[open-memex: a secret was masked in place (${r.matchedPattern}) before saving]`
|
|
820
|
+
: "";
|
|
821
|
+
return {
|
|
822
|
+
title: "memory: working-state",
|
|
823
|
+
output:
|
|
824
|
+
`Working-state note written to ${r.filePath}. Surfaces at session start; expires after ${cfg.workingStateTtlDays} day${cfg.workingStateTtlDays === 1 ? "" : "s"} or at the next write.${secretNote}`,
|
|
825
|
+
};
|
|
826
|
+
}
|
|
827
|
+
const note = readWorkingState(scope.key, cfg.workingStateTtlDays);
|
|
828
|
+
if (!note) {
|
|
829
|
+
return {
|
|
830
|
+
title: "memory: working-state",
|
|
831
|
+
output: `No working-state note for ${scope.projectName}. Write one at wrap-up (action=write) so an interrupted task can resume.`,
|
|
832
|
+
};
|
|
833
|
+
}
|
|
834
|
+
const status = note.expired
|
|
835
|
+
? `EXPIRED (${note.ageDays} day${note.ageDays === 1 ? "" : "s"} old, ttl ${note.ttlDays}) — stale until a write refreshes it`
|
|
836
|
+
: `updated ${note.ageDays} day${note.ageDays === 1 ? "" : "s"} ago, ttl ${note.ttlDays} day${note.ttlDays === 1 ? "" : "s"}`;
|
|
837
|
+
return {
|
|
838
|
+
title: "memory: working-state",
|
|
839
|
+
output: `[${status}]\n\n${note.content}`,
|
|
840
|
+
};
|
|
841
|
+
}
|
|
@@ -0,0 +1,153 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* D89 / §3.6 — session working state note.
|
|
3
|
+
*
|
|
4
|
+
* One ephemeral Markdown note per project scope, at
|
|
5
|
+
* `working-state/<scope_key>.md` under the data root — beside the store,
|
|
6
|
+
* never inside `memories/`, never committed to a repo. The note is written
|
|
7
|
+
* or refreshed by the agent at wrap-up, surfaced at session start alongside
|
|
8
|
+
* the §7 injection, and never enters the review ladder: it is scratch
|
|
9
|
+
* state, not knowledge. Worth-keeping content routes through the D61
|
|
10
|
+
* checkpoint-proposal flow — the note is raw material, the ladder is the
|
|
11
|
+
* gate. Expired notes are reported by `audit` (reports only, never
|
|
12
|
+
* auto-deletes — the D57 posture); the next wrap-up write overwrites.
|
|
13
|
+
*
|
|
14
|
+
* Hermetic on purpose: only fs, paths and config types are imported, no
|
|
15
|
+
* sqlite — scripts/smoke-pure.ts keeps its no-sqlite guarantee.
|
|
16
|
+
*/
|
|
17
|
+
import fs from "node:fs";
|
|
18
|
+
import path from "node:path";
|
|
19
|
+
import { paths } from "./paths.ts";
|
|
20
|
+
import { redact } from "./redact.ts";
|
|
21
|
+
import { atomicWriteTextSync } from "./store/markdown.ts";
|
|
22
|
+
import type { MyOMemoryConfig } from "./config.ts";
|
|
23
|
+
|
|
24
|
+
const DAY_MS = 86_400_000;
|
|
25
|
+
|
|
26
|
+
export interface WorkingStateFile {
|
|
27
|
+
content: string;
|
|
28
|
+
/** Filesystem write time in ms (the note's own age anchor). */
|
|
29
|
+
updatedAtMs: number;
|
|
30
|
+
/** TTL days effective for this note (frontmatter `ttl_days`, falling
|
|
31
|
+
* back to the given default). */
|
|
32
|
+
ttlDays: number;
|
|
33
|
+
/** Whole-day age of the note. */
|
|
34
|
+
ageDays: number;
|
|
35
|
+
/** True when ageDays > ttlDays — ignored by surfacing, reported by audit. */
|
|
36
|
+
expired: boolean;
|
|
37
|
+
}
|
|
38
|
+
|
|
39
|
+
export interface WriteWorkingStateResult {
|
|
40
|
+
filePath: string;
|
|
41
|
+
hadSecret: boolean;
|
|
42
|
+
matchedPattern: string | null;
|
|
43
|
+
}
|
|
44
|
+
|
|
45
|
+
/** Read-only path helper — never creates the directory (D70 discipline;
|
|
46
|
+
* contrast the write path below, which mkdirs on demand). */
|
|
47
|
+
export function workingStatePath(scopeKey: string): string {
|
|
48
|
+
return path.join(paths().root, "working-state", `${scopeKey}.md`);
|
|
49
|
+
}
|
|
50
|
+
|
|
51
|
+
/**
|
|
52
|
+
* Write or refresh the note. The agent composes the body (task summary /
|
|
53
|
+
* open files / last commands / where the work stands / next step). Content
|
|
54
|
+
* passes through `redact()` so command paste-through from an interrupted
|
|
55
|
+
* session cannot park a readable secret in storage. TTL days is stamped
|
|
56
|
+
* into frontmatter so the user's per-note edit survives config changes.
|
|
57
|
+
*/
|
|
58
|
+
export function writeWorkingState(
|
|
59
|
+
scopeKey: string,
|
|
60
|
+
content: string,
|
|
61
|
+
defaultTtlDays: number,
|
|
62
|
+
redactPatterns: string[],
|
|
63
|
+
): WriteWorkingStateResult {
|
|
64
|
+
const { content: redacted, hadSecret, matchedPattern } = redact(content, redactPatterns);
|
|
65
|
+
const filePath = workingStatePath(scopeKey);
|
|
66
|
+
fs.mkdirSync(path.dirname(filePath), { recursive: true });
|
|
67
|
+
const ttlDays = Number.isInteger(defaultTtlDays) && defaultTtlDays > 0 ? defaultTtlDays : 7;
|
|
68
|
+
const text =
|
|
69
|
+
"---\n" +
|
|
70
|
+
"schema: working-state\n" +
|
|
71
|
+
`updated_at: ${new Date().toISOString()}\n` +
|
|
72
|
+
`ttl_days: ${ttlDays}\n` +
|
|
73
|
+
"---\n" +
|
|
74
|
+
redacted.trimEnd() +
|
|
75
|
+
"\n";
|
|
76
|
+
atomicWriteTextSync(filePath, text);
|
|
77
|
+
return { filePath, hadSecret, matchedPattern };
|
|
78
|
+
}
|
|
79
|
+
|
|
80
|
+
/**
|
|
81
|
+
* Read the note and compute expiry. Missing file → null. A note older than
|
|
82
|
+
* its TTL is marked expired (surfacing ignores it; audit reports it).
|
|
83
|
+
*/
|
|
84
|
+
export function readWorkingState(
|
|
85
|
+
scopeKey: string,
|
|
86
|
+
defaultTtlDays: number,
|
|
87
|
+
): WorkingStateFile | null {
|
|
88
|
+
const filePath = workingStatePath(scopeKey);
|
|
89
|
+
let raw: string;
|
|
90
|
+
try {
|
|
91
|
+
raw = fs.readFileSync(filePath, "utf8");
|
|
92
|
+
} catch {
|
|
93
|
+
return null;
|
|
94
|
+
}
|
|
95
|
+
const m = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?/.exec(raw);
|
|
96
|
+
if (!m) return null;
|
|
97
|
+
const fm = m[1] ?? "";
|
|
98
|
+
const updatedAt = /^updated_at:\s*(.+)$/m.exec(fm)?.[1]?.trim() ?? "";
|
|
99
|
+
const t = Date.parse(updatedAt);
|
|
100
|
+
if (Number.isNaN(t)) return null;
|
|
101
|
+
const ttlDaysRaw = /^ttl_days:\s*(\d+)\s*$/m.exec(fm)?.[1];
|
|
102
|
+
const ttlDays = ttlDaysRaw
|
|
103
|
+
? Number.parseInt(ttlDaysRaw, 10)
|
|
104
|
+
: Number.isInteger(defaultTtlDays) && defaultTtlDays > 0
|
|
105
|
+
? defaultTtlDays
|
|
106
|
+
: 7;
|
|
107
|
+
const ageDays = Math.max(0, Math.floor((Date.now() - t) / DAY_MS));
|
|
108
|
+
return {
|
|
109
|
+
content: raw.slice(m[0].length).trimEnd(),
|
|
110
|
+
updatedAtMs: t,
|
|
111
|
+
ttlDays,
|
|
112
|
+
ageDays,
|
|
113
|
+
expired: ageDays > ttlDays,
|
|
114
|
+
};
|
|
115
|
+
}
|
|
116
|
+
|
|
117
|
+
/**
|
|
118
|
+
* Delete the note. Honest delete (D63 spirit): true — deleted or already
|
|
119
|
+
* gone; false — the unlink failed (keeps reporting to worry about).
|
|
120
|
+
*/
|
|
121
|
+
export function clearWorkingState(scopeKey: string): boolean {
|
|
122
|
+
const filePath = workingStatePath(scopeKey);
|
|
123
|
+
try {
|
|
124
|
+
fs.unlinkSync(filePath);
|
|
125
|
+
return true;
|
|
126
|
+
} catch (err) {
|
|
127
|
+
return (err as NodeJS.ErrnoException).code === "ENOENT";
|
|
128
|
+
}
|
|
129
|
+
}
|
|
130
|
+
|
|
131
|
+
/**
|
|
132
|
+
* D89: surfaced at session start, outside the review ladder. Returns null
|
|
133
|
+
* when nothing should surface: the feature is off, or no note exists, or
|
|
134
|
+
* the note has expired (audit is the reporter; silence at session start).
|
|
135
|
+
*/
|
|
136
|
+
export function workingStateBlock(
|
|
137
|
+
scopeKey: string,
|
|
138
|
+
projectName: string,
|
|
139
|
+
cfg: MyOMemoryConfig,
|
|
140
|
+
): string | null {
|
|
141
|
+
if (!cfg.workingStateEnabled) return null;
|
|
142
|
+
const note = readWorkingState(scopeKey, cfg.workingStateTtlDays);
|
|
143
|
+
if (!note || note.expired || !note.content) return null;
|
|
144
|
+
return (
|
|
145
|
+
`[OPEN-MEMEX WORKING STATE — ${projectName}]\n` +
|
|
146
|
+
"Scratch state from an interrupted task, not durable knowledge; do not save it as a memory.\n" +
|
|
147
|
+
note.content +
|
|
148
|
+
"\n\n" +
|
|
149
|
+
"This is the user's own recent work state, for resuming where the work stands. " +
|
|
150
|
+
"If something in it deserves to outlive the task, propose it as a distilled memory — the checkpoint-proposal flow is the gate, the note never enters a review ladder. " +
|
|
151
|
+
"When the user signals the session or task is wrapping up, refresh this note via `memory_workingstate` (action=write) before finishing: task summary, open files, last commands, where the work stands, next step."
|
|
152
|
+
);
|
|
153
|
+
}
|