v2.6.1 — 泛化审计轮：召回/排序/分类三处修复

全部先测后改：§4b 联想通道四根因（h16 口语↔规范摘要零词面重叠两头不靠）、§4c Generative-Agents recency（时间金标违反 0.419→0.161）、§4d 分类器第一人称结构门（捕获率 0.438→1.000）、§4f superseded 降权（矩阵 KU 15/17→17/17 无代价）、概念卡扩充（孤儿 33→23）、SKILL 聚合读法缺口。实验否决两条并留档（SYNAPSE 激活衰减架构性无效、PMI 词表过滤零收益）。182 tests green.

v2.6.0 — Associative retrieval: self-trained lexicon + concept-card graph + PPR spread

2.6.0 — 2026-09-05 — 联想检索与档案词表：让"词面零重叠"的回忆变得可达

承接 2026-09-05 深夜与用户的演进讨论（"回忆 ≠ 语义相似：反面与精神内核相似物打分为 0 就不可见"），全部改动先在沙盒实测、再落库；新增三层能力与一次闸门放宽。

• 词元净化层（scripts/lexicon.py + resources/lexicon/）：vendor jieba 词典（MIT，fxsjy/jieba，34.9 万词条）+ 档案自训练词表（memory/v2/archive-lexicon.json：档案文本 DF≥2 的 2-4 字字段 + 全部实体卡 label/aliases，rebuild_views 自动刷新）。三类修复均有实测根因：① ASCII 单字符（"巫师3"拆出的"3"）不再具备内容词资格——记录 id/日期里的"3"曾让驾照记录在巫师3查询拿 timeline 第 1；② 中英混写专名自动粘连成整词（"巫师3""晕3D"），CJK/ASCII 边界不再切碎最强锚定；③ 词典外切片权重 ×0.4 封顶——保留召回（唯一命中仍前排、排序是相对的）但不再当锚定词，跨词假切片（"郎我""卡了"）失去虚高 IDF。设计教训已写进代码注释与测试：第一版"直接删除 OOV 切片"立即回归 T02（"弦一郎"档案仅出现 1 次、任何 DF 门槛都救不了它），改为降权后零误杀。known() 的判定含档案自训练词表——档案自身就是最懂自己专名的词典（用户 5.6b 提案）。
• 联想检索通道（scripts/ppr.py + retrieve_v2 associations 段）：个性化 PageRank 在档案图上扩散（种子 = 查询命中的实体/概念卡；4 次迭代的局部扩散——收敛式 PPR 会让 ai-agi/home 这类 50-68 mention 的枢纽把"联想"变成"热度榜"；非种子邻居 mention_count≤30 封顶）。两级候选：种子实体投影（图距离 1 的自有记录，按 salience 排序——"打击感烂"经概念卡直达"巫师3 骑马手感"记录，词面零重叠）+ 图扩散邻居。输出独立 associations 段，每条带 via_entity 路径与 spread_score，绝不混入 timeline、绝不自行构成入选资格——词面管精确回忆、图管发散，证据链可见可审计。
• 概念卡层（实体 55→63）：PPR 需要抽象层节点才能产生"精神内核"联想——第一版无概念卡的实测是共现随机游走（"打击感"查询联想出足球装备边界）。新增 8 张概念卡（操作手感/叙事体验/品味锚点/金钱自主/消费纪律/家庭边界/考公路径/身体限制）+ 《百年孤独》正式实体卡；aliases 覆盖口语入口词（"书荒""晕3D""考公""史低""打击感"）。实测："书荒了，整本来嚼嚼"——此前三通道全灭——现经 concept.reading-taste 带出阅读史与开放清单。"打击感跟纸糊的一样"→ witcher3-feel 记录 via concept.gameplay-feel。
• 足迹轮只读降级（MCP maintenance 参数）：实测发现 fail-closed 链（足迹消息判 non-personal → capture 拒写 → retrieve 拒读）把攻略/书荒类轮次彻底锁在档案之外，连读都不行。personal_retrieve/personal_catalog 现接受 maintenance: true（等价 CLI --maintenance，trace 审计）做只读降级；写入闸门分毫未动，SKILL 指引模型随后仍按足迹纪律 tier=full 重声明补 capture。
• 管线时间线（scripts/pipeline_view.py）：一轮对话的一生——receipt 判档理由 → capture 哈希 → 派生闭环 → 检索轨迹（query/scoring/选中/联想/停用）一页只读回放（--turn-id X / --latest N，HTML 到 dashboard/）。可视化第一步，同时是验收工具：足迹纪律、闭环完整性、检索捞偏都能在此回放。
• 测试 171→173 全绿（新增 OOV 降权契约、混合专名存活、tools/list 健康检查连带修复 MCP schema 的 Python False 字面量笔误）；retrieval_version 升为 2.6.0。诚实边界不变：probe 契约输入仍是足迹关键词；associations 是候选池不是排序结果，引用前模型必须自行判断联想是否成立。

