Personal-Ontology

中文 · English

全景 · 区别 · 核心系统 · Trust Core · Skills · 安装 · 状态 · FAQ · 变更

让 AI Agent 长期、可追溯、经你批准地维护"关于你"的知识。

这是一个原创的个人本体工作台：一个完整知识系统（lab-ontology）、一个可独立使用的可信度核心（lab-trust-core），以及四个围绕知识流工作的 Skill。它解决的是 Agent 记忆的三个老问题——记得零散、来源不可追、还会在你不知情时被改写。这里的答案是三条立场：

1. Markdown 与 Git 是唯一事实源。 向量库、关系图、检索索引都是可以随时从 Markdown 重建的派生层；换引擎不丢知识。
2. 写入即提案。 任何 Agent 都能读，但没有谁能直接写。每次改动都是一份精确到文件内容基线的提案，只有你在当前对话里明确批准，网关才会校验、提交 Git、重建索引。
3. 证据有边界，结论有成熟度。 一条观点从哪来、样本多大、利益关系如何、允许用在哪，都是字段而不是修辞；seed → corroborated → validated 按独立来源家族计，不按重复次数投票。

全景

flowchart LR
    subgraph Collect["采集 · 把经历变成材料"]
        CD["lab-wx-distillation<br/>从微信等既有记录蒸馏"]
        LR["lab-life-reviewer<br/>主动访谈逐事件还原"]
    end
    subgraph Distil["蒸馏 · 决定什么值得留"]
        KR["lab-retrospective<br/>结论复盘 / 逐轮法证审计"]
    end
    subgraph File["入库 · 提案与批准"]
        KI["lab-intake<br/>查重 → 精确提案 → 等待批准"]
    end
    subgraph System["lab-ontology · 核心系统"]
        GW["agent-knowledge 网关 (MCP)<br/>13 个 knowledge_* 工具"]
        V[("Vault<br/>Markdown + Git")]
        IX[("Native 派生索引<br/>关键词 + 向量")]
    end
    CD --> KR
    LR --> KR
    KR --> KI
    KI --> GW
    GW -- "用户批准后提交" --> V
    V -. "可重建" .-> IX
    AG["任意 MCP Agent（Claude / Codex / others）"] -- "knowledge_route / search / get" --> GW
    TC["lab-trust-core · Trust Core<br/>独立 SDK / CLI / read-only MCP"]
    GW -. "knowledge_get 后<br/>非强制 shadow" .-> TC
    EXT["其他知识系统 / RAG / Agent"] -. "可独立调用" .-> TC

从左到右就是知识的流向：先从既有记录或主动访谈里采集材料，再由复盘环节决定什么值得留下，最后经提案流程入库。所有 Agent 读知识都走同一个网关，读到的是同一份 Vault。

和常见「自动记忆」的区别

多数给 Agent 加记忆的方案是一个自动写入的黑盒：模型觉得重要就存，存进一个你打不开的向量库。这个仓库走的是另一条路：

代价也说清楚：它比"装上就有记忆"的方案重——需要运行本地网关，完整语义检索还需要兼容的向量服务，每次写入也要你点头。适合把个人知识当长期资产管理的人，不适合只想要聊天记忆的场景。

核心系统：lab-ontology

打开模块文档 · 架构说明 · 安装指南

lab-ontology 是共享知识流的核心系统；入库与复盘 Skill 直接使用它，采集 Skill 也可以独立产出交接包。它包含三样东西：

• 一个 Vault 骨架（lab-ontology/vault/），可以直接用 Obsidian 打开。知识按"未来如何被 Agent 使用"分三层：.raw/ 只保可复原、从不进索引；sources/ 存证据与候选观点，按需检索；projects/ decisions/ methods/ syntheses/ concepts/ 是默认参与判断的结果层。页面契约写在 ops/SCHEMA.md，Agent 行为规则写在 ops/AGENTS.md。
• 一个 MCP 网关（vault/ops/gateway/），名为 agent-knowledge，暴露 13 个 knowledge_* 工具：route / search / get / list / related 负责读，intake / schema 返回契约，propose_changes / list_proposals / get_proposal / apply_proposal / reject_proposal 负责提案与审批，repair_index 负责修复派生索引。读取是"精确优先"的：向量相似度只排序候选，从不单独触发读取。
• 一套 Native 治理与检索工具：Git 提交绑定的 Markdown 目录、关键词与向量混合索引、同提交关键词回退、由 frontmatter 链接生成的带类型关系、可重建的人类 index.md、Vault/Schema 校验器和索引范围检查。Schema pack（agent-decision-memory）位于 ops/agent-knowledge-schema/pack.json。

它不是 prompt-only 的：CI 会把骨架复制到临时目录并初始化成独立 Git Vault，再运行完整确定性单测、Schema/Vault 校验和 13 工具启动探针。Native 向量、构建与修复协议由合成 embedding 服务测试；test:smoke 在临时合成 Vault 中验证同提交关键词降级链。完整向量能力使用 Ollama-compatible embedding 服务，真实服务只用于可选的人工本地集成检查。仓库里只有系统和合成 fixture，没有作者的个人知识。

