open-memex 0.9.0-alpha.3 → 0.9.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/AGENTS.md +27 -2
- package/CHANGELOG.md +5 -7
- package/README.md +43 -1
- package/README.zh-CN.md +26 -1
- package/dist/.build-stamp +1 -1
- package/dist/cli.js +167 -2
- package/dist/config.js +11 -0
- package/dist/graph/extract.js +234 -0
- package/dist/graph/lint.js +89 -0
- package/dist/graph/outline.js +146 -0
- package/dist/graph/queries.js +122 -0
- package/dist/plugin-core.js +4 -0
- package/dist/retrieve/inject.js +26 -2
- package/dist/review.js +9 -0
- package/dist/store/db.js +8 -2
- package/dist/store/graph.js +225 -0
- package/dist/store/sync.js +7 -3
- package/dist/tools/ops.js +10 -1
- package/docs/V2-DESIGN.md +2 -2
- package/docs/design/decisions.md +3 -0
- package/docs/design/knowledge-graph.md +1 -1
- package/package.json +1 -1
- package/scripts/smoke-pure.ts +203 -0
- package/scripts/test-full.ts +76 -4
- package/server.json +2 -2
- package/skills/open-memex/SKILL.md +17 -0
- package/src/cli.ts +181 -4
- package/src/config.ts +17 -0
- package/src/graph/extract.ts +276 -0
- package/src/graph/lint.ts +107 -0
- package/src/graph/outline.ts +167 -0
- package/src/graph/queries.ts +143 -0
- package/src/plugin-core.ts +4 -0
- package/src/retrieve/inject.ts +27 -2
- package/src/review.ts +9 -0
- package/src/store/db.ts +8 -2
- package/src/store/graph.ts +293 -0
- package/src/store/sync.ts +6 -2
- package/src/tools/ops.ts +11 -2
package/AGENTS.md
CHANGED
|
@@ -39,6 +39,7 @@ npm run cli -- sync-status # last sync time/kin
|
|
|
39
39
|
npm run cli -- inventory [--format text|json|html] [--scope both] # what is remembered, in the open (D68); personal-bearing output refused inside a git worktree without --allow-personal
|
|
40
40
|
npm run cli -- audit [--scope project|personal|both] # memory health: near-dup pairs, stale actives, broken chains, personal-in-repo, expired working-state notes (read-only)
|
|
41
41
|
npm run cli -- wstate [--clear] # show/clear the session working-state note (D89 §3.6; the file it prints is editable directly)
|
|
42
|
+
npm run cli -- graph build | outline | neighbours <id> | path <a> <b> | lint # D91 structural graph (project scope only; no --scope)
|
|
42
43
|
npm run cli -- pull # fetch + fast-forward only (explicit; diverged = clean failure, never force-merge)
|
|
43
44
|
npm run cli -- push # push current branch to remote (explicit only; open-memex never auto-pushes)
|
|
44
45
|
npm run cli -- export [--scope project|personal|both] [--all] [-o <file>] # portable .tar.gz bundle (markdown + manifest); private excluded unless --all
|
|
@@ -186,11 +187,35 @@ hook today, so the write path is instruction + tool; the tool description,
|
|
|
186
187
|
the surfaced block, the MCP handshake, `init` instructions and the skill must
|
|
187
188
|
keep saying the same thing.
|
|
188
189
|
|
|
190
|
+
**Knowledge graph (D91, §20 deterministic half) — derived, never a source.** `src/store/graph.ts`
|
|
191
|
+
owns `graph_edges`/`graph_meta` (created `IF NOT EXISTS` outside the versioned
|
|
192
|
+
schema, like D77's counters — the graph is rebuildable and disposable). Pure
|
|
193
|
+
logic lives in `src/graph/{extract,outline,queries,lint}.ts`; do not move DB calls
|
|
194
|
+
into them. Edge rules: `supersedes` (from the index's `superseded_by`),
|
|
195
|
+
`derived-from` (from the `derived_from` column — added in index v10),
|
|
196
|
+
body-mention (`[[ULID]]` EXTRACTED / bare ULID INFERRED), shared-tag at the
|
|
197
|
+
fixed ladder 1→low / 2→medium / ≥3→high with per-node/per-set caps. NEVER
|
|
198
|
+
lower a confidence or widen the caps without a measurement — the caps exist so
|
|
199
|
+
one universal tag cannot build an O(n²) edge set. The compiled outline joins
|
|
200
|
+
components **only by medium+ edges** (universal-tag collapse guard; fixture in
|
|
201
|
+
`smoke-pure.ts`) and is injected once at session start (`graphOutline`,
|
|
202
|
+
`graphOutlineLines`; exposure counts as D77 `retrieved`, never useful).
|
|
203
|
+
Every mutating path must call `refreshGraphQuiet` after the write — if you add
|
|
204
|
+
one (new tool, CLI verb, keyword-capture pattern, review transition), add the
|
|
205
|
+
refresh in the same change. The graph covers the cwd's **project** scope only (no `--scope`, personal
|
|
206
|
+
never graphs) and the interface is **CLI only** — the MCP surface stays at
|
|
207
|
+
thirteen tools. `graph lint` reports only (orphans / dangling / stale); an edge
|
|
208
|
+
endpoint that exists in *another* scope is a legitimate foreign link (a propose
|
|
209
|
+
copy's `derived_from`), so lint skips it — pass `loadAllMemoryIds()` as the
|
|
210
|
+
foreign set, never "fix" it by dropping the edge. The LLM half (semantic
|
|
211
|
+
insights, missing-page alerts) is still open in §18 and must propose new memories
|
|
212
|
+
through the normal flow, not write them.
|
|
213
|
+
|
|
189
214
|
## Design constraints — read the frozen design first
|
|
190
215
|
|
|
191
|
-
`docs/V2-DESIGN.md` is the frozen protocol v0.2 (decisions settled through
|
|
216
|
+
`docs/V2-DESIGN.md` is the frozen protocol v0.2 (decisions settled through D91 — log in `docs/design/decisions.md`; open questions tracked at the end of the doc). Per its §12:
|
|
192
217
|
AGENTS.md answers "how should AI work here"; the design doc answers "why is it
|
|
193
|
-
built this way" (principles, iron rules, the append-only decision log in `docs/design/decisions.md`, currently D1–
|
|
218
|
+
built this way" (principles, iron rules, the append-only decision log in `docs/design/decisions.md`, currently D1–D91). Before changing
|
|
194
219
|
architecture, scope semantics, lifecycle, or the protocol surface (frontmatter
|
|
195
220
|
schema, MCP tools, CLI contract), read the relevant design section — the decision
|
|
196
221
|
log records what was already considered and rejected.
|
package/CHANGELOG.md
CHANGED
|
@@ -9,17 +9,15 @@ the `@alpha` tag are development snapshots and are not listed individually.
|
|
|
9
9
|
|
|
10
10
|
## [Unreleased]
|
|
11
11
|
|
|
12
|
-
## [0.9.0
|
|
12
|
+
## [0.9.0] - 2026-11-06
|
|
13
13
|
|
|
14
|
-
-
|
|
15
|
-
|
|
16
|
-
## [0.9.0-alpha.2] - 2026-11-03
|
|
14
|
+
- Session working-state note (D89 → D90, new minor line): one ephemeral per-project Markdown note for resuming an interrupted task — task summary, open files, last commands, where the work stands, next step. The agent writes it at wrap-up via the new **`memory_workingstate`** tool (now the **twelve** tools on both the opencode plugin and the MCP server), it surfaces once at session start next to the first-turn injection (framed as scratch, never knowledge), it never enters `memories/` or the retrieval index or the review ladder, and anything in it worth keeping goes through the normal propose-first flow. TTL defaults to 7 days (`workingStateTtlDays`; `workingStateEnabled` gates the whole feature — both flat keys, settable via `config set`). Expired notes stay silent at session start and are reported by `open-memex audit`; `open-memex wstate` (`--clear`) is the human surface. The write passes through `redact()` and `atomicWriteTextSync` like every path. One correction to D89's wording, recorded as D90: the opencode plugin API has no Stop hook, so the opencode write path is the instruction + tool branch (the agent refreshes the note when the user signals wrap-up); Claude Code's Stop hook waits for the Phase 2C native plugin.
|
|
17
15
|
|
|
18
|
-
- D77-L2: measure usefulness by reuse (the D77 counters, layer 2). Each memory now carries local counters in a `memory_usage` table beside the rebuildable index (D77: counters live in SQLite, never in frontmatter, never off the machine): `retrieved_count` — incremented when a memory is actually returned by `memory_search`, `memory_list`, the CLI `search`/`list`, or the session-start injection — and the useful split, `useful_self` (personal memories and unpublished project drafts) vs `useful_team` (approved/published project memories). Only explicit signals raise the useful side: the new **`memory_useful`** tool (thirteenth MCP tool, seventh on the opencode plugin; also `open-memex useful <id...>`), a human approve at review (`promote` to approved, or the `--local-approve` propose shortcut), and a supersede (recorded even when the index row is momentarily missing — the Markdown file is the source of truth). Passive exposure never counts as useful — the tool description, MCP handshake, READMEs, skill, and AGENTS.md all state the restraint so an agent that reads only one still behaves. `memory_usage` is created with `CREATE TABLE IF NOT EXISTS` outside the versioned schema and survives `rebuildIndexSchema` (ids come from the files); hard forget prunes the row, branch-switch removals do not. `memory_useful` returns counts plus `reuse_rate` (useful / retrieved, `n/a` when never retrieved).
|
|
16
|
+
- D77-L2: measure usefulness by reuse (the D77 counters, layer 2). Each memory now carries local counters in a `memory_usage` table beside the rebuildable index (D77: counters live in SQLite, never in frontmatter, never off the machine): `retrieved_count` — incremented when a memory is actually returned by `memory_search`, `memory_list`, the CLI `search`/`list`, or the session-start injection — and the useful split, `useful_self` (personal memories and unpublished project drafts) vs `useful_team` (approved/published project memories). Only explicit signals raise the useful side: the new **`memory_useful`** tool (thirteenth MCP tool, seventh on the opencode plugin; also `open-memex useful <id...>`), a human approve at review (`promote` to approved, or the `--local-approve` propose shortcut), and a supersede (recorded even when the index row is momentarily missing — the Markdown file is the source of truth). Passive exposure never counts as useful — the tool description, MCP handshake, READMEs, skill, and AGENTS.md all state the restraint so an agent that reads only one still behaves. `memory_usage` is created with `CREATE TABLE IF NOT EXISTS` outside the versioned schema and survives `rebuildIndexSchema` (ids come from the files); hard forget prunes the row, branch-switch removals do not. `memory_useful` returns counts plus `reuse_rate` (useful / retrieved, `n/a` when never retrieved).
|
|
19
17
|
|
|
20
|
-
|
|
18
|
+
- D77-L3: the reuse report — D77's third and final layer. `memory_status` (MCP) and `open-memex sync-status` now end with a **Reuse (D77)** block built from the `memory_usage` counters: per-scope `retrieved` / `useful` rates (personal + this project) with the **useful split shown separately** (`self` vs `team`, as D77 requires — the combined total drives the rate), the **top reused** memories, and **zombies** — retrieved at least once, never confirmed useful, i.e. the decay/prune candidates. Superseded/deprecated entries stay in the lists (their reuse was real) but carry a lifecycle tag like `[superseded]`, so historical data never reads to the agent as current guidance (a supersede itself ticks the old memory). The agent-facing tool result caps each list (cut disclosed, pointing at the CLI); the CLI prints them uncapped. Retracted/archived memories are excluded from both lists but still count toward the scope totals; an empty store gets an honest "no data yet" line instead of a silent section. Rendering is pure (`src/reuse-report.ts`, smoke-tested without SQLite); collection is one join query in `loadReuseReport`. The counters themselves stay local-only SQLite telemetry (D77).
|
|
21
19
|
|
|
22
|
-
-
|
|
20
|
+
- The knowledge graph, deterministic half (D91 → design §20): an automatic, derivation-honest structural graph over project memories, plus a compiled outline injected at session start. `graph build` (`open-memex graph build`) extracts every edge it can *prove* — `relates-to` from `[[wiki-link]]` body mentions (EXTRACTED) and bare-ULID mentions (INFERRED), supersedes chains from the index, derived-from edges from propose copies, and shared-tag co-membership at a fixed confidence ladder (1 shared tag → low, 2 → medium, ≥3 → high, capped at `MAX_SHARED_TAG_EDGES_PER_NODE = 12` per node / 2000 nodes to bound hot-tag blowups) — stores it in `graph_edges`/`graph_meta` beside the rebuildable index, and stamps every edge `extracted` (structural fact) or `inferred` (heuristic) with its derivation receipt. Every mutating path (add/supersede/soft + hard forget on both hosts, keyword capture, propose, review promotion, CLI add/supersede/status/forget) refreshes the graph automatically; statuses are materialized into nodes so `retracted`/`archived` memories imply their edges without custom SQL. The new **`graph outline`** command renders the compiled outline — medium+ confidence components as `topic (n): titles...` lines, bounded by `graphOutlineLines` (default 10) with the cut disclosed — and `open-memex graph outline` output is also injected once at session start next to the working-state note (`graphOutline: false` disables it); outline components are joined **only by medium+ edges** so one universal tag cannot collapse the graph into one mega-topic (fixture-pinned). `graph neighbours <id> [--depth 1-6]` walks BFS with per-edge receipts, `graph path <a> <b>` prints the hop chain (depth 4 default), both failing honestly on unknown ids (D63: findings never invent nodes). `graph lint` reports orphans (active, in no topic, linked to nothing), dangling edges, and near-stale pairs (≥ 0.8 similarity, excluding chains) — reports only, nothing auto-resolved; this report is the input D78's pre-submit lint consumes later. The graph covers the cwd's project scope only (no `--scope` flag; `personal` never graphs). MCP stays at 13 tools — the interface is CLI-only per §20.6. Schema bump: the index gains a `derived_from` column (v10, rebuild-from-Markdown migration). New pure modules (`src/graph/{extract,outline,queries,lint}.ts`) + `src/store/graph.ts`; smoke + full-suite tested (154 pass). The LLM half (abstracted insights, missing-page alerts → new memories) stays open in §18.
|
|
23
21
|
|
|
24
22
|
## [0.8.2] - 2026-10-28
|
|
25
23
|
|
package/README.md
CHANGED
|
@@ -26,6 +26,10 @@ memory on your machine.
|
|
|
26
26
|
a curated multilingual map of equivalents is indexed with every memory at
|
|
27
27
|
write time, so no related wording misses the right answer. Deterministic
|
|
28
28
|
and auditable, no embedding model required.
|
|
29
|
+
- **A map, not just search**: a derived knowledge graph connects your project
|
|
30
|
+
memories — supersedes chains, shared tags, explicit mentions — and injects
|
|
31
|
+
a compiled outline at session start, so the agent sees what's in memory
|
|
32
|
+
without searching. Structural edges only, no LLM.
|
|
29
33
|
|
|
30
34
|

|
|
31
35
|
|
|
@@ -38,6 +42,7 @@ depth once you're up and running.
|
|
|
38
42
|
- [Quick start](#quick-start)
|
|
39
43
|
- [Core concepts](#core-concepts)
|
|
40
44
|
- [Which editors, which features](#which-editors-which-features)
|
|
45
|
+
- [How it compares](#how-it-compares)
|
|
41
46
|
- [Installation](#installation)
|
|
42
47
|
- [Setting up your editor](#setting-up-your-editor)
|
|
43
48
|
- [What `init` changes on your machine](#what-init-changes-on-your-machine)
|
|
@@ -52,6 +57,8 @@ depth once you're up and running.
|
|
|
52
57
|
- [Storage layout](#storage-layout)
|
|
53
58
|
- [Config](#config)
|
|
54
59
|
- [CLI reference](#cli-reference)
|
|
60
|
+
- [Session working state](#session-working-state)
|
|
61
|
+
- [Knowledge graph](#knowledge-graph)
|
|
55
62
|
- [MCP server](#mcp-server)
|
|
56
63
|
- [Scopes, in detail](#scopes-in-detail)
|
|
57
64
|
- [Troubleshooting](#troubleshooting)
|
|
@@ -697,6 +704,8 @@ Defaults:
|
|
|
697
704
|
"injectOnFirstTurn": true, // [OPEN-MEMEX] system-prompt block
|
|
698
705
|
"keywordCaptureEnabled": true,
|
|
699
706
|
"logLevel": "info", // info | debug
|
|
707
|
+
"graphOutline": true, // inject the compiled graph outline at session start
|
|
708
|
+
"graphOutlineLines": 10, // outline length cap (max 30)
|
|
700
709
|
"memoryDir": ".ai/open-memex" // in-repo project-memory dir, relative to repo root
|
|
701
710
|
}
|
|
702
711
|
```
|
|
@@ -708,10 +717,12 @@ setting after install:
|
|
|
708
717
|
open-memex config set keywordCaptureEnabled false
|
|
709
718
|
open-memex config set maxProjectMemories 12
|
|
710
719
|
open-memex config set sync.autoPull true # best-effort pull at MCP session start
|
|
720
|
+
open-memex config set graphOutline false # stop injecting the graph outline
|
|
711
721
|
```
|
|
712
722
|
|
|
713
723
|
Settable keys: `maxProjectMemories`, `maxProfileItems`, `injectOnFirstTurn`,
|
|
714
|
-
`keywordCaptureEnabled`, `captureAliases`, `logLevel`, `memoryDir`,
|
|
724
|
+
`keywordCaptureEnabled`, `captureAliases`, `logLevel`, `memoryDir`,
|
|
725
|
+
`graphOutline`, `graphOutlineLines`, and `sync.autoPull` (a dotted
|
|
715
726
|
key that writes into the nested `sync` object). Full design:
|
|
716
727
|
[docs/V2-DESIGN.md](./docs/V2-DESIGN.md).
|
|
717
728
|
|
|
@@ -854,6 +865,8 @@ open-memex scopes # list project scopes with memory counts
|
|
|
854
865
|
open-memex reindex # rebuild the SQLite index from markdown
|
|
855
866
|
open-memex audit # memory health: duplicate pairs, stale memories, broken chains, expired working-state notes
|
|
856
867
|
open-memex wstate # show the session working-state note (--clear deletes it)
|
|
868
|
+
open-memex graph build # rebuild the knowledge graph (structural edges only; runs automatically on writes)
|
|
869
|
+
open-memex graph lint # orphans, dangling edges, near-duplicate pairs (reports only)
|
|
857
870
|
open-memex migrate --to-v2 [--dry-run] # v1 data → v2 (renames user scope to personal)
|
|
858
871
|
```
|
|
859
872
|
|
|
@@ -881,6 +894,35 @@ open-memex wstate # show the note (age + expiry)
|
|
|
881
894
|
open-memex wstate --clear # delete it
|
|
882
895
|
```
|
|
883
896
|
|
|
897
|
+
## Knowledge graph
|
|
898
|
+
|
|
899
|
+
A derived, rebuildable graph over the **current project's** memories (D91, §20
|
|
900
|
+
deterministic half) — it answers "what is in memory and how is it connected"
|
|
901
|
+
without searching, and it never touches the Markdown source of truth. Structural
|
|
902
|
+
edges only, no LLM: `supersedes` chains, `derived-from` propose copies,
|
|
903
|
+
`[[wiki-link]]` body mentions (EXTRACTED) and bare-ULID mentions (INFERRED),
|
|
904
|
+
and shared-tag co-membership at a fixed
|
|
905
|
+
confidence ladder (1 tag → low, 2 → medium, ≥3 → high). Every edge is marked
|
|
906
|
+
`EXTRACTED` (structural fact) or `INFERRED` (heuristic) with its receipt.
|
|
907
|
+
|
|
908
|
+
The graph refreshes automatically on every memory write. A **compiled outline**
|
|
909
|
+
(medium+ confidence components, capped and cut-disclosed) is injected once at
|
|
910
|
+
session start next to the working-state note; disable it with
|
|
911
|
+
`config set graphOutline false`, tune its length with `graphOutlineLines`
|
|
912
|
+
(default 10, max 30). Personal scope is never graphed.
|
|
913
|
+
|
|
914
|
+
```sh
|
|
915
|
+
open-memex graph build # rebuild now (writes do this automatically)
|
|
916
|
+
open-memex graph outline # the compiled outline, as injected
|
|
917
|
+
open-memex graph neighbours <id> [--depth 1-6] # BFS with per-edge provenance
|
|
918
|
+
open-memex graph path <a> <b> # shortest hop chain, with receipts
|
|
919
|
+
open-memex graph lint [--json] # orphans, dangling edges, near-stale pairs
|
|
920
|
+
```
|
|
921
|
+
|
|
922
|
+
`lint` reports only — nothing is auto-resolved; a human decides. The same report
|
|
923
|
+
is the planned input for D78's pre-submit curation. The interface is CLI-only;
|
|
924
|
+
the MCP surface stays at its thirteen memory tools.
|
|
925
|
+
|
|
884
926
|
## MCP server
|
|
885
927
|
|
|
886
928
|
The same memory tools over the Model Context Protocol, via a stdio server —
|
package/README.zh-CN.md
CHANGED
|
@@ -14,6 +14,7 @@
|
|
|
14
14
|
- **本地优先**:记忆是纯 Markdown 文件(事实来源),外加一个可重建的 SQLite 关键词索引。除非你明确要分享,否则任何东西都不会离开你的机器。
|
|
15
15
|
- **一份记忆,所有助手**:一条命令把几个编辑器都接上,它们共享同一份记忆,不再各存一份互不可见。
|
|
16
16
|
- **精确的同义词检索**:`ship` 找得到 `deploy`,`单点登录` 找得到 `SSO`——一份多语言的精选同义词映射表在写入时展开进索引,任何相关词语都不会漏掉正确答案。确定性、可审计,不需要下载模型。
|
|
17
|
+
- **知识图谱,不只会搜**:一张派生图谱把项目记忆连起来(取代链、共享标签、显式引用),会话开始时注入一份编译大纲——不用搜索就知道记忆里有什么、彼此怎么连。只抽结构边,不调用 LLM。
|
|
17
18
|
|
|
18
19
|

|
|
19
20
|
|
|
@@ -24,6 +25,7 @@
|
|
|
24
25
|
- [快速开始](#快速开始)
|
|
25
26
|
- [核心概念](#核心概念)
|
|
26
27
|
- [编辑器与功能对照](#编辑器与功能对照)
|
|
28
|
+
- [和别的方案比](#和别的方案比)
|
|
27
29
|
- [安装](#安装)
|
|
28
30
|
- [为你的编辑器做设置](#为你的编辑器做设置)
|
|
29
31
|
- [init 到底改了你机器上的什么](#init-到底改了你机器上的什么)
|
|
@@ -38,6 +40,8 @@
|
|
|
38
40
|
- [存储布局](#存储布局)
|
|
39
41
|
- [配置](#配置)
|
|
40
42
|
- [CLI 参考](#cli-参考)
|
|
43
|
+
- [工作状态笔记](#工作状态笔记)
|
|
44
|
+
- [知识图谱](#知识图谱)
|
|
41
45
|
- [MCP 服务器](#mcp-服务器)
|
|
42
46
|
- [作用域详解](#作用域详解)
|
|
43
47
|
- [故障排查](#故障排查)
|
|
@@ -431,6 +435,8 @@ npm install -g open-memex@latest # 或 @alpha
|
|
|
431
435
|
"injectOnFirstTurn": true, // [OPEN-MEMEX] 系统提示块
|
|
432
436
|
"keywordCaptureEnabled": true,
|
|
433
437
|
"logLevel": "info", // info | debug
|
|
438
|
+
"graphOutline": true, // 会话开始时注入图谱编译大纲
|
|
439
|
+
"graphOutlineLines": 10, // 大纲长度上限(最大 30)
|
|
434
440
|
"memoryDir": ".ai/open-memex" // 仓库内项目记忆目录,相对于仓库根
|
|
435
441
|
}
|
|
436
442
|
```
|
|
@@ -441,9 +447,10 @@ npm install -g open-memex@latest # 或 @alpha
|
|
|
441
447
|
open-memex config set keywordCaptureEnabled false
|
|
442
448
|
open-memex config set maxProjectMemories 12
|
|
443
449
|
open-memex config set sync.autoPull true # MCP 会话开始时尽力而为地 pull
|
|
450
|
+
open-memex config set graphOutline false # 不再注入图谱大纲
|
|
444
451
|
```
|
|
445
452
|
|
|
446
|
-
可设置的键:`maxProjectMemories`、`maxProfileItems`、`injectOnFirstTurn`、`keywordCaptureEnabled`、`captureAliases`、`logLevel`、`memoryDir`,以及 `sync.autoPull`(带点的键,写入嵌套的 `sync` 对象)。完整设计:[docs/V2-DESIGN.md](./docs/V2-DESIGN.md)(英文)。
|
|
453
|
+
可设置的键:`maxProjectMemories`、`maxProfileItems`、`injectOnFirstTurn`、`keywordCaptureEnabled`、`captureAliases`、`logLevel`、`memoryDir`、`graphOutline`、`graphOutlineLines`,以及 `sync.autoPull`(带点的键,写入嵌套的 `sync` 对象)。完整设计:[docs/V2-DESIGN.md](./docs/V2-DESIGN.md)(英文)。
|
|
447
454
|
|
|
448
455
|
## CLI 参考
|
|
449
456
|
|
|
@@ -564,6 +571,8 @@ open-memex scopes # 列出各项目作用域及记忆计数
|
|
|
564
571
|
open-memex reindex # 从 markdown 重建 SQLite 索引
|
|
565
572
|
open-memex audit # 记忆健康检查:近重复对、陈旧记忆、断裂的取代链、过期的工作状态笔记
|
|
566
573
|
open-memex wstate # 显示工作状态笔记(--clear 删除)
|
|
574
|
+
open-memex graph build # 重建知识图谱(仅结构边;写入时自动刷新)
|
|
575
|
+
open-memex graph lint # 孤立节点、悬空边、近重复对(只报告,不自动处理)
|
|
567
576
|
open-memex migrate --to-v2 [--dry-run] # v1 数据 → v2(把 user 作用域改名为 personal)
|
|
568
577
|
```
|
|
569
578
|
|
|
@@ -578,6 +587,22 @@ open-memex wstate # 显示笔记(含年龄与到期)
|
|
|
578
587
|
open-memex wstate --clear # 删除
|
|
579
588
|
```
|
|
580
589
|
|
|
590
|
+
## 知识图谱
|
|
591
|
+
|
|
592
|
+
一张派生、可重建的图谱,覆盖**当前项目作用域**的记忆(D91,§20 确定性那一半)——不用搜索就能回答"记忆里有什么、彼此怎么连",且永远不碰 Markdown 真源。只抽取结构边、不调用 LLM:`supersedes` 取代链、`derived-from` propose 副本、`[[wiki-link]]` 正文链接(EXTRACTED)与裸 ULID 提及(INFERRED),以及共享标签的固定置信阶梯(1 个标签 → low,2 个 → medium,≥3 个 → high)。每条边都标注 `EXTRACTED`(结构事实)或 `INFERRED`(启发式)并附推导凭据。
|
|
593
|
+
|
|
594
|
+
图谱在每次写入记忆时自动刷新。一份**编译大纲**(medium+ 置信度的连通分量,带截断披露)会在会话开始时与工作状态笔记一起注入一次;用 `config set graphOutline false` 关闭,`graphOutlineLines` 调长度(默认 10,上限 30)。personal 作用域永不入图。
|
|
595
|
+
|
|
596
|
+
```sh
|
|
597
|
+
open-memex graph build # 立即重建(写入会自动做)
|
|
598
|
+
open-memex graph outline # 编译后的大纲(即注入内容)
|
|
599
|
+
open-memex graph neighbours <id> [--depth 1-6] # BFS,带每条边的来源
|
|
600
|
+
open-memex graph path <a> <b> # 最短跳链,带凭据
|
|
601
|
+
open-memex graph lint [--json] # 孤立节点、悬空边、近陈旧对
|
|
602
|
+
```
|
|
603
|
+
|
|
604
|
+
`lint` 只报告——不自动处理,由人决定。同一份报告就是 D78 提交前策展的既定输入。接口仅限 CLI;MCP 表面保持十三个记忆工具不变。
|
|
605
|
+
|
|
581
606
|
## MCP 服务器
|
|
582
607
|
|
|
583
608
|
同一组记忆工具,走 Model Context Protocol、经 stdio 服务器提供——不需要任何宿主专用插件。任何 MCP 客户端都能用 open-memex。
|
package/dist/.build-stamp
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
|
|
1
|
+
1a872598f56a092aab47264914caf532b86c553e96a92f73333742e4e0d9588b
|
package/dist/cli.js
CHANGED
|
@@ -19,6 +19,9 @@ import { loadConfig, configSource } from "./config.js";
|
|
|
19
19
|
import { paths, projectRoot, isInRepoMemoryFile } from "./paths.js";
|
|
20
20
|
import { redact } from "./redact.js";
|
|
21
21
|
import { readWorkingState, clearWorkingState, workingStatePath } from "./working-state.js";
|
|
22
|
+
import { refreshGraph, refreshGraphQuiet, ensureGraph, loadGraphEdges, loadGraphNodes, loadAllMemoryIds } from "./store/graph.js";
|
|
23
|
+
import { graphNeighbours, shortestPath } from "./graph/queries.js";
|
|
24
|
+
import { lintGraph } from "./graph/lint.js";
|
|
22
25
|
import { resolveMcpCommand } from "./init.js";
|
|
23
26
|
import fs from "node:fs";
|
|
24
27
|
import path from "node:path";
|
|
@@ -421,6 +424,31 @@ Flags:
|
|
|
421
424
|
|
|
422
425
|
Example:
|
|
423
426
|
open-memex audit --scope both`,
|
|
427
|
+
graph: `Work with the compiled memory graph (§20, D88/D91) — a derived layer
|
|
428
|
+
of structural edges between memories, rebuilt from the Markdown source of
|
|
429
|
+
truth, never hand-edited.
|
|
430
|
+
|
|
431
|
+
Usage:
|
|
432
|
+
open-memex graph build rebuild edges + the compiled outline for this project
|
|
433
|
+
open-memex graph neighbours <id> [--depth N] neighbours via BFS (default 1, max 6)
|
|
434
|
+
open-memex graph path <idA> <idB> [--depth N] shortest path (default 4, max 6)
|
|
435
|
+
open-memex graph lint [--json] health check: orphans, dangling refs, stale chains
|
|
436
|
+
open-memex graph outline print the compiled outline as it is injected
|
|
437
|
+
|
|
438
|
+
Every hop reports its edge type, provenance and confidence — EXTRACTED
|
|
439
|
+
means the link was explicit in the source (a supersede chain, a
|
|
440
|
+
derived-from copy, or the body mentioning the other memory's id);
|
|
441
|
+
INFERRED means the system noticed it (shared tags). Inferred links are
|
|
442
|
+
suggestions, never facts that were in the source.
|
|
443
|
+
|
|
444
|
+
Writes (add / supersede / forget / propose / promote) refresh the graph
|
|
445
|
+
automatically; graph build is the manual repair. Lint only reports.
|
|
446
|
+
|
|
447
|
+
Examples:
|
|
448
|
+
open-memex graph build
|
|
449
|
+
open-memex graph neighbours 01ABC --depth 2
|
|
450
|
+
open-memex graph path 01ABC 01DEF
|
|
451
|
+
open-memex graph lint`,
|
|
424
452
|
wstate: `Show the project's session working-state note (D89, §3.6) — the
|
|
425
453
|
ephemeral scratch note the agent refreshes at wrap-up so an interrupted task
|
|
426
454
|
can resume. The file itself is plain Markdown and editable directly.
|
|
@@ -460,6 +488,7 @@ Usage:
|
|
|
460
488
|
open-memex pr-status [--apply]
|
|
461
489
|
open-memex reindex
|
|
462
490
|
open-memex audit [--scope project|personal|both]
|
|
491
|
+
open-memex graph <build|neighbours <id>|path <a> <b>|lint|outline> [--depth N] [--json]
|
|
463
492
|
open-memex wstate [--clear]
|
|
464
493
|
open-memex scopes
|
|
465
494
|
open-memex migrate [--from <key>] [--to <key>]
|
|
@@ -818,6 +847,135 @@ async function main() {
|
|
|
818
847
|
}
|
|
819
848
|
return;
|
|
820
849
|
}
|
|
850
|
+
// D91: the graph surface (§20 deterministic half). Project scope only —
|
|
851
|
+
// the graph covers the cwd's project scope like every other command;
|
|
852
|
+
// no --scope flag exists because personal has no reader this iteration.
|
|
853
|
+
if (cmd === "graph") {
|
|
854
|
+
const sub = rest[0] ?? "";
|
|
855
|
+
const flags = parseFlags(rest.slice(1));
|
|
856
|
+
// --depth is opt-in per command: neighbours defaults to 1, path to 4,
|
|
857
|
+
// and an explicit flag is clamped to [1, 6]. Absent = undefined so the
|
|
858
|
+
// default reads cleanly where it is applied.
|
|
859
|
+
const depth = (() => {
|
|
860
|
+
if (flags.depth === undefined || flags.depth === "true")
|
|
861
|
+
return undefined;
|
|
862
|
+
const n = Number(flags.depth);
|
|
863
|
+
if (!Number.isInteger(n) || n < 1 || n > 6)
|
|
864
|
+
return undefined;
|
|
865
|
+
return n;
|
|
866
|
+
})();
|
|
867
|
+
const syncThen = (fn) => {
|
|
868
|
+
syncScope(project.key, "cli");
|
|
869
|
+
fn();
|
|
870
|
+
};
|
|
871
|
+
if (sub === "build") {
|
|
872
|
+
syncThen(() => {
|
|
873
|
+
const s = refreshGraph(project.key, cfg);
|
|
874
|
+
console.log(`graph built for ${s.scopeKey}: ${s.nodes} memories, ${s.edges} edges, ` +
|
|
875
|
+
`${s.topics} topic(s), outline ${s.outlineLines} line(s)`);
|
|
876
|
+
});
|
|
877
|
+
return;
|
|
878
|
+
}
|
|
879
|
+
if (sub === "neighbours") {
|
|
880
|
+
const id = rest[1];
|
|
881
|
+
if (!id)
|
|
882
|
+
usage();
|
|
883
|
+
syncThen(() => {
|
|
884
|
+
ensureGraph(project.key, cfg);
|
|
885
|
+
const nodes = loadGraphNodes(project.key);
|
|
886
|
+
if (!nodes.some((n) => n.id === id)) {
|
|
887
|
+
console.error(`neighbours: no memory with id ${id} in scope ${project.key} — graph findings never invent nodes.`);
|
|
888
|
+
process.exit(1);
|
|
889
|
+
}
|
|
890
|
+
const hits = graphNeighbours(id, loadGraphEdges(project.key), nodes.map((n) => n.id), {
|
|
891
|
+
maxDepth: depth ?? 1,
|
|
892
|
+
});
|
|
893
|
+
if (hits.length === 0) {
|
|
894
|
+
const status = nodes.find((n) => n.id === id).status;
|
|
895
|
+
console.log(status === "active"
|
|
896
|
+
? `no structural neighbours within depth ${depth ?? 1} — this memory is currently an orphan (see \`graph lint\`).`
|
|
897
|
+
: `no structural neighbours within depth ${depth ?? 1} for this ${status} memory.`);
|
|
898
|
+
return;
|
|
899
|
+
}
|
|
900
|
+
for (const h of hits) {
|
|
901
|
+
const n = nodes.find((x) => x.id === h.id);
|
|
902
|
+
console.log(`- ${h.id} (depth ${h.depth}) ${h.via.type} ${h.via.provenance}/${h.via.confidence} (${h.via.via})` +
|
|
903
|
+
` [${n.status}] ${n.body.replace(/\s+/g, " ").trim().slice(0, 120)}`);
|
|
904
|
+
}
|
|
905
|
+
});
|
|
906
|
+
return;
|
|
907
|
+
}
|
|
908
|
+
if (sub === "path") {
|
|
909
|
+
const a = rest[1];
|
|
910
|
+
const b = rest[2];
|
|
911
|
+
if (!a || !b)
|
|
912
|
+
usage();
|
|
913
|
+
syncThen(() => {
|
|
914
|
+
ensureGraph(project.key, cfg);
|
|
915
|
+
const nodes = loadGraphNodes(project.key);
|
|
916
|
+
for (const id of [a, b]) {
|
|
917
|
+
if (!nodes.some((n) => n.id === id)) {
|
|
918
|
+
console.error(`path: no memory with id ${id} in scope ${project.key}.`);
|
|
919
|
+
process.exit(1);
|
|
920
|
+
}
|
|
921
|
+
}
|
|
922
|
+
const p = shortestPath(a, b, loadGraphEdges(project.key), nodes.map((n) => n.id), {
|
|
923
|
+
maxDepth: depth ?? 4,
|
|
924
|
+
});
|
|
925
|
+
if (!p.found) {
|
|
926
|
+
console.log(`no path found between ${a} and ${b} within depth ${depth ?? 4}. Weaker links (single shared tags) exist outside the built edge cap — \`graph neighbours\` per side may still connect them.`);
|
|
927
|
+
return;
|
|
928
|
+
}
|
|
929
|
+
console.log(`${a} [${nodes.find((n) => n.id === a).status}]`);
|
|
930
|
+
for (const h of p.hops) {
|
|
931
|
+
console.log(` --(${h.type} ${h.provenance}/${h.confidence} via ${h.via})-->`);
|
|
932
|
+
console.log(`${h.to} [${nodes.find((n) => n.id === h.to).status}]`);
|
|
933
|
+
}
|
|
934
|
+
});
|
|
935
|
+
return;
|
|
936
|
+
}
|
|
937
|
+
if (sub === "lint") {
|
|
938
|
+
syncThen(() => {
|
|
939
|
+
ensureGraph(project.key, cfg);
|
|
940
|
+
// Cross-scope ids (e.g. a propose copy's personal original) are not
|
|
941
|
+
// findings — lint skips endpoints the store knows about.
|
|
942
|
+
const f = lintGraph(loadGraphNodes(project.key), loadGraphEdges(project.key), loadAllMemoryIds());
|
|
943
|
+
const counts = {
|
|
944
|
+
orphan: 0,
|
|
945
|
+
"dangling-edge": 0,
|
|
946
|
+
stale: 0,
|
|
947
|
+
};
|
|
948
|
+
for (const x of f)
|
|
949
|
+
counts[x.kind]++;
|
|
950
|
+
if (flags.json === "true") {
|
|
951
|
+
console.log(JSON.stringify({ findings: f, counts }, null, 2));
|
|
952
|
+
return;
|
|
953
|
+
}
|
|
954
|
+
console.log(`graph lint (${project.key}): ${f.length} finding(s) — orphans ${counts.orphan}, dangling ${counts["dangling-edge"]}, stale ${counts.stale}. Reports only — a human decides; nothing is auto-resolved.`);
|
|
955
|
+
for (const x of f) {
|
|
956
|
+
console.log(` [${x.kind}] ${x.id}${x.other ? ` ↔ ${x.other}` : ""}: ${x.detail}`);
|
|
957
|
+
}
|
|
958
|
+
if (f.length > 0) {
|
|
959
|
+
console.log(`feed these to the review flow when curating; D78's pre-submit lint consumes the same report later.`);
|
|
960
|
+
}
|
|
961
|
+
});
|
|
962
|
+
return;
|
|
963
|
+
}
|
|
964
|
+
if (sub === "outline") {
|
|
965
|
+
syncThen(() => {
|
|
966
|
+
const g = ensureGraph(project.key, cfg);
|
|
967
|
+
if (!g || !g.outline) {
|
|
968
|
+
console.log("no compiled outline for this scope yet — `graph build` creates one.");
|
|
969
|
+
return;
|
|
970
|
+
}
|
|
971
|
+
console.log(`outline built ${g.builtAt} (${g.nodes} memories / ${g.edges} edges):`);
|
|
972
|
+
for (const line of g.outline.split("\n"))
|
|
973
|
+
console.log(line);
|
|
974
|
+
});
|
|
975
|
+
return;
|
|
976
|
+
}
|
|
977
|
+
usage();
|
|
978
|
+
}
|
|
821
979
|
// `config` prints the effective configuration (defaults + file). No DB needed.
|
|
822
980
|
// `config set <key> <value>` persists a setting to the config file.
|
|
823
981
|
if (cmd === "config") {
|
|
@@ -1081,6 +1239,8 @@ async function main() {
|
|
|
1081
1239
|
const mf = readMemoryFile(filePath);
|
|
1082
1240
|
if (mf)
|
|
1083
1241
|
upsertFromFile(mf);
|
|
1242
|
+
// D91 ingest: refresh the project graph quietly (personal no-ops inside).
|
|
1243
|
+
refreshGraphQuiet(s.key, cfg);
|
|
1084
1244
|
console.log(`saved ${fm.id} [${s.kind}] -> ${filePath}`);
|
|
1085
1245
|
if (hadSecret) {
|
|
1086
1246
|
console.log(`warning: content matched secret pattern (${matchedPattern}); saved with the secret masked (first 4 chars kept).`);
|
|
@@ -1114,6 +1274,7 @@ async function main() {
|
|
|
1114
1274
|
});
|
|
1115
1275
|
upsertFromFile(oldMf);
|
|
1116
1276
|
upsertFromFile(newMf);
|
|
1277
|
+
refreshGraphQuiet(oldMf.fm.scope_key, cfg);
|
|
1117
1278
|
console.log(`superseded ${oldMf.fm.id} → ${newMf.fm.id}`);
|
|
1118
1279
|
if (hadSecret) {
|
|
1119
1280
|
console.log(`warning: content matched secret pattern (${matchedPattern}); saved with the secret masked (first 4 chars kept).`);
|
|
@@ -1133,6 +1294,7 @@ async function main() {
|
|
|
1133
1294
|
try {
|
|
1134
1295
|
const mf = setStatus(id, st);
|
|
1135
1296
|
upsertFromFile(mf);
|
|
1297
|
+
refreshGraphQuiet(mf.fm.scope_key, cfg);
|
|
1136
1298
|
console.log(`status ${id} → ${mf.fm.status}`);
|
|
1137
1299
|
}
|
|
1138
1300
|
catch (e) {
|
|
@@ -1148,10 +1310,11 @@ async function main() {
|
|
|
1148
1310
|
// D68: --soft hides (retracts) instead of deleting — same action as
|
|
1149
1311
|
// the memory_forget tool's soft flag. One-way (D64).
|
|
1150
1312
|
if (rest.includes("--soft")) {
|
|
1151
|
-
const target = db().prepare(`SELECT file_path FROM memories WHERE id = ?`).get(id);
|
|
1313
|
+
const target = db().prepare(`SELECT file_path, scope_key FROM memories WHERE id = ?`).get(id);
|
|
1152
1314
|
try {
|
|
1153
1315
|
const mf = setStatus(id, "retracted");
|
|
1154
1316
|
upsertFromFile(mf);
|
|
1317
|
+
refreshGraphQuiet(mf.fm.scope_key, cfg);
|
|
1155
1318
|
console.log(`hidden ${id} (retracted — out of lists and search; save it again as a new memory to bring it back)`);
|
|
1156
1319
|
// D70: same honesty as the hard delete — a retraction of an in-repo
|
|
1157
1320
|
// memory is a local working-tree edit until it is committed and pushed.
|
|
@@ -1165,7 +1328,7 @@ async function main() {
|
|
|
1165
1328
|
}
|
|
1166
1329
|
return;
|
|
1167
1330
|
}
|
|
1168
|
-
const row = db().prepare(`SELECT file_path FROM memories WHERE id = ?`).get(id);
|
|
1331
|
+
const row = db().prepare(`SELECT file_path, scope_key FROM memories WHERE id = ?`).get(id);
|
|
1169
1332
|
if (!row) {
|
|
1170
1333
|
console.error("not found");
|
|
1171
1334
|
process.exit(1);
|
|
@@ -1186,6 +1349,8 @@ async function main() {
|
|
|
1186
1349
|
}
|
|
1187
1350
|
}
|
|
1188
1351
|
deleteFromIndex(id);
|
|
1352
|
+
// D91 ingest: the node left the graph — refresh its scope quietly.
|
|
1353
|
+
refreshGraphQuiet(row.scope_key);
|
|
1189
1354
|
// D77-L2: hard forget prunes the usage row with the memory (the tool
|
|
1190
1355
|
// path does the same); branch-switch removals go through syncScope and
|
|
1191
1356
|
// keep counters for that reason.
|
package/dist/config.js
CHANGED
|
@@ -9,6 +9,8 @@ export const DEFAULT_CONFIG = {
|
|
|
9
9
|
captureAliases: true,
|
|
10
10
|
workingStateEnabled: true,
|
|
11
11
|
workingStateTtlDays: 7,
|
|
12
|
+
graphOutline: true,
|
|
13
|
+
graphOutlineLines: 10,
|
|
12
14
|
keywordPatterns: [
|
|
13
15
|
"^\\s*remember(?!\\s+for\\s+me)(?:\\s+that|\\s+to)?[:,]?\\s+(.+)$",
|
|
14
16
|
"^\\s*(?:please\\s+)?note(?:\\s+that)?[:,]?\\s+(.+)$",
|
|
@@ -159,6 +161,15 @@ export const SETTABLE_KEYS = {
|
|
|
159
161
|
throw new Error("must be a positive integer (days)");
|
|
160
162
|
return n;
|
|
161
163
|
},
|
|
164
|
+
graphOutline: toBool,
|
|
165
|
+
graphOutlineLines: (v) => {
|
|
166
|
+
const n = toNonNegInt(v);
|
|
167
|
+
if (n < 1)
|
|
168
|
+
throw new Error("must be a positive integer (topic lines)");
|
|
169
|
+
if (n > 30)
|
|
170
|
+
throw new Error("must be 30 or less — the injected outline stays compact");
|
|
171
|
+
return n;
|
|
172
|
+
},
|
|
162
173
|
memoryDir: toRelativeDir,
|
|
163
174
|
"sync.autoPull": toBool,
|
|
164
175
|
logLevel: (v) => {
|