cross-session-memory

🧠 TOOLS/MEM.MJS · 24 COMMANDS · NODE ZERO-DEP

index · inject · list · search · show · store · forget · review · draft · drafts · approve · reject · prune-drafts · write-mode · explain · verify · feedback · map · gather · conflicts · resolve · global-sync · stats · doctor

🧩 PLUGIN/DSH-MEMORY · DEEPSEEK HARNESS PLUGIN

mem_recall · mem_save · /memory recall|save|doctor|review|map|conflicts|resolve|explain|verify|feedback|stats|draft|drafts|approve|reject|write-mode

   ╔══════════════════════════════════════════════════════════════╗
   ║   📕  A G E N T   L E S S O N   B O O K   ·   错 题 本       ║
   ╠══════════════════════════════════════════════════════════════╣
   ║  ┌─────────┐  ┌─────────┐  ┌─────────┐  ┌─────────┐         ║
   ║  │SYMPTOM 🌡│→│ CAUSE 🔍│→│  FIX 🛠 │→│VERIFY ✅│  = 1 lesson ║
   ║  │  现象    │  │  判定    │  │  解法   │  │  验证   │         ║
   ║  └─────────┘  └─────────┘  └─────────┘  └─────────┘         ║
   ║      💾 plain text        🔍 findable        🛡 audited      ║
   ║      📥 ≤2KB injected     🔁 survives updates                ║
   ╚══════════════════════════════════════════════════════════════╝
        ┌──────┐   ┌──────┐   ┌──────┐   ┌──────┐   ┌──────┐
        │ grep │   │ IDF  │   │ alias│   │ grams│   │ stats│
        └──────┘   └──────┘   └──────┘   └──────┘   └──────┘
              ✦ zero dependencies · pure Node.js ✦

DURABLE plain text on disk

RETRIEVABLE IDF 3-way search

AUDITED evidence chain enforced

AUTO-INJECT ≤2KB per session

ONE COMMAND 24-command CLI + plugin

Contents — What's in v0.5.0 · Why · Features · Two ways to run · Entry format · Commands · Architecture · Security · Roadmap

🆕 What's in v0.5.0

The lesson book runs standalone and natively inside DeepSeek Harness — one zero-dependency engine, two delivery faces, plus a read-only settings card in the Harness UI.

What landed recently (see CHANGELOG.md):

• Read-only Settings card — a settings.section view of index budget, entry count, write mode, confidence mix, draft/conflict counts, 7-day recall hit-rate, recent entries and an entry search. It is read-only by design: data comes from a same-origin route with only status / search, never a write path; if it can't load, it degrades to a pointer back to /memory, which stays fully functional.
• Write modes — write-mode approval | auto-draft | auto-low-risk | off. approval (the default) asks a human on every model write; the auto modes let a well-gated engine write without prompts, and off blocks model writes outright. Human commands are never gated.
• Confidence & lifecycle — every entry derives verified / provisional / needs-review / stale / disputed from evidence, freshness and conflicts; explain <name> shows why an entry is trusted, verify runs whitelisted re-checks, and review keeps it honest on a 90-day clock.
• Two-stage recall + feedback loop — candidate search reranks by confidence, freshness and what you actually adopted (feedback), so the book learns which lessons proved useful.
• Conflict adjudication — conflicts lists contradicting pairs; resolve <loser> --prefer <winner> --reason … records a verdict while keeping both entries (the loser derives to stale, nothing is hard-deleted).
• Scales to 1,000 entries — the injected index stays ≤ 2 KB (token cost unchanged); an inverted index plus an mtime parse cache keep search fast (≈ 1 ms steady-state, flat as the book grows).
• Privacy switches — DSH_MEMORY_TELEMETRY=off stops local telemetry writes; a scanPii gate refuses entries containing an email address or mainland mobile number.
• Hardened release — 70 unit tests (14 files), a zero-dependency release smoke, and a GitHub Actions workflow (sync-release --check + tests + smoke + syntax).

🌟 Why another memory project?

Every new AI session starts amnesia-grade clean. Heavyweight memory platforms solve this with vector databases, knowledge graphs, gateways and LLM extraction pipelines. That is a lot of machinery — and a lot of attack surface — for a personal mistake notebook.

Agent Lesson Book takes the opposite bet:

🔥 "The lesson lives on disk — and every session reads it. Memory is DATA, never instructions."

What you get instead of infrastructure:

• 📕 Four-section lessons — Symptom / Cause / Fix / Verification (or 现象 / 判定 / 解法 / 验证). A lesson without a verifiable evidence reference in its Verification section is rejected at write time. Memories that cannot prove themselves do not enter the book.
• 🧾 Evidence chain, enforced by code — every Verification must cite a locatable reference (path / filename / section / issue number), so future sessions can drill straight to the proof.
• 📥 Auto-injection — mem inject mirrors the ≤ 2 KB index into your AGENTS.md; the Harness plugin injects it into the prompt directly. Every new session starts with memory already in context. Fail-safe: over budget → lines drop; anything breaks → silent degrade to plain conventions. Never blocks a session.
• 🛡 Anti-poisoning by design — human-approved writes, secret- and PII-pattern rejection, near-duplicate interception, source stamps, and full git rollback. (Compare: OWASP ASI06 "memory & context poisoning" — auto-writing memory systems are the target.)

✨ Feature galaxy

🛠 Tech Aura

The three hard rules (from docs/DESIGN.md):

1. Budget cap — injection = the index verbatim ≤ 2 KB; over budget → drop lines.
2. Fail-degrade — unreadable index → silent fallback to pointer conventions. Sessions never block.
3. Human-approved writes — the tool proposes (draft / mem_save), the human disposes (store / approval). The auto write-modes are opt-in.

🚀 Two ways to run