Trust Core：lab-trust-core

打开 Trust Core 文档 · 数据模型 · 集成说明

lab-trust-core 接收一条结构化知识记录及其预期用途，返回可解释的 allow、review 或 deny 判断，并检查这条知识能否从 seed 晋升为 corroborated 或 validated。它按独立来源家族计数，不会把同一作者反复发布误认成交叉验证。

它不是第二套知识库，也不是 Skill：不保存、不搜索、不写入知识，不依赖 lab-ontology，可以通过 SDK、CLI 或只读 MCP 单独嵌入任意知识库、RAG 或 Agent。Agent Knowledge 1.8.0 已通过 lockfile 固定其公开 release，但只在 knowledge_get 通过 scope gate 后做非强制 shadow 观测；它不会阻断读取、改变路由、升级成熟度或批准写入。这个组合不影响 Trust Core 单独使用。

Skills（按知识流向排序）

lab-wx-distillation 是四个里最重的一个：一条确定性的本地 Python 流水线，负责从既有记录里提取。它把采集、解密适配、身份脱敏留在本机，只让模型看到密封过的、脱敏的数据包；每条路由恰好产生一个处理结果，事件各自带语义状态，完整事件账本是权威，重要性只影响展示、不删除事件。当前状态是 v2.0.1，在合成/公开 fixture 上通过 150 个测试；它不宣称与任何具体微信构建的真机兼容，没有通过现场清单之前也不应该这样宣称。

lab-life-reviewer 从另一头补上记录里没有的东西：由你主动讲，Agent 逐事件追问、核对相关材料、保留 Raw 细节，再形成交接包。采访和归档是同一个 Skill 里前后衔接的两个任务，用文件交接，归档任务不能依赖对采访聊天的记忆。它不会把复杂经历压成一行时间线，也不会把解释当成事实。

lab-retrospective 站在采集与入库之间，回答“这次发生了什么、审计覆盖是否完整、有什么值得留下”。短任务使用结论模式；失败项目、长对话、跨任务范围和“复盘每一次问答”使用法证模式。它先取得当前方法页，再读取原始轮次、核验完成声明、关联用户纠正并报告 COMPLETE/PARTIAL；只有通过覆盖门后，才把叙事蒸馏成可迁移结论，并为每条候选标注证据、样本量和适用边界。大多数复盘正确的结果仍是零新增。

lab-intake 是最薄的一个，也是唯一的入口：任何材料想进 Vault，都由它先调 knowledge_intake 取契约、查重、生成精确提案，然后停下来等你批准。它自己不定义 Schema、不选存放位置、从不直接写文件；Schema 演进发生在网关里，Skill 不需要重新发布。

四个 Skill 都是厂商与模型无关的：Codex、Claude Code 和任何 MCP 客户端共用同一份 SKILL.md，只是安装位置不同。

一次完整的流转

以一次人生回顾为例：lab-life-reviewer 在采访任务里记录一段职业经历，生成 Raw 和 handoff；归档任务读取它们，调用 lab-retrospective 把叙事里能跨时间成立的结论挑出来——也许只有一条，也许没有；有结论时交给 lab-intake，它先读取当前 Schema 和目标页面、检索同义知识，再预检完整目标文件的字段、列表格式与双向关系，生成一份提案：新建一张 source 页记录出处与候选观点，或更新一张既有的 project 页。你看到的是原文级别的改动，批准后网关在隔离候选树里校验，只提交获批文件，并把 Native 索引同步到同一 Git 提交。从此任何 Agent 在相关任务开始时，都能通过 knowledge_route 读到这条结论，并看到它是 seed 还是已被多个独立来源 corroborated。

状态

Quick install

系统本体：复制 lab-ontology/vault/ 作为你自己的 Vault，把其中的 MCP 网关注册到 Agent，步骤见 lab-ontology/README.md。

Trust Core 可以不下载其他组件，单独稀疏检出：

git clone --filter=blob:none --no-checkout https://github.com/haorantang97/Personal-Ontology.git
cd Personal-Ontology
git sparse-checkout init --cone
git sparse-checkout set lab-trust-core
git checkout main
cd lab-trust-core && npm ci && npm run verify

Skill 用社区 Agent Skills 安装器按需安装：

npx skills add haorantang97/Personal-Ontology --skill lab-wx-distillation
npx skills add haorantang97/Personal-Ontology --skill lab-life-reviewer
npx skills add haorantang97/Personal-Ontology --skill lab-retrospective
npx skills add haorantang97/Personal-Ontology --skill lab-intake

也可以只复制对应的完整 Skill 目录。Codex、Claude Code、直接使用和卸载说明都在各模块 README 中。

仓库结构

Personal-Ontology/
├── README.md                      # 本页：介绍与目录
├── CONTRIBUTING.md · CHANGELOG.md
├── LICENSE.md · THIRD_PARTY_NOTICES.md
├── lab-ontology/                  # 核心系统
│   ├── README.md · docs/          # 模块手册、架构、安装
│   └── vault/                     # Obsidian Vault 骨架 + ops/（网关、schema、校验器）
├── lab-trust-core/                # 可独立安装的可信度核心；不依赖 lab-ontology
├── skills/
│   ├── lab-wx-distillation/  # Python 流水线、契约、fixture、150 个测试
│   ├── lab-life-reviewer/         # 双语参考文件
│   ├── lab-retrospective/
│   └── lab-intake/
├── tests/                         # 布局、Skill 包结构与公开边界测试
└── .github/workflows/ci.yml