v2.5.1 — repo-face hygiene

Repo-face hygiene patch — no retrieval or write-path behavior changes.

• Both READMEs: the packaged-file count is finally unpinned (EN was pinned to "38 files", zh-CN had silently kept the stale "37 个文件") — now "byte-identical, re-verified every release".
• hot_mirror.py: the three hardcoded C:\Users\Administrator\... paths are gone from the public wheel; defaults now derive from the user profile, overridable via PU_SKILLS_DIR / PU_HOT_MIRROR_DIR / PU_HOT_MIRROR_LOG. Behavior on the original machine is unchanged.
• mcp_test.py: the committed acceptance driver had rotted against the current preflight response shape (nested turn_receipt) and crashed with KeyError; repaired and re-verified end-to-end against a sandbox archive (13 MCP tools, full chain green).
• peek.py: synced with the acceptance workspace copy (--maintenance auto-injected).

Wheel parity re-verified at build time: 38/38 modules byte-identical to scripts/, zero machine-specific strings. 171 tests green.

Full Changelog: v2.5.0...v2.5.1

v2.5.0 — audit-repair release: retrieval honesty, write integrity, ops hardening

Highlights

Retrieval honesty — anchor-ratio demotion (weighted-idf-4-anchor) stops sentence-form queries from rewarding noise n-grams on small corpora; closed-class stop words can no longer masquerade as rare content terms; single-char aliases (妈/她) no longer get noise-suppressed, so colloquial queries finally reach core events.

Write integrity — MCP write tools no longer report false isError on in-flight captures (no more retry → duplicate records); ledger repair trust rules rewritten (attachment-only links preserved, no disposition flips); version chains now cover decision records.

Ops hardening — CLI reads are capture-gated like MCP (--capture-id or --maintenance); install_mcp refuses to hijack a live registration tree; backup_archive --no-cloud; dangling entity links now surface instead of vanishing.

Followups — official closure channel resolve_followup (13th MCP tool) with optional answer-capture binding; missing source/expiry fields now remind instead of silently passing.

On-demand hypotheses — causal hypotheses load only when query terms hit, not on every read.

Tests: 113 → 171 green · CI ubuntu/windows × py3.10/3.13 · wheel byte-identical to source.

中文

审计修复版本：检索诚实性（锚定比值降权、停用词降权、单字别名豁免）、写入一致性（写工具不再误报 isError、台账修复信任规则重写、decision 版本链）、运维加固（CLI 读闸门对齐、install_mcp 防劫持、备份 --no-cloud）、回访闭环（resolve_followup 第 13 个 MCP 工具，可绑定回答原话）。因果假设改为按需加载。完整清单见 CHANGELOG。

Full Changelog: v2.4.1-pre-2500-repair...v2.5.0

v2.3.1 — three-tier invocation + audit hardening

Three-tier invocation (full/light/skip) plus the audit-hardening pass. Highlights:

• Three-tier gate: full / light / skip with model-declared tier, tier flows through receipts, records, timeline and knowledge views (2.3.0)
• reasons_suppressed: skip overrides of the content classifier now leave an audit trail (2.3.1)
• Light-tier empty closure is now gate-enforced: light-tier-requires-derived-record (2.3.1)
• finalize (CLI + MCP) no longer false-errors while sibling captures are pending in multi-capture turns (2.3.1)
• Docs: tier-upgrade requires a new turn_id; skip guardrail; multi-capture closing recipe
• Tests: 103 passed; snapshot re-certified and pushed to cloud

v2.2.2 — incident hardening, attachment restoration, protocol fix

See CHANGELOG.md. Highlights: MCP server now speaks UTF-8 on every Windows box (protocol fix); turn receipts support multi-capture turns; hot-mirror watchdog + scheduled daily backup; all incident-lost photo attachments restored under original capture IDs with sha256-verified provenance.

