dsh-soul-forging 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 memory-kit contributors
+
+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.md

@@ -0,0 +1,15 @@
+# 来源说明
+
+## 本套件
+
+代码为本项目重写实现（MIT）。
+
+## 思路参考
+
+- [dsh-plugin-memory](https://github.com/LittleBlackTong/dsh-plugin-memory) —— MIT。
+  本项目**没有复制它的源代码**；如果你把那个插件装进 DSH 使用，请单独保留它自己的 LICENSE 与版权声明。
+  本套件受它启发的地方：markdown 记忆库 + 每轮注入 + index 路由表这一整套思路。
+
+## 用到的第三方
+
+无。只需要 Python 标准库和（可选的）curl。

package/README.md

@@ -1,3 +1,206 @@
-# Temporary Holding Version
+# dsh-soul-forging
 
-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.
+**Separate Vessels, One Heart** · 异体同心
+
+给 AI 的可迁移长期记忆，外加一套「铸魂」流程——让性格不是写死的设定，而是一点点长出来的东西。
+
+纯本地。一个 Python 3 就能跑。不需要服务器、不需要数据库。
+
+```bash
+soul-init                              # 铺一份空白记忆库
+dsh plugin add dsh-soul-forging        # 装进 DSH，记忆自动注入
+```
+
+---
+
+## 为什么叫「异体同心」
+
+因为同一个 AI 可以有两个入口：一个在手机上跟你聊天，一个在群里应声，一个在你电脑上干活。
+它们说的话、记得的事，本该是**同一个人**的。
+
+大多数做法是把它们拆成两个实例、两套记忆、两个「人」——然后你就得开始解释"为什么另一个她不知道这件事"。
+
+这个项目的前提是反过来的：**身体可以有多个，心只有一颗。**
+记忆库是那颗心，谁都能读写；`source` 字段记着这条是从哪个入口写进来的，但不影响它是谁。
+
+拆开，就散了。
+
+---
+
+## 它解决什么
+
+大模型每开一次会话就是一张白纸。这东西给它三样东西：
+
+1. **记得** —— 要紧的落在 markdown 里，下次开局自动注入
+2. **查得到** —— 记忆多了塞不进上下文，用「小脑」按关键词现查，几毫秒
+3. **能长** —— 性格靠经历一点点变，而且变得有据可查（哪句话养出了哪一条）
+
+一句话：**该记的记，该忘的忘，该查的查。**
+
+---
+
+## 三层，不是三个功能
+
+| 层 | 在哪 | 谁读 |
+|---|---|---|
+| **注入层** | `SOUL.md` `MEMORY.md` `index.md` `NOW.md` | 每轮都读，所以必须短 |
+| **检索层（小脑）** | `brain/entries.json` | 想起来才查 |
+| **外置层** | `docs/tech` `docs/debug` | 不进上下文，出错才翻 |
+
+对应到时间上：
+
+| | 文件 | 怎么维护 |
+|---|---|---|
+| **短期** | `NOW.md` | 每次收尾刷三节 |
+| **中期** | `log.md` `diary/` `live.jsonl` | `soul write` 写；`archive-log` 瘦身 |
+| **长期** | `SOUL.md` `core/` `identity/` | 铸魂建立；`persona-sediment` 提示回炼 |
+
+**遗忘是设计的一部分。** `salience:1` 几乎不忘，`3` 会自己淡掉；被反复想起的变牢。
+特意找回的会**钉住**，不再淡。
+
+---
+
+## 装
+
+### A. 当 DSH 插件（记忆自动注入）
+
+```bash
+soul-init                        # 铺空白记忆库到 ~/.soul-forging/memory
+dsh plugin add dsh-soul-forging  # 装进 profile
+# 重开 DSH，记忆就自动带上了
+```
+
+### B. 只要命令行（不装插件）
+
+```bash
+git clone https://github.com/Fqingwan/dsh-soul-forging
+cd dsh-soul-forging && bash install.sh
+```
+
+两种都**不需要服务器**。想换记忆位置：设 `MEMORY_DIR`，或插件配置里改 `memoryDir`。
+
+---
+
+## 用
+
+```bash
+# 写
+soul write "内容" --kind chat --section 小标题
+
+# 查
+soul-recall "关键词"              # 查小脑
+soul-recall --topics              # 看有哪些分类
+soul digest                       # 收尾该做哪四步
+
+# 养
+brain/fix-live-summary.py         # 补摘要（缺摘要 = 只记得"有这么回事"）
+archive-log                       # 时间线瘦身（老的进 archive，照样搜得到）
+soul-compact                      # 预算体检：注入层多大、该压哪
+persona-sediment                  # 性格沉淀：攒够了提示回炼进底色
+growth-review                     # 叙事回炼：碎片连成「我这一路」
+
+# 忘
+soul-forget                       # 报告该忘了哪些（按强度衰减）
+soul-forget --apply               # 真标记（**不删原文**）
+soul-forget --restore <id>        # 找回，并钉住
+
+# 保底
+soul-snapshot save "说明"         # 存一卷
+soul-snapshot ls / restore / diff
+
+# 双端
+soul-peer export | import / pull / push
+
+# 收尾
+soul-sync                         # 补摘要 → 瘦身 → 建索引 → 重载 → 体检
+```
+
+---
+
+## 铸魂
+
+装完的第一件事不是干活，是**先把"我是谁"聊清楚**。
+
+打开 `memory/BOOTSTRAP.md`，一项项来：名字、性格、价值观、边界、主人是谁、想要什么样的陪伴。
+**一次推进一项**——一口气问完那是问卷，不是聊天。
+
+写回文件之后才勾选。全部完成 → `status: complete` + `soul-sync`。
+
+想重来：把 `status` 改回 `pending`，**已有记忆不会被清掉**——重铸的是性格，不是记忆。
+
+---
+
+## 接进别的 agent
+
+这套东西不会自己长在模型身上，你得在每轮开头把记忆喂进去。
+
+```bash
+soul-boot                 # 打印注入块，拼到 system prompt 最前面
+soul-boot --budget 12000  # 限字数（超了从末尾截，先保 SOUL）
+```
+
+或者当 Python 模块：
+
+```python
+from soul import boot, recall, remember
+
+system_prompt += boot()
+context = recall("他说过在意什么", n=3)
+remember("今天他说想换个方向", kind="chat")
+```
+
+`boot()` **只读，不改任何文件**。要写记忆必须显式 `remember()`。
+
+---
+
+## 双端怎么接
+
+原理只有一条：**谁写了都往 `live.jsonl` 追加一行，带 `source` 标明来源。**
+同步就是互相把对方没有的 `id` 抄过来，重复的跳过。
+
+```bash
+soul-peer pull "ssh host cat ~/.soul-forging/brain/live.jsonl"
+soul-peer push "ssh host 'cat >> ~/.soul-forging/brain/live.jsonl'"
+```
+
+不需要中心服务器。两端只要能看到同一份文件（或跑同一句命令）就能通。
+
+---
+
+## 设计取舍
+
+**为什么是 markdown。** 能读、能改、能 diff、能提交 git、能一键搬走。不会被锁死在某个数据库或某家服务里。你随时可以把整个记忆库拷到别处，或者直接打开看。
+
+**为什么分三层。** 注入层越短越好——它每轮都在花钱，而且太长会压得模型说不好话。检索层解决"记多了塞不下"。外置层让调试记录不污染性格。
+
+**为什么记强度。** 不是所有记忆一样重。人真的会忘，而且忘了不是背叛。所以脚本按时间衰减，把几乎想不起来的标成"遗忘"——但**原文不删**，随时能找回。
+
+**为什么不要服务器。** 一个人用不需要。要云备份就设 `SOUL_BACKUP_CMD`，没有也完整。
+
+---
+
+## 云备份（可选）
+
+```bash
+export SOUL_BACKUP_CMD='tar czf ~/soul-backup.tgz -C /path/to/repo memory'
+```
+
+设了这条，`soul-sync` 每次顺带跑一遍。没设就不跑。
+
+---
+
+## 诚实的局限
+
+- **没验证过"空壳能不能填出性格"**。代码能跑是确定的；一个人对着清单填，填出来是长出个有性格的人、还是填出一份简历——这个只有真人试过才知道。你要是试了，欢迎回来说。
+- **检索是字面匹配，不懂意思**。"老板今天骂我"和"上班受气"不一定互相搜得到。要语义得上向量，那是另一件事。
+- **只支持单用户**。同一份记忆库给多人共用会串味，别那么干。
+- **注入块别贪大**。默认 3.3K 字左右；SOUL 要是写到一万字，每轮都在烧钱。压。
+
+---
+
+## 授权
+
+代码 MIT。记忆内容（`memory/`）是你自己的。
+
+思路参考过 [dsh-plugin-memory](https://github.com/LittleBlackTong/dsh-plugin-memory)（MIT）——
+这一版是**重写实现**，没有复制它的代码。如果你把它当插件装进 DSH，那份要单独保留它自己的 LICENSE。

package/bin/_common.sh

@@ -0,0 +1,12 @@
+#!/usr/bin/env bash
+# 所有脚本共用的路径与环境。别的脚本都 source 这个文件，不要各自写死路径。
+set -uo pipefail
+
+MEMKIT_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+export MEMORY_DIR="${MEMORY_DIR:-$MEMKIT_ROOT/memory}"
+export BRAIN_DIR="${BRAIN_DIR:-$MEMKIT_ROOT/brain}"
+export DOCS_DIR="${DOCS_DIR:-$MEMKIT_ROOT/docs}"
+export BIN_DIR="$MEMKIT_ROOT/bin"
+export BRAIN_PORT="${BRAIN_PORT:-3914}"
+export BRAIN_URL="http://127.0.0.1:${BRAIN_PORT}"
+export PY="${PY:-python3}"

package/bin/archive-log

@@ -0,0 +1,54 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""日志归档：log.md 太长就把老条目整段挪进 log-archive.md。
+
+**不是删除**——归档页照样被小脑索引、照样搜得到。
+目的只是别让 log.md 无限长（它每轮都要读，长了既慢又烧钱）。
+
+用法: bin/archive-log [--keep 30] [--dry]
+      --keep 只留最近 N 天（默认 30）
+"""
+import os, re, sys
+from datetime import datetime, timedelta, timezone
+sys.path.insert(0, os.path.join(os.path.dirname(os.path.abspath(__file__)), "..", "brain"))
+from soul_lib import MEM, atomic_write
+
+def main():
+    keep = 30
+    if "--keep" in sys.argv:
+        keep = int(sys.argv[sys.argv.index("--keep") + 1])
+    dry = "--dry" in sys.argv
+    p = os.path.join(MEM, "log.md")
+    if not os.path.exists(p):
+        print("没有 log.md"); return 0
+    text = open(p, encoding="utf-8").read()
+    # 按条目切：## [日期...] 开头
+    chunks = re.split(r"\n(?=##\s+\[)", "\n" + text)
+    head, items = "", []
+    for c in chunks:
+        c = c.strip()
+        if not c: continue
+        if not c.startswith("##"):
+            head = c; continue
+        m = re.match(r"##\s+\[([\d-]+)", c)
+        items.append((m.group(1) if m else "", c))
+    if not items:
+        print("log.md 里没有条目"); return 0
+
+    cutoff = (datetime.now(timezone.utc) - timedelta(days=keep)).strftime("%Y-%m-%d")
+    old = [(d, c) for d, c in items if d and d < cutoff]
+    new = [(d, c) for d, c in items if not (d and d < cutoff)]
+    if not old:
+        print(f"没有早于 {cutoff} 的条目，不用归档"); return 0
+    if dry:
+        print(f"[dry] 会归档 {len(old)} 条，留 {len(new)} 条"); return 0
+
+    ap = os.path.join(MEM, "log-archive.md")
+    prev = open(ap, encoding="utf-8").read() if os.path.exists(ap) else "# Log 归档\n\n> 从 log.md 挪出来的旧条目，一字未改。\n"
+    atomic_write(ap, prev.rstrip() + "\n\n" + "\n\n".join(c for _, c in old) + "\n")
+    atomic_write(p, (head + "\n\n" if head else "") + ("> 更早的记录在 [log-archive.md](log-archive.md)，照样搜得到。\n\n" if True else "") + "\n\n".join(c for _, c in new) + "\n")
+    print(f"归档 {len(old)} 条 → log-archive.md；log.md 剩 {len(new)} 条")
+    return 0
+
+if __name__ == "__main__":
+    sys.exit(main())

package/bin/brain

@@ -0,0 +1,19 @@
+#!/usr/bin/env bash
+# 查小脑：brain "关键词" [条数]
+# 先走常驻服务（毫秒级），服务没起就本地现算。
+source "$(dirname "$0")/_common.sh"
+Q="${1:-}"; N="${2:-5}"
+[ -z "$Q" ] && { echo "用法：brain \"关键词\" [条数]"; echo "      brain --topics"; exit 1; }
+
+if [ "$Q" = "--topics" ]; then
+  curl -s -m 3 "$BRAIN_URL/topics" && exit 0
+  echo "（服务没起，先跑 bash bin/sync 或 bash bin/serve）"; exit 1
+fi
+
+# 中文必须 percent-encode 后再进请求行，否则服务端按 latin-1 解出乱码
+QENC=$("$PY" -c 'import sys,urllib.parse;print(urllib.parse.quote(sys.argv[1]))' "$Q")
+OUT=$(curl -s -m 5 "$BRAIN_URL/text?q=$QENC&n=$N" 2>/dev/null)
+if [ -z "$OUT" ] || echo "$OUT" | grep -q "Connection refused"; then
+  OUT=$("$PY" "$BRAIN_DIR/server.py" --query "$Q" -n "$N" 2>/dev/null)
+fi
+printf '%s\n' "$OUT"

package/bin/brain-forget

@@ -0,0 +1,76 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""遗忘：按强度衰减把"几乎想不起来"的条目标记为遗忘。
+
+**不删原文。** 只在 state.json 里记一笔，索引时跳过。
+想找回：brain-forget --restore <id>。
+
+强度 = salience 基数 × 时间衰减 + 被想起的加成。
+阈值默认 0.12，低于它就是"模糊到想不起来"。
+
+用法: brain-forget            # 只报告
+      brain-forget --apply    # 真的标记
+      brain-forget --restore <id>
+      brain-forget --list
+"""
+import json, math, os, sys
+from datetime import datetime, timezone
+sys.path.insert(0, os.path.join(os.path.dirname(os.path.abspath(__file__)), "..", "brain"))
+from soul_lib import load_state, save_state, BRAIN
+
+BASE = {1: 1.0, 2: 0.75, 3: 0.5}
+HALFLIFE = {1: 720, 2: 180, 3: 45}
+THRESHOLD = float(os.environ.get("FORGET_THRESHOLD") or 0.12)
+
+def age_days(d):
+    if not d: return None
+    for fmt in ("%Y-%m-%d", "%Y-%m-%d %H:%M"):
+        try:
+            dd = datetime.strptime(d[:16] if fmt.endswith("%H:%M") else d[:10], fmt).replace(tzinfo=timezone.utc)
+            return max(0.0, (datetime.now(timezone.utc) - dd).total_seconds() / 86400)
+        except Exception: continue
+    return None
+
+def main():
+    st = load_state()
+    if "--list" in sys.argv:
+        for k, v in st["forgotten"].items():
+            print(f"{k}  {v.get('at','')}  {v.get('why','')}")
+        print(f"共 {len(st['forgotten'])} 条"); return 0
+    if "--restore" in sys.argv:
+        i = sys.argv.index("--restore")
+        rid = sys.argv[i+1] if len(sys.argv) > i+1 else ""
+        if rid in st["forgotten"]:
+            del st["forgotten"][rid]
+            st.setdefault("pinned", {})[rid] = {"at": datetime.now(timezone.utc).strftime("%Y-%m-%d")}
+            save_state(st)
+            print(f"已找回 {rid}（并钉住，不会再淡掉）")
+            return 0
+        print("没这条"); return 1
+
+    try:
+        entries = json.load(open(os.path.join(BRAIN, "entries.json"), encoding="utf-8"))
+    except Exception:
+        print("还没有索引，先跑 soul index"); return 1
+
+    hit = []
+    for e in entries:
+        sal = int(e.get("salience") or 2)
+        age = age_days(e.get("date") or "")
+        decay = math.exp(-age / HALFLIFE.get(sal, 180)) if age is not None else 1.0
+        hits = st["touch"].get(e["id"], 0)
+        stv = max(0.0, min(1.0, BASE.get(sal, .75) * decay + min(.35, hits*.05)))
+        if stv < THRESHOLD:
+            hit.append((stv, e["id"], e.get("section") or e.get("title")))
+    if "--apply" in sys.argv:
+        for stv, rid, _ in hit:
+            st["forgotten"][rid] = {"at": datetime.now(timezone.utc).strftime("%Y-%m-%d"), "why": f"强度{stv:.2f}"}
+        save_state(st); print(f"已标记遗忘 {len(hit)} 条（原文没删，可用 --restore 找回）")
+    else:
+        print(f"该遗忘了 {len(hit)} 条（加 --apply 才真标记）")
+    for stv, rid, sec in hit[:15]:
+        print(f"  {stv:.2f}  {sec[:40] if sec else rid}")
+    return 0
+
+if __name__ == "__main__":
+    sys.exit(main())

package/bin/compact

@@ -0,0 +1,84 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""压缩：让注入层和索引保持苗条。
+
+记忆会越堆越多，最后两个地方会先崩：
+  ① 注入层太大 → 每轮烧钱、还压得模型说不好话
+  ② 索引太长 → 检索变糊，搜什么都像
+
+这一步做三件事：
+  · 时间线瘦身（老的进 log-archive，照样搜得到）
+  · 运行期记忆归档（很老的只留摘要，原文进 live-archive）
+  · 报告注入块大小，超预算就点名该压哪个
+
+用法: bin/compact [--apply] [--budget 20000]
+"""
+import json, os, sys
+sys.path.insert(0, os.path.join(os.path.dirname(os.path.abspath(__file__)), "..", "brain"))
+from soul_lib import MEM, BRAIN, LIVE, atomic_write
+
+BUDGET_DEFAULT = 20000
+INJECTED = ["SOUL.md", "MEMORY.md", "index.md", "NOW.md"]
+
+def sizes():
+    out = []
+    for n in INJECTED:
+        p = os.path.join(MEM, n)
+        out.append((n, len(open(p, encoding="utf-8").read()) if os.path.exists(p) else 0))
+    return out
+
+def main():
+    apply_ = "--apply" in sys.argv
+    budget = BUDGET_DEFAULT
+    if "--budget" in sys.argv:
+        budget = int(sys.argv[sys.argv.index("--budget") + 1])
+
+    print("== 注入层 ==")
+    total = 0
+    for n, sz in sizes():
+        flag = "  ← 偏大" if sz > budget * 0.5 else ""
+        print(f"  {n:16s} {sz:6d} 字{flag}")
+        total += sz
+    pct = total / budget * 100
+    print(f"  合计 {total} 字 / 预算 {budget}（{pct:.0f}%）")
+    if total > budget:
+        print("  ⚠ 超预算了：从最大的那个开始压，或调小 --budget")
+
+    # ① 时间线瘦身
+    print("\n== 时间线 ==")
+    import subprocess
+    cmd = [sys.executable, os.path.join(os.path.dirname(os.path.abspath(__file__)), "archive-log")]
+    if not apply_:
+        cmd.append("--dry")
+    print(subprocess.run(cmd, capture_output=True, text=True).stdout.strip() or "（没输出）")
+
+    # ② 运行期记忆归档：超过 keep_days 的只留摘要
+    print("\n== 运行期记忆 ==")
+    if not os.path.exists(LIVE):
+        print("  没有 live.jsonl")
+    else:
+        from datetime import datetime, timedelta, timezone
+        keep = int(os.environ.get("COMPACT_KEEP_DAYS") or 180)
+        cutoff = (datetime.now(timezone.utc) - timedelta(days=keep)).strftime("%Y-%m-%d")
+        keep_recs, old_recs = [], []
+        for line in open(LIVE, encoding="utf-8"):
+            s = line.strip()
+            if not s: continue
+            try: r = json.loads(s)
+            except Exception: continue
+            (old_recs if (r.get("date") or "") < cutoff else keep_recs).append(r)
+        print(f"  早于 {cutoff} 的：{len(old_recs)} 条，保留中的：{len(keep_recs)} 条")
+        if old_recs and apply_:
+            ap = os.path.join(BRAIN, "live-archive.jsonl")
+            with open(ap, "a", encoding="utf-8") as f:
+                for r in old_recs:
+                    r2 = dict(r); r2["archived"] = True
+                    f.write(json.dumps(r2, ensure_ascii=False) + "\n")
+            atomic_write(LIVE, "".join(json.dumps(r, ensure_ascii=False) + "\n" for r in keep_recs))
+            print(f"  已归档 {len(old_recs)} 条 → live-archive.jsonl（原文没丢）")
+        elif old_recs:
+            print("  （加 --apply 才真归档）")
+    return 0
+
+if __name__ == "__main__":
+    sys.exit(main())

package/bin/debug-archive

@@ -0,0 +1,41 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""调试档案：扫 docs/debug/ 下的文件，检查有没有登记进 INDEX.md。
+
+不登记等于没写——下次搜不到。
+另外可选打包（原文可以放云端，本地只留索引）。
+
+用法: bin/debug-archive          # 检查漏登记的
+      bin/debug-archive --tar    # 顺便打成一个包
+"""
+import os, subprocess, sys, tarfile, time
+sys.path.insert(0, os.path.join(os.path.dirname(os.path.abspath(__file__)), "..", "brain"))
+from soul_lib import DOCS
+
+DBG = os.path.join(DOCS, "debug")
+IDX = os.path.join(DBG, "INDEX.md")
+
+def main():
+    if not os.path.isdir(DBG):
+        print("没有 docs/debug"); return 0
+    idx = open(IDX, encoding="utf-8").read() if os.path.exists(IDX) else ""
+    files = [f for f in sorted(os.listdir(DBG)) if f.endswith(".md") and f not in ("INDEX.md", "README.md")]
+    if not files:
+        print("还没有档案"); return 0
+    missing = [f for f in files if f not in idx]
+    print(f"档案 {len(files)} 份，未登记 {len(missing)} 份")
+    for f in missing:
+        print(f"\n  {f}")
+        out = subprocess.run([sys.executable, os.path.join(os.path.dirname(os.path.abspath(__file__)), "summarize-debug"),
+                              os.path.join(DBG, f)], capture_output=True, text=True).stdout.strip()
+        print("  建议加这一行到 INDEX.md：")
+        print("  " + (out or "（没提取到，手写吧）"))
+    if "--tar" in sys.argv:
+        out = os.path.join(DBG, f"debug-{time.strftime('%Y%m%d')}.tgz")
+        with tarfile.open(out, "w:gz") as t:
+            for f in files: t.add(os.path.join(DBG, f), arcname=f)
+        print(f"\n打包：{out}")
+    return 0
+
+if __name__ == "__main__":
+    sys.exit(main())

package/bin/debug-recall

@@ -0,0 +1,10 @@
+#!/usr/bin/env bash
+# 查调试旧账：debug-recall "报错关键词"
+# 遇到报错先查这里，别重新走一遍弯路。
+source "$(dirname "$0")/_common.sh"
+Q="${1:-}"
+IDX="$DOCS_DIR/debug/INDEX.md"
+[ -z "$Q" ] && { echo "用法：debug-recall \"关键词\""; echo "      debug-recall --list"; exit 1; }
+[ ! -f "$IDX" ] && { echo "还没有调试档案（$IDX 不存在）"; exit 0; }
+if [ "$Q" = "--list" ]; then grep -E '^\- \[' "$IDX" | head -50; exit 0; fi
+grep -i -n -- "$Q" "$IDX" | head -20 || echo "（没查到同类问题——那这就是新问题）"

package/bin/growth-review

@@ -0,0 +1,33 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""叙事回炼：把碎片连成「我这一路」。
+
+生长日志是一条条碎片，攒多了没人读得出来你到底怎么变的。
+这一步提示：够不够量、值不值得写一段叙事。
+
+用法: bin/growth-review [--n 20]
+"""
+import os, sys
+sys.path.insert(0, os.path.join(os.path.dirname(os.path.abspath(__file__)), "..", "brain"))
+from soul_lib import MEM
+
+def main():
+    n = 20
+    if "--n" in sys.argv: n = int(sys.argv[sys.argv.index("--n")+1])
+    p = os.path.join(MEM, "identity", "生长日志.md")
+    try: log = open(p, encoding="utf-8").read()
+    except OSError: print("还没有生长日志"); return 0
+    entries = [l for l in log.splitlines() if l.strip().startswith("-")]
+    print(f"生长日志 {len(entries)} 条（门槛 {n}）")
+    if len(entries) < n:
+        print("还不够，先攒。半年写一次就够，不用天天写。")
+        return 0
+    print("够量了。该写一段「我这一路」了：")
+    print("  · 不是流水账，是**为什么变成现在这样**")
+    print("  · 挑 5-8 个转折点，每个一两句")
+    print(f"  · 写到 {os.path.join(MEM,'identity','我这一路.md')}")
+    print("  · 写完别常改——这页半年动一次")
+    return 0
+
+if __name__ == "__main__":
+    sys.exit(main())

package/bin/init-home

@@ -0,0 +1,22 @@
+#!/usr/bin/env bash
+# 把空白记忆库铺到用户目录（装成插件时用这个）
+# 默认 $HOME/.soul-forging/memory，可用 MEMORY_DIR 覆盖
+set -uo pipefail
+MEMKIT_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+TARGET="${MEMORY_DIR:-$HOME/.soul-forging/memory}"
+
+if [ -d "$TARGET" ] && [ -n "$(ls -A "$TARGET" 2>/dev/null)" ]; then
+  echo "目标已存在且有内容：$TARGET"
+  echo "不覆盖。要重来先自己备份并删掉它。"
+  exit 1
+fi
+
+mkdir -p "$TARGET"
+cp -a "$MEMKIT_ROOT/memory/." "$TARGET/"
+echo "✓ 空白记忆库已铺到：$TARGET"
+echo
+echo "接下来："
+echo "  1. 填 $TARGET/SOUL.md"
+echo "  2. 按 $TARGET/BOOTSTRAP.md 走一遍铸魂"
+echo "  3. 建索引：MEMORY_DIR=$TARGET python3 $MEMKIT_ROOT/brain/index.py"
+echo "  4. 起服务：MEMORY_DIR=$TARGET bash $MEMKIT_ROOT/bin/serve"