Repository rules

• 根 README 负责介绍与目录，不重复具体 Skill、系统或 Trust Core 的操作手册。
• Skill 默认保持厂商与模型无关；不同 Agent 只使用不同安装位置。
• 每个独立组件单独声明验证状态、隐私边界和第三方依赖。
• Raw 访谈、聊天原文、身份、密钥与个人证据必须保存在仓库之外；lab-ontology/vault/ 永远是空骨架。
• 任何知识库写入都必须保留精确提案和用户批准门。
• 公开 fixture 通过不等于真实设备或具体微信小版本兼容。
• 全库不得出现私人绝对路径；tests/ 会在 CI 中扫描。
• 中文为主：README 用中文撰写并在末尾附英文摘要；代码、提交信息与 CI 用英文。
• 不直接向 main 推送：每项工作开分支、走 PR、CI 全绿后合并，同一时间一个会话只动一个模块。详见 CONTRIBUTING.md，变更记录见 CHANGELOG.md。

FAQ

没有 Ollama 能用吗？ 可以启动网关、读取精确页面与契约、管理提案，并在 Native 索引不可用时使用同一 Git 提交上的关键词回退；响应会标成降级。完整关键词+向量混合检索和索引重建需要 Ollama-compatible embedding 服务，参考配置见 setup。

我的数据会离开我的电脑吗？ Vault、索引、审批记录和本仓库提供的网关按本地运行设计；本仓库不发布个人内容，并在 CI 中扫描私人绝对路径。复盘时对话历史是否离开本机，取决于你选择的 Agent 宿主、模型和隐私设置；应使用本地或已获批准的宿主，并只授予完成复盘所需的任务历史。

和 mem0 / Basic Memory 这类项目什么关系？ 同一问题空间（给 Agent 的持久记忆），不同立场：它们优先"无感自动记忆"，这里优先"可审计的知识资产"——写入有审批门，证据有成熟度。两者可以共存。

为什么大多数 Skill 仍然很薄？ Schema、知识路由和写入审批规则由网关的当前契约返回，所以采集与入库 Skill 主要负责把 Agent 引到正确入口。lab-retrospective 是例外之一：它把模式选择、逐轮账本、声明核验和覆盖门作为稳定执行协议随 Skill 发布；具体领域方法与 Schema 仍留在知识库和网关中演进。

可以商用吗？ lab-trust-core/ 采用 MIT License，可以按该许可证商用。仓库其余部分允许个人与非商业用途；商业使用需要书面授权，见 License。

License

除明确例外外，本仓库采用 PolyForm Noncommercial License 1.0.0：个人与非商业用途（个人学习、研究、实验、爱好项目，以及慈善、教育、公共研究、公共安全与健康、环保、政府机构的使用）可自由查看、使用、修改和分发；任何商业用途需另行取得著作权人的书面授权。**例外：lab-trust-core/ 按其目录内的 MIT License 独立授权，根目录的 PolyForm 条款不替代该许可。**第三方组件见 THIRD_PARTY_NOTICES.md。

English summary

Full English documentation: README.en.md

Personal-Ontology is an original workbench for letting AI agents maintain knowledge about you over the long run — traceably, and only with your approval. It consists of one complete system, one standalone Trust Core, and four Skills.

lab-ontology is the foundation: a schema-governed Obsidian vault skeleton (Markdown + Git as the only source of truth), an MCP gateway named agent-knowledge that exposes 13 knowledge_* tools for precision-first reading and proposal-gated writing, and Agent Knowledge 1.8.0's Native hybrid index. Its vectors, typed relationships and human navigation index are rebuildable; unhealthy Native retrieval visibly falls back to keyword recall over the same Git commit. Full vector search uses an Ollama-compatible embedding service.

lab-trust-core is an independent MIT-licensed policy core. Given a knowledge record and an intended use, its SDK, CLI or read-only MCP returns an explainable trust verdict and promotion check. It stores and retrieves nothing and does not require lab-ontology. Agent Knowledge 1.8.0 pins it for a non-enforcing post-read shadow diagnostic; that shadow never blocks delivery or authorizes writes.

The skills follow the flow of knowledge. lab-wx-distillation extracts an evidence-bounded personal operating model from existing records (WeChat 4.x exports) with a deterministic local pipeline; lab-life-reviewer collects what records never captured through interview-led life review; lab-retrospective audits finished, paused or failed work in conclusion or forensic mode, reports raw-turn and completion-claim coverage as COMPLETE/PARTIAL, then decides what deserves to survive with evidence and sample size attached; lab-intake is the single entry point that turns anything worth keeping into an exact proposal and waits for approval.

The repository root is a catalog; each component contains its authoritative installation, privacy, validation and usage documentation. No private interview content, personal evidence pages or assets are published here.