open-memex 0.9.0-alpha.6 → 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 +2 -2
- package/CHANGELOG.md +5 -9
- package/README.md +7 -0
- package/README.zh-CN.md +4 -0
- package/package.json +1 -1
- package/server.json +2 -2
package/AGENTS.md
CHANGED
|
@@ -213,9 +213,9 @@ through the normal flow, not write them.
|
|
|
213
213
|
|
|
214
214
|
## Design constraints — read the frozen design first
|
|
215
215
|
|
|
216
|
-
`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:
|
|
217
217
|
AGENTS.md answers "how should AI work here"; the design doc answers "why is it
|
|
218
|
-
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
|
|
219
219
|
architecture, scope semantics, lifecycle, or the protocol surface (frontmatter
|
|
220
220
|
schema, MCP tools, CLI contract), read the relevant design section — the decision
|
|
221
221
|
log records what was already considered and rejected.
|
package/CHANGELOG.md
CHANGED
|
@@ -9,19 +9,15 @@ the `@alpha` tag are development snapshots and are not listed individually.
|
|
|
9
9
|
|
|
10
10
|
## [Unreleased]
|
|
11
11
|
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
## [0.9.0-alpha.3] - 2026-11-04
|
|
15
|
-
|
|
16
|
-
- 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).
|
|
12
|
+
## [0.9.0] - 2026-11-06
|
|
17
13
|
|
|
18
|
-
|
|
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.
|
|
19
15
|
|
|
20
|
-
- 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).
|
|
21
17
|
|
|
22
|
-
|
|
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).
|
|
23
19
|
|
|
24
|
-
-
|
|
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.
|
|
25
21
|
|
|
26
22
|
## [0.8.2] - 2026-10-28
|
|
27
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)
|
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
|
- [故障排查](#故障排查)
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "open-memex",
|
|
3
|
-
"version": "0.9.0
|
|
3
|
+
"version": "0.9.0",
|
|
4
4
|
"mcpName": "io.github.stoneskin/open-memex",
|
|
5
5
|
"description": "Local-first memory layer and protocol for AI coding agents. Markdown source of truth, SQLite FTS5 index, zero cloud.",
|
|
6
6
|
"keywords": [
|
package/server.json
CHANGED
|
@@ -3,7 +3,7 @@
|
|
|
3
3
|
"name": "io.github.stoneskin/open-memex",
|
|
4
4
|
"title": "open-memex",
|
|
5
5
|
"description": "Local-first memory for AI coding agents — Markdown + SQLite FTS5, shared across editors via MCP.",
|
|
6
|
-
"version": "0.
|
|
6
|
+
"version": "0.9.0",
|
|
7
7
|
"repository": {
|
|
8
8
|
"url": "https://github.com/stoneskin/open-memex",
|
|
9
9
|
"source": "github"
|
|
@@ -13,7 +13,7 @@
|
|
|
13
13
|
{
|
|
14
14
|
"registryType": "npm",
|
|
15
15
|
"identifier": "open-memex",
|
|
16
|
-
"version": "0.
|
|
16
|
+
"version": "0.9.0",
|
|
17
17
|
"runtimeHint": "npx",
|
|
18
18
|
"packageArguments": [
|
|
19
19
|
{
|