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

index · inject · list · search · show · store · forget · review · draft · map · gather · global-sync · stats · doctor · usage

🧩 PLUGIN/DSH-MEMORY · DEEPSEEK HARNESS PLUGIN (new in 0.3.0)

mem_recall · mem_save · /memory recall|save|doctor|review|map|stats|draft

   ╔══════════════════════════════════════════════════════════════╗
   ║   📕  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 15-command CLI + plugin

Contents — What's new in 0.3.0 · Why · Features · Two ways to run · Entry format · Commands · Architecture · Security · Roadmap

🆕 What's new in 0.3.0

Plugin Edition. The lesson book now runs natively inside DeepSeek Harness — same zero-dependency engine, two delivery faces:

Full details in CHANGELOG.md and plugin/README.md.

🌟 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-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).

🚀 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

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

That one command mounts the whole trio (prompt injection · mem_recall / mem_save · /memory) and survives destructive reinstalls. Two dependencies are materialized by junction/link first — exact 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, 15 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)

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

📂 Repository Anatomy

cross-session-memory/
├── README.md · README.zh-CN.md · README.zh-TW.md · README.ar.md · README.vi.md
├── LICENSE · CHANGELOG.md · .gitignore
├── tools/
│   ├── mem.mjs            # the 15-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
│   ├── 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. This book writes nothing without a human — in the plugin, mem_save returns ask on every call, and a never approval policy refuses it outright.

🗺 Roadmap

• 🧩 0.3.x — plugin polish: tools/result write telemetry, nightly review timer, strict wiki-link validation (M2)
• 🌱 0.4 — session CJK search fallback patch · client memory panel · ctx.skills · bigram synonym packs · mem map SVG export (M3)
• 🌍 later — optional multi-book federation · CLI i18n (--lang)
• 🚫 Won't do — vector stores · gateways · silent auto-write. Triggers documented in docs/DESIGN.md.

🤝 Contributing

PRs welcome — especially new lesson packs (sanitized!) and README translations. 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.                    ║
  ║      错题本 · sổ lỗi · دفتر الدروس · lesson book          ║
  ╚═══════════════════════════════════════════════════════════╝