dsh-loci 0.0.0-stage → 2.0.1

package/CHANGELOG.md

@@ -0,0 +1,321 @@
+# Changelog
+
+All notable changes to this project are documented here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/); the project follows
+[Semantic Versioning](https://semver.org/spec/v2.0.0.html) from 1.0.0.
+
+## [2.0.1] — 2026-11-14
+
+### Changed
+
+- **Publishing now uses Trusted Publishing (OIDC) only.** `setup-node` no longer
+  receives `registry-url` and the publish step no longer reads `NODE_AUTH_TOKEN`:
+  the collaboration center's npm runbook records both as `ENEEDAUTH` traps, and
+  with a Trusted Publisher bound, the OIDC identity token is the credential. The
+  repository therefore holds no npm secret.
+- `release.yml` gained an `npm >= 11.5` check, because npm 10 never performs the
+  OIDC exchange.
+
+### Note
+
+`2.0.0` was the bootstrap publish (npm does not allow a first publish over OIDC,
+[npm/cli#8544](https://github.com/npm/cli/issues/8544)), so it carries no
+attestation. **2.0.1 is the first version with a provenance attestation.**
+
+## [2.0.0] — 2026-11-14
+
+### Added
+
+- **`loci doctor` now looks for near-duplicates.** Two entries that say the same
+  thing split the ranking, each take an index line, and force a correction to be
+  applied twice. The check reports groups with their ids and a similarity score, and
+  leaves the merge to a person (the store can already do it: `loci_write op:'merge'`).
+
+  The metric is `max(Jaccard, containment)` over character bigrams. Jaccard alone
+  scores a restated Chinese title at 0.55 — under any useful threshold — because the
+  two titles share most of the *shorter* one rather than most of the union. The scan
+  is bounded (verified heads only, ≤2000 entries, candidate pairs from shared tags
+  and title windows, report capped at 5 groups).
+
+- `test/unit/duplicates.test.mjs`: the metric, the verified-only rule, the clean
+  store, the caps, and the doctor row.
+
+### Changed
+
+- `publishConfig.access: "public"` is set in the manifest, so a direct `npm publish`
+  cannot accidentally create a private package.
+
+### Note
+
+This is the last item from the audit's "ten improvements" list: rows 1–3 and 5–10
+are done, and row 2's remaining gap (duplicate detection) closed here. The version
+jumps to 2.0.0 because the feature set that list described is complete, not because
+anything in the on-disk format broke — schemas and the tool surface are unchanged.
+
+## [1.9.0] — 2026-11-14
+
+### Added
+
+- **Candidate-only background extraction** (`extractMode: 'on'`, **off by default**).
+  The deterministic capture layer only records statements that announce themselves
+  ("always", "never", "we agreed"). A preference stated in passing — "honestly I'd
+  rather see the diff first" — carries no such marker and was lost. With the feature
+  on, the recent conversation is sent to the configured model at turn end and the
+  answers land as **candidates** for review.
+
+  Four rules keep it from becoming the feature a user turns off:
+  - off unless `extractMode: 'on'`, and inert when the profile has no `llm` route
+    (reports `no-model`, writes nothing);
+  - candidates only — an extracted preference can never reach the prompt by itself;
+  - budgeted: `extractMaxCallsPerHour` (6), `extractMaxCandidates` (3),
+    `extractTimeoutMs` (20 s), and a 12 KB input cap. Exhausting the budget is
+    silent, not an error;
+  - it can always fail: timeout, provider error, unparseable answer or an invented
+    quote all return `{written: 0, reason}` on its own timer, never touching the
+    turn. A quote that is not in the transcript is dropped before storage.
+
+- `test/unit/extractor.test.mjs` covers the switch, the missing route, the budget,
+  the timeout, invented quotes and the unusable-answer paths.
+
+### Unverified
+
+- The `ctx.llm` adapter is written against the Host's `llm.stream(request)` call and
+  collects text from whatever frame shape the provider emits. **It has not been run
+  against a live provider**; the unit tests use a fake completer and a fake stream.
+  If a provider's chunk shape is not one of the recognised forms, the extractor
+  records `model-error` and stays out of the way — it does not write junk.
+
+## [1.8.0] — 2026-11-14
+
+### Added
+
+- **Import bridges** for the memory plugins a user is likely leaving
+  (`dsh-loci import --from auto-memory|claude`, `POST /api/loci/import-peer`,
+  `--dry-run` to preview):
+  - **dsh-auto-memory**: reads one Markdown file per memory with its front matter
+    (`name/title/type/disabled/evidence`). `_user/` becomes global scope, each
+    `--<project>--/` directory keeps its own scope key, `type: feedback` maps to
+    `procedural`, and disabled or already-superseded entries are skipped.
+  - **Claude Code memory**: reads `MEMORY.md`'s links plus every topic file that
+    is not in the index, so a hand-added file is not silently lost.
+  - everything lands as a **candidate**: another plugin's trust level is not
+    evidence here, and the source file is recorded as `sourceRef`.
+  - format details were taken from the producer's own serializer, not guessed;
+    `@tr1v3r/dsh-ltm` is deliberately not read (private SQLite schema) and the
+    operations guide says why.
+
+### Fixed
+
+- A **byte-order mark** in front matter silently disabled parsing: the whole file
+  became body text and the entry imported with a filename-derived title. A BOM is
+  now stripped before the fence is matched, with a regression test.
+
+## [1.7.0] — 2026-11-14
+
+### Added
+
+- **`sourceRef`**: a fact can cite where it lives (`src/host/store.js:120`).
+  - accepted by `loci_write`, stored with the evidence (the quote and the citation
+    are both provenance), returned by `loci_get` as a `source:` line, shown under
+    **Source** in the panel detail, and written to the export front matter so a
+    round trip keeps it;
+  - flattened and capped at 160 characters like every other free-text field;
+  - a citation that trips the secret scanner is dropped rather than stored;
+  - it never raises trust: a model-written entry with a citation is still a
+    candidate, because knowing where something is written down does not make it
+    true.
+
+## [1.6.0] — 2026-11-14
+
+### Added
+
+- **`merge`** (`loci_write` with `op:'merge'`, `store.merge()`, `POST /api/loci/merge`).
+  Two entries that say the same thing in different words split the ranking, each
+  take an index line, and force a correction to be applied twice. Write-time dedupe
+  only catches byte-identical or same-title writes, so the realistic case — written
+  months apart, different wording — now has an explicit operation:
+  - the sources are **superseded, never deleted**: their history stays readable and
+    `loci_get` keeps working;
+  - tags and entities are unioned, so the merged entry keeps both entries'
+    searchability;
+  - an optional `expectedRevisions` list aborts the whole merge on a stale
+    expectation, before anything is written;
+  - a merge that changes the text re-opens verification (the target lands as a
+    candidate), because trust is bound to the words that were confirmed;
+  - one `merge` audit line names both sides.
+
+## [1.5.0] — 2026-11-14
+
+### Fixed
+
+- **`--json doctor` printed the help text and exited 2.** Flags are now
+  position-independent: `--json doctor` and `doctor --json` are the same thing.
+- **`snapshots` was unreachable** — its block sat after the switch, so it never ran.
+  It is a real command now, alongside a new `snapshot [--label <name>]` that writes
+  one consistent `VACUUM INTO` file under `backups/`.
+- **`stats` reported the current directory's scope only.** Running it from another
+  directory showed "0 entries" for a store with entries in it. Diagnostics default
+  to the whole store; `--session` narrows to the current scope set.
+- **The audit log accepted arbitrary prose** in a delete `reason`. It is now capped
+  and scanned by the same secret detector as memory bodies.
+- **`assertInside` was lexical**: a symlink inside the data directory passed the
+  prefix check and then wrote wherever the link pointed. It now also resolves the
+  deepest existing part of the path and requires that to stay inside, with a test
+  that skips on a host that cannot create symlinks.
+
+### Changed
+
+- CI and the release workflow install with **`npm ci`** from a committed
+  `package-lock.json`.
+- The release workflow refuses a tag whose commit is not an ancestor of `main`,
+  publishes prereleases to the **`next`** dist-tag, and runs the coverage gate
+  before publishing.
+- The coverage gate now fails on **lines (<80), branches (<55) and functions
+  (<70)**, and prints all three; before, only lines were checked while branches sat
+  at 62%.
+- CI installs the packed tarball and runs its `bin`, so a broken `files` list or
+  shebang fails the build instead of a user's terminal.
+- `docs/OPERATIONS.md` shows the exact way to invoke the CLI from an installed
+  profile (`node <profile>/node_modules/dsh-loci/scripts/cli.mjs`), documents the
+  `/loci` slash commands, and replaces the "no snapshot command" note.
+
+## [1.4.0] — 2026-11-14
+
+### Fixed
+
+- **`export` then `import` imported nothing.** The exporter wrote entries under
+  `<root>/markdown/<scope>/<kind>/` and a one-line summary under
+  `<root>/exports/`; the importer read `exports`. The default is now the tree that
+  holds the documents, and the original scope and scope key are restored from the
+  front matter instead of forcing every import into `workspace:imported`.
+- The CLI granted itself `allowHardDelete`; it now honours the config, with
+  `--allow-hard-delete` as the explicit opt-in for one invocation.
+- `cli.mjs` read the version from four hardcoded strings; it now reads
+  `package.json`.
+
+### Added
+
+- `store.forgetAll()`: soft (or hard, with `allowHardDelete`) deletion of one scope
+  or the whole store, gated by an echoed confirmation phrase, one audit line per
+  entry. `POST /api/loci/forget-all` exposes it, and **Settings → Delete
+  everything** asks for the phrase before running.
+- `test/unit/export.test.mjs` (round trip, scope restore, path guard) and
+  `test/unit/forget-all.test.mjs` (confirmation, hard-delete gate, scope limit).
+
+## [1.3.0] — 2026-11-14
+
+### Changed
+
+- **A captured statement verifies itself.** With capture on by default, every
+  durable-sounding sentence the user said landed in the review queue and was never
+  injected — while the same words, written by the model with a quote, went straight
+  through. A captured statement now passes the same quote gate as a model-supplied
+  quote: if its sentence is still in the session buffer it is verified, otherwise it
+  stays a candidate. Imports and session summaries never verify themselves.
+- `autoVerifyCaptured` (default `true`) keeps the old behaviour for a cautious user.
+- The review queue lists only the kinds that could be injected, so past-session
+  summaries stop pretending to be pending decisions.
+
+### Added
+
+- Reject, verify-all, and a visible error line in the review queue; a failed click
+  now says so instead of disappearing into `console.warn`.
+
+## [1.2.0] — 2026-11-14
+
+### Changed
+
+- **The sidebar card is a page of notes, not a dashboard.** Counters ("4 today",
+  "4 this week") are gone. The card now shows `更新于 <time>` over one short
+  paragraph made of the few things the agent currently understands in this
+  project — a consensus, a lesson, a fact — so reading it answers "did it
+  actually take that in?" instead of "did the number go up?".
+  Ordering is by when an entry last *became* trustworthy (`verified_at`, falling
+  back to the last edit), so confirming an old entry today puts it at the top.
+- The card is scoped to the current project's read set, not to every scope in the
+  store: it answers "what does this conversation's agent know".
+- Pending entries are mentioned as one line of text ("still need your review"),
+  never as a badge count.
+
+### Added
+
+- `buildKnowledge` + `GET /api/loci/knowledge`: verified entries as notes, with a
+  first-sentence `gist` that is withheld when it merely restates the title.
+- `test/unit/knowledge.test.mjs`: notes exclude candidates, respect scope, carry
+  the moment they became true, and re-order on a fresh confirmation.
+
+## [1.1.0] — 2026-11-13
+
+### Added
+
+- **Sidebar mirror** (`sidebar.footer.action`): a flat card beside Settings that
+  shows what memory changed today and in the last seven days, the last three
+  changes as one-line entries, pending-review count, the installed version in small
+  text, and an explicit "check for updates" that is the only path that touches the
+  network.
+- **Feed tab** in the panel: every add, revision, verification, pin, deletion,
+  restore, import and maintenance pass, newest first, with the entry it touched.
+- **`/api/loci/activity`**, **`/api/loci/update`**, **`/api/loci/version`** — the
+  owner-only endpoints behind those two surfaces; the activity feed carries ids,
+  titles and counts, never bodies.
+- **Update checker** (`src/host/update.js`): six-hour cache, 4-second timeout, and
+  "unavailable" on any failure instead of an error state. It never installs
+  anything; upgrading stays a decision made in the plugin manager.
+
+### Changed
+
+- The panel opens on the **Feed** tab (was Index), because "what changed" is the
+  question a user actually arrives with.
+- Version text follows the ecosystem convention: `v1.1.0` at 10px in the card,
+  and a quiet version line in the Stats tab.
+- Removed the `build:client` script: the client half is hand-authored
+  module-loader JavaScript, so there was nothing to build and the entry was broken.
+
+### Fixed
+
+- (pending) findings from the four independent production-readiness audits.
+
+## [1.0.0] — 2026-11-13
+
+First release.
+
+### Added
+
+- **Layered memory** with five kinds (`rule`, `semantic`, `procedural`, `episodic`,
+  `working`), where `working` is never injected.
+- **Bi-temporal facts**: `valid_from` / `valid_to` for event time and `recorded_at`
+  for transaction time; edits append a revision and close the previous one instead
+  of overwriting it. `loci_search(asOf)` answers "what was true then".
+- **One injected section** (`loci:index`, order 4000, `interpolate:false`),
+  byte-budgeted (default 3,584 B), stable across read-only turns, empty on an empty
+  store.
+- **Five tools**: `loci_write`, `loci_search`, `loci_get`, `loci_forget`,
+  `loci_stats`. Search returns `total`, `hasMore` and a cursor; pagination reaches
+  everything it counts.
+- **Hybrid retrieval**: CJK bigram full text + entity expansion + optional vectors,
+  ranked in process with a coverage admission rule (no `bm25()` scan, no prefix
+  query). Measured p95 12.5 ms at 10,000 entries.
+- **Trust gate**: only `verified` entries are injected; status is derived from a
+  verbatim quote found in the user's live messages, never declared by the model.
+- **Scope isolation**: `session` / `workspace` / `project` / `global`, explicit keys,
+  `workspace` default, `global` only on request.
+- **Deterministic capture**: durable statements become candidates after a completed
+  turn; a session summary is written when a root agent is disposed. No background
+  model call.
+- **Safety**: `{{}}` neutralization, markup escaping, instruction-shape quarantine,
+  credential redaction, fenced injection, audit without content.
+- **Native UI**: a settings page and a four-tab sidebar panel (Index, Search,
+  Review, Stats) built on the Host's slots and theme tokens, with `zh`/`en` strings.
+- **Owner-only JSON API** for the panel, over the Host's exact-fetch routes.
+- **Optional MCP facade** (`src/mcp/server.js`), read-only by default.
+- SQLite store with WAL, busy timeout, snapshot migration and rollback, Markdown
+  export/import, `dsh-loci` CLI, `/loci` command.
+
+### Known limits
+
+- No LLM consolidation (v1.1 candidate).
+- Deterministic capture only records explicitly phrased durable statements.
+- Vector search is brute-force cosine over stored embeddings.
+- Plaintext at rest; no encryption beyond the OS.
+
+[1.0.0]: https://github.com/Awenforever/dsh-loci/releases/tag/v1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Awenforever
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/NOTICE

@@ -0,0 +1,31 @@
+dsh-loci
+Copyright (c) 2026 Awenforever
+SPDX-License-Identifier: MIT
+
+Third-party material
+--------------------
+
+No third-party source code is vendored in this package. The design cites the
+following work for specific mechanisms; see docs/RESEARCH.md for the exact
+section and URL behind each claim.
+
+- Graphiti / Zep — bi-temporal edge model and edge invalidation
+  (arXiv 2501.13956). Mechanism reimplemented from the published description.
+- Mem0 — multi-signal retrieval with BM25 as a boost signal, and write-time
+  temporal metadata (arXiv 2504.19413; docs.mem0.ai). Mechanism reimplemented.
+- Cognee — current / superseded / conflicting fact marks and an all-local
+  default storage stack (docs.cognee.ai). Mechanism reimplemented.
+- MemOS — layered memory vocabulary and the local RRF/MMR plugin as an
+  existence proof (arXiv 2505.22101, arXiv 2507.03724). Vocabulary only.
+- OpenViking — L0/L1 context layer sizes and session-start budget discipline
+  (docs.openviking.ai). Budgets reimplemented.
+- ReMe — guidance-only injection into DSH and read-only on-demand retrieval
+  (agentscope-ai/ReMe, reme.agentscope.io). Product-level pattern, no code.
+- memsearch — Markdown-as-truth with a rebuildable shadow index, and the
+  low-risk-only project configuration rule (zilliztech/memsearch). Pattern only.
+- Letta / MemGPT — core vs archival memory vocabulary (docs.letta.com).
+- Claude Code, Cursor, ChatGPT — product documentation reviewed for what to
+  adopt and what not to copy.
+
+Runtime dependencies: `@deepseek-ai/schemastery` (MIT), used for the
+plugin configuration schema. It is not modified.

package/README.md

@@ -1,3 +1,144 @@
-# Temporary Holding Version
+# dsh-loci · Loci 记忆宫殿
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+**A long-term memory for DeepSeek Harness where the prompt only ever sees the palace's index — every room is one lookup away.**
+
+[中文](README.zh.md) · [Design](docs/DESIGN.md) · [Research](docs/RESEARCH.md) · [Operations](docs/OPERATIONS.md) · [Security](docs/SECURITY.md) · [Acceptance](docs/ACCEPTANCE.md)
+
+```
+system prompt:  ~1.3k tokens, stable, one line per fact
+user asks     →  loci_search "发布顺序"   → total=3, one call
+needs detail  →  loci_get m_01J…           → full text + history + evidence
+```
+
+## Why it exists
+
+Every memory plugin tested in this workspace failed one of two ways: it cost a
+fixed toll on every request (mnemon: +4.8 KB of system prompt, 16 tools), or it
+grew without bound (ledger-memory: 7 KB → 27 KB per turn). The ones that stayed
+cheap truncated recall silently (mnemon returned 4 of 20 requested rows;
+auto-memory's index holds about 27 Chinese entries).
+
+Loci is built around one rule: **the prompt holds an index, not a memory.**
+
+- Empty store → **0 bytes injected**. No header, no advice, nothing.
+- 100 entries → still one stable section, capped at a byte budget with an honest
+  "… +N more" footer.
+- A read-only turn → the section is byte-identical, so the prefix cache survives.
+- A broad question → `loci_search` returns `total` and a cursor, so "list them
+  all" is answerable.
+
+## What it remembers
+
+![The sidebar note and the memory panel](marketplace/screenshots/sidebar-note.png)
+
+| Layer | Kind | Injected? | Example |
+|---|---|---|---|
+| rules | `rule` | yes, first | "删除前必须做路径断言" |
+| semantic | `semantic` | yes, index line | "生产机是 prod-01" |
+| procedural | `procedural` | yes, index line | "发布顺序 staging → canary → 全量" |
+| episodic | `episodic` | yes, index line | "2026-11-13 会话摘要" |
+| working | `working` | no | scratch facts for this session only |
+
+Only `verified` entries are injected. Anything written without a verbatim quote
+from the conversation is stored as a **candidate** and waits in the panel for
+one click.
+
+## Install
+
+Inside the Harness profile that should have memory:
+
+```text
+Settings → Plugins → install from a directory or the market listing, or
+dsh plugin --profile <name> add dsh-loci
+```
+
+The bundle adds one Host row (`dsh-loci`) and one Client half. Restart the
+Harness, then open **Settings → Loci** or the **Memory** panel in the sidebar.
+
+Requirements: DSH `>=0.2.2-rc.1 <0.3.0-0`, Node `>=24.9.0` (the Harness ships it).
+No service and no native module.
+
+The package also ships a small CLI (`snapshot`, `export`, `import`, `doctor`,
+`stats`, `review`, `purge`, `migrate`, `rollback`). It is not on your `PATH` after a
+plugin install — call it through the profile:
+
+```text
+node "$HOME/.dsh/profiles/<profile>/node_modules/dsh-loci/scripts/cli.mjs" doctor --json
+```
+
+Inside a chat there are zero-token slash commands too: `/loci`, `/loci review`,
+`/loci doctor`, `/loci export`.
+
+## The five tools
+
+| Tool | Use |
+|---|---|
+| `loci_write` | Save, revise, or merge facts. `evidenceQuote` must be verbatim; without it the entry is a candidate. `op:'merge'` folds duplicate ids into one — the sources are superseded, never deleted. |
+| `loci_search` | Hybrid search. Returns `total`, `hasMore`, `cursor`; `detail` is snippet/overview/full. Omit `query` to list the newest entries. |
+| `loci_get` | Full text plus revision history and the evidence quote. |
+| `loci_forget` | Soft-delete (history kept) or restore. |
+| `loci_stats` | Counts, budget use, channel health, database location. |
+
+Tool names are prefixed `loci_` on purpose: `ctx.tools.register` throws on a
+duplicate name, so two memory plugins both claiming `memory_search` would break
+one of them.
+
+## Where you see it
+
+- **Sidebar note** — a small card beside Settings, like the quota and advisor
+  cards, that reads like a page of notes rather than a dashboard: `更新于 <time>`
+  over one short paragraph of what the agent currently understands in this
+  project (a consensus, a lesson, a fact), plus one quiet line if something is
+  waiting for your review. It answers "did it take that in?" — no counters.
+  The version sits in small text with an explicit "check for updates", the only
+  path that touches the network.
+- **Memory panel** — the full view, opening on a **Feed** of every add, revision,
+  verification, pin, deletion and import, newest first.
+- **Settings → Loci** — the budget, capture mode, default scope, secret policy
+  and embedding channel.
+
+## Configuration
+
+Everything lives in the plugin's Loader row; Loci never reads a project file.
+The settings page writes the fields marked *live* without a restart.
+
+| Key | Default | Meaning |
+|---|---|---|
+| `sectionMaxBytes` | `3584` | hard byte budget for the injected section (max 16384) |
+| `rulesMaxBytes` | `1024` | ceiling for the rules block inside that budget |
+| `defaultScope` | `workspace` | scope a write lands in when it does not say |
+| `captureMode` | `rules` | deterministic capture of explicit durable statements |
+| `extractMode` | `off` | `on` asks the configured model, at turn end, what is worth remembering — always as candidates, always budgeted |
+| `recallAssist` | `off` | one bounded first-turn recall block per session |
+| `maintenanceMode` | `sweep` | TTL, index repair, and embedding backfill every 6h |
+| `secretPolicy` | `redact` | redact high-confidence secrets, or refuse the write |
+| `vectorMode` | `off` | optional HTTP embedding channel; lexical always works |
+| `allowHardDelete` | `false` | enable `purge` in the CLI/panel |
+
+## What it will not do
+
+- No model call in any automatic path in v1.0 — capture and summaries are
+  deterministic, so the cost is visible and zero.
+- No cloud, no telemetry, no network unless you configure `vectorMode: 'http'`.
+- No cross-project leakage: reads use an explicit scope-key set, never a wildcard.
+- No physical deletion by default; `purge` needs a config switch, a confirmation,
+  and leaves an audit line.
+
+## Data
+
+`$DSH_HOME/memory/loci/` only:
+
+```
+memory.db            SQLite (WAL) — the transactional truth
+audit.jsonl          append-only: inject / recall / write / verify / delete
+backups/             pre-migration and manual snapshots (VACUUM INTO)
+markdown/            human-readable projection
+exports/             export bundles and import drops
+```
+
+Uninstalling the plugin leaves the directory untouched, by design. Delete it
+yourself when you mean it.
+
+## License
+
+MIT. See [NOTICE](NOTICE) for the research lineage of each mechanism.

package/README.zh.md

@@ -0,0 +1,111 @@
+# dsh-loci · Loci 记忆宫殿
+
+**给 DeepSeek Harness 的长期记忆：提示词里只放「宫殿的索引」，每个房间按需推门。**
+
+[English](README.md) · [设计](docs/DESIGN.md) · [调研](docs/RESEARCH.md) · [运维](docs/OPERATIONS.md) · [安全](docs/SECURITY.md) · [验收](docs/ACCEPTANCE.md)
+
+```
+系统提示：  约 1.3k tokens，稳定，一条记忆一行
+你问：      → loci_search "发布顺序"  → total=3，一次调用
+要细节：    → loci_get m_01J…         → 全文 + 历史 + 逐字证据
+```
+
+## 为什么需要它
+
+本机实测过的记忆插件，要么在每次请求上交固定「税」（mnemon：系统提示 +4.8KB、16 个工具），要么无界增长（ledger-memory：每轮 7KB 涨到 27KB）。便宜的又都在静默截断召回（mnemon 要 20 条只回 4 条；auto-memory 的索引约 27 条中文就触顶）。
+
+Loci 只有一条规则：**提示词里放索引，不放记忆。**
+
+- 空库 → **注入 0 字节**，没有标题、没有说明、什么都没有。
+- 100 条 → 仍是同一段，硬字节预算，超出时明确写出「… 还有 N 条」。
+- 只读回合 → 段内容逐字节不变，前缀缓存得以保留。
+- 宽泛提问 → `loci_search` 返回 `total` 和 cursor，「列出全部」真的能列完。
+
+## 它记什么
+
+| 层 | kind | 是否注入 | 例子 |
+|---|---|---|---|
+| 硬约束 | `rule` | 是，排最前 | 「删除前必须做路径断言」 |
+| 事实 | `semantic` | 是，索引一行 | 「生产机是 prod-01」 |
+| 流程 | `procedural` | 是，索引一行 | 「发布顺序 staging → canary → 全量」 |
+| 经历 | `episodic` | 是，索引一行 | 「2026-11-13 会话摘要」 |
+| 工作记忆 | `working` | 否 | 只在本次会话有效的草稿事实 |
+
+只有 `verified` 会被注入。写入时若没有来自对话的逐字引文，条目落为 **candidate**，在面板里等你点一下。
+
+## 安装
+
+在需要有记忆的 profile 里：
+
+```text
+设置 → 插件 → 从目录或市场条目安装，或
+dsh plugin --profile <名字> add dsh-loci
+```
+
+bundle 会插入一行 Host 插件（`dsh-loci`）和一个 Client 半边。重启 Harness，然后打开 **设置 → Loci** 或侧栏的 **记忆** 面板。
+
+侧栏底部还有一张**便签**（和额度、advisor 卡片并排），它不是看板：顶上 `更新于 <时间>`，下面一小段话，是它此刻真正理解的东西——达成的共识、踩过的经验、事实。没有数字，看到的就是"它有没有把这件事接住"。
+
+要求：DSH `>=0.2.2-rc.1 <0.3.0-0`，Node `>=24.9.0`（Harness 自带）。无服务、无原生模块。
+
+包里还带一个小 CLI（`snapshot`/`export`/`import`/`doctor`/`stats`/`review`/`purge`/`migrate`/`rollback`）。插件安装后它不在 PATH 上，按 profile 调用：
+
+```text
+node "$HOME/.dsh/profiles/<profile>/node_modules/dsh-loci/scripts/cli.mjs" doctor --json
+```
+
+会话里还有零 token 的斜杠命令：`/loci`、`/loci review`、`/loci doctor`、`/loci export`。
+
+## 五个工具
+
+| 工具 | 用途 |
+|---|---|
+| `loci_write` | 写入、修订或合并事实。`evidenceQuote` 必须逐字；没有就落为候选。`op:'merge'` 把重复条目折进一条——源条目被 supersede，不删除。 |
+| `loci_search` | 混合检索，返回 `total`、`hasMore`、`cursor`；`detail` 可选 snippet/overview/full。 |
+| `loci_get` | 全文 + 修订历史 + 证据引文。 |
+| `loci_forget` | 软删除（历史保留）或恢复。 |
+| `loci_stats` | 计数、预算占用、通道健康、库位置。 |
+
+工具名用 `loci_` 前缀是有意的：`ctx.tools.register` 同名会抛错，两个记忆插件都叫 `memory_search` 必然坏一个。
+
+## 配置
+
+配置只存在于插件自己的 Loader 行；Loci **不读项目内配置文件**。设置页里标注「即时」的字段无需重启。
+
+| 键 | 默认 | 含义 |
+|---|---|---|
+| `sectionMaxBytes` | `3584` | 注入段的硬字节预算（上限 16384） |
+| `rulesMaxBytes` | `1024` | 段内规则块的字节上限 |
+| `defaultScope` | `workspace` | 未显式指定时的写入作用域 |
+| `captureMode` | `rules` | 规则型捕获用户的明确约定 |
+| `extractMode` | `off` | 设为 `on` 时，在回合结束让模型提一遍「这轮有什么值得记」——一律落为候选，且有预算上限 |
+| `recallAssist` | `off` | 每会话一次、有上限的首轮辅助召回块 |
+| `maintenanceMode` | `sweep` | 每 6 小时做 TTL、索引修复、向量补齐 |
+| `secretPolicy` | `redact` | 高置信密钥脱敏，或直接拒绝写入 |
+| `vectorMode` | `off` | 可选 HTTP 向量通道；词法检索始终可用 |
+| `allowHardDelete` | `false` | 是否允许 CLI/面板里的 `purge` |
+
+## 它明确不做
+
+- v1.0 的自动路径里没有模型调用 —— 捕获与摘要是确定性的，成本可见且为零。
+- 无云、无遥测；除非你配置 `vectorMode: 'http'`，否则不出网。
+- 不跨项目串味：读取用显式 scope-key 集合，从不通配。
+- 默认不物理删除；`purge` 需要配置开关 + 确认 + 留审计。
+
+## 数据位置
+
+只在 `$DSH_HOME/memory/loci/`：
+
+```
+memory.db            SQLite（WAL），事务真源
+audit.jsonl          追加写：inject / recall / write / verify / delete
+backups/             迁移前与手动快照（VACUUM INTO）
+markdown/            人类可读投影
+exports/             导出包与导入投递目录
+```
+
+卸载插件不会删除这个目录（有意为之）；真要删请自己动手。
+
+## 许可
+
+MIT。每个机制的研究出处见 [NOTICE](NOTICE)。