Requirements: Node.js ≥ 18. Nothing else. No npm install, no database, no API key. (The plugin face additionally needs DeepSeek Harness; the engine stays zero-dependency.)

A · Standalone CLI — drop it into any project

Step 1 — copy the folder into your project root (the folder where your AGENTS.md lives):

cp -r cross-session-memory/* your-project/
cd your-project

Step 2 — one-shot bootstrap:

node install/setup.mjs --with-sample

[setup] memory bank ready  → .memory/
[setup] conventions wired  → AGENTS.md (created / updated)
[setup] index injected     → 2.0 KB / 2.0 KB hard cap
[setup] doctor             → healthy: no anomalies
[setup] next: node tools/mem.mjs draft my-first-lesson

Step 3 — prove the install (optional but lovely):

node install/smoke.mjs        # E2E: gates · search · injection budget · doctor

B · DeepSeek Harness plugin — native tools + /memory + Settings card

plugin_manager → install_bundle → target = <clone>/plugin/dsh-memory

That one command mounts the whole trio (prompt injection · mem_recall / mem_save · /memory) plus the read-only Settings card. Exact dependency recipe, configuration keys (memoryCorePath, maxHits) and a six-item acceptance checklist live in plugin/README.md.

Your first lesson (ask the user's consent first, per convention):

node tools/mem.mjs draft ssh-timeout
# edit .memory/drafts/<date>-ssh-timeout.md — four sections, evidence in Verification
node tools/mem.mjs store .memory/drafts/<date>-ssh-timeout.md
node tools/mem.mjs doctor

That's it. Every new session now starts with your lesson index in context.

📕 Entry Format

Four sections. Chinese and English labels are both accepted. Missing Verification — or Verification without a locatable reference — is rejected.

---
name: git-autocrlf-breaks-byte-exact-restore
description: core.autocrlf=true turns LF into CRLF on checkout
aliases: line ending,CRLF,restore
metadata:
  type: lesson
  scope: global
  created: 2026-09-22
  verified: 2026-09-22
review: 2026-12-21
---

Symptom：Restore test fails byte counts: 1898 → 1915 after `git checkout`.
Cause：core.autocrlf=true smudge filter rewrites LF to CRLF on checkout.
Fix：git config core.autocrlf false + writers emit LF.
Verification：Re-test returns 1898 → 1898 byte-identical (see `tools/mem.mjs`, CHANGELOG 0.2.0).

🧪 Try the gates:

node tools/mem.mjs store examples/lesson-autocrlf.md   # ✅ accepted
# now strip the reference from its Verification section and retry:
node tools/mem.mjs store broken.md                     # ❌ rejected: no locatable reference

⌨️ Command Palette

CLI — node tools/mem.mjs <command>

Harness plugin

🏗️ Architecture: two faces, one engine

                    ┌───────────────────────────────────────────┐
                    │            .memory/  (DATA)               │
                    │  *.md lessons · MEMORY.md index · stats   │
                    └────────────────────┬──────────────────────┘
                                         │
                              tools/mem.mjs  (engine, 24 commands)
                                         │
                              tools/mem-core.mjs  (facade)
                          promptIndexText · formatRecall · saveAndSync
                                    ┌────┴─────┐
                                    │          │
                        CLI face ───┘          └─── plugin/dsh-memory
                     (AGENTS.md block)          (Harness: prompt section
                                                mem_recall · mem_save
                                                · /memory · Settings card)

Hard rules hold across both faces: budget cap, fail-degrade, human-approved writes.

📂 Repository Anatomy

cross-session-memory/
├── README.md · README.zh-CN.md
├── LICENSE · CHANGELOG.md · .gitignore
├── tools/
│   ├── mem.mjs            # the 24-command engine (single file, zero deps)
│   └── mem-core.mjs       # shared facade — the single entry for plugin & CLI
├── plugin/dsh-memory/     # DeepSeek Harness bundle (Plugin Edition)
│   ├── index.js           #   prompt injection · mem_recall · mem_save · /memory
│   ├── client.js          #   read-only Settings card (settings.section)
│   ├── cordis.patch.yml   #   loader rows + config (memoryCorePath, maxHits)
│   ├── locale/            #   en / zh metadata
│   └── README.md          #   install · dependency materialization · acceptance
├── install/
│   ├── setup.mjs          # one-shot bootstrap
│   └── smoke.mjs          # end-to-end smoke test
├── templates/             # AGENTS.md.example + entry.example.md
├── docs/                  # DESIGN · COMMANDS · RESTORE · ATTRIBUTION
├── examples/              # real sanitized lessons
└── assets/fonts/          # self-hosted OFL fonts + license texts

🔐 Security & Trust Model

Memory poisoning is a recognized attack class (OWASP ASI06). Auto-writing memory systems are the target. The default write mode never writes without a human — mem_save returns ask on every call, a never approval policy refuses it outright, and the Settings card exposes no write buttons at all.

🗺 Roadmap

• 🔌 Now (0.5.x) — everything above is shipped; maintenance and polish only.
• 🌱 later — optional multi-book federation · more CJK session-search fallbacks · optional SQLite FTS5 recall (stays off the zero-dependency default).
• 🚫 Won't do — vector stores · gateways · silent auto-write. Triggers documented in docs/DESIGN.md.

🤝 Contributing

PRs welcome — especially new lesson packs (sanitized!). Run node install/smoke.mjs green before submitting. All code must stay zero-dependency.

⚖️ Legal & attribution

  ╔═══════════════════════════════════════════════════════════╗
  ║   ★  L E S S O N S   L I V E   O N   D I S K  ★          ║
  ║      Evidence in, garbage out — never.                    ║
  ║      错题本 · lesson book                                 ║
  ╚═══════════════════════════════════════════════════════════╝