v2.2.1 — installable release (Glama, PyPI fix, recovery tooling)

What's fixed in 2.2.1

• PyPI installs now report the real version — the packaged MCP server previously fell back to 2.0.0 in its serverInfo; skill_version now reads package metadata when the VERSION file is absent.
• validate_memory.py version fix — expected version is derived from the VERSION file, so validation no longer fails out of the box after version bumps (this broke 2.2.0 installs).
• init_archive.py builds v2 views during bootstrap — a fresh archive validates clean on first run.
• restore_stable.py — scoped recovery from the stable zip (code/data/all, dry-run by default, sha-256 verified, pre-restore snapshot).
• Glama MCP directory support — added glama.json and a Dockerfile so the server can be installed and security-scanned.
• CI (GitHub Actions), issue templates, and a repo version-sync test.

pip install personal-understanding · MIT · Python 3.10+ stdlib

v2.2.0 — hardening + first PyPI release

First release published to PyPI: personal-understanding — pip install personal-understanding.

Hardening (main branch)

• Added content-first, immutable turn receipts so personal material cannot be skipped just because it is framed as rewriting, translation, summarization, or image review.
• Bound capture, finalization, and session_check --turn-id to the receipt hash and made incomplete personal turns fail closed.
• Added a shared inter-process mutation lock, atomic writes, ledger journal/repair, and locked MCP record/follow-up/hypothesis writers to prevent lost updates between Agents and MCP processes.

---

⚠️ Known issues in 2.2.0 artifacts (fixed on main, will ship in 2.2.1)

• validate_memory.py hardcoded the expected version as 2.1.0, so validation failed out of the box on 2.2.0 installs (fixed in 138ad6a; expected version is now derived from the VERSION file).
• The PyPI wheel/sdist were built from a stale snapshot: the packaged MCP server predates the receipt/concurrency hardening above (its serverInfo reports 2.0.0), and the pip route has no archive bootstrap (no memory/ root under site-packages). Until 2.2.1, prefer a source install:
  git clone https://github.com/caix84476-netizen/personal-understanding.git <your-skills-dir>/personal-understanding && python scripts/init_archive.py && python scripts/install_mcp.py --auto

v2.1.0

Personal Understanding v2.1.0

Verbatim-first, evidence-chain personal memory for AI agents. One folder, Python stdlib only, fully local. Ships as a skill + stdio MCP server (11 tools) with a local audit dashboard. Bilingual: English (SKILL.md) and 中文 (SKILL.zh-CN.md).

Highlights

• Verbatim-first capture — every personal message saved word-for-word (SHA-256, timestamped, session-tagged) before any summarizing; every derived record links back to the exact quotes
• Derivation closure + hard session gate — the agent cannot claim "memory updated" unless structural validation, closure, and v2 integrity checks pass with exit code 0
• Human-like three-layer recall — survey (compact routing map) → probe (entities, context cards, time neighbors) → deep (verbatim only); cold-recall ladder for "I forget…"
• Causal hypothesis layer — claim / mechanism / supports / counterexamples / alternatives / scope, always candidate, never silently promoted to fact
• Entity profiles + cross-entity context cards — people, schools, places, objects, works, games, concepts, environments
• Proactive follow-ups — "let's see in a few days" becomes a tracked loop that checks back with context
• Guided starters — new users who don't know what to share get one warm, concrete question from the archive's real gaps
• Audit dashboard — local read-only panel: counts, validation state, full chain from any event back to the original words
• Zero dependencies — Python stdlib only, no embeddings service, no API keys, no telemetry

v2.1.0 changes (2026-08-29)

• Correctness: fixed a salience-decay data-corruption bug; unified follow-up-due semantics; atomic writes everywhere; tolerant load of corrupt manifests; dead code removed
• Product: trigger-scenario description; low-signal fast path; survey phase bucketing (~230 ms); evidence_fidelity counts in probe
• Loops: persisted retrieval decision traces; redesigned backup model (snapshots + rclone mirror); install_mcp.py across clients; references consolidated 26 → 14
• Includes the full hardening history from earlier rounds (v2.0.0 architecture leap: memory/v2/, immutable captures, salience axis, context cards, hypotheses, three-state validation, dashboard)

See the full CHANGELOG.

• MIT License
• Install: git clone into your client's skills dir → python scripts/init_archive.py → python scripts/install_mcp.py --auto