{
"canonical_name": "jmiaie/ompa",
"compilation_id": "pack_9a2b0fefb08946ddbc0853308eaf6fc7",
"created_at": "2026-05-13T05:27:53.708208+00:00",
"created_by": "project-pack-compiler",
"feedback": {
"carrier_selection_notes": [
"viable_asset_types=mcp_config, recipe, host_instruction, eval, preflight",
"recommended_asset_types=mcp_config, recipe, host_instruction, eval, preflight"
],
"evidence_delta": {
"confirmed_claims": [
"identity_anchor_present",
"capability_and_host_targets_present",
"install_path_declared_or_better"
],
"missing_required_fields": [],
"must_verify_forwarded": [
"Run or inspect `pip install ompa` in an isolated environment.",
"Confirm the project exposes the claimed capability to at least one target host."
],
"quickstart_execution_scope": "allowlisted_sandbox_smoke",
"sandbox_command": "pip install ompa",
"sandbox_container_image": "python:3.12-slim",
"sandbox_execution_backend": "docker",
"sandbox_planner_decision": "deterministic_isolated_install",
"sandbox_validation_id": "sbx_6dd4f33e53224600bd9e31b10d78ea62"
},
"feedback_event_type": "project_pack_compilation_feedback",
"learning_candidate_reasons": [],
"template_gaps": []
},
"identity": {
"canonical_id": "project_08253b0054ad046fab73af989cea4e10",
"canonical_name": "jmiaie/ompa",
"homepage_url": null,
"license": "unknown",
"repo_url": "https://github.com/jmiaie/ompa",
"slug": "ompa",
"source_packet_id": "phit_dbfd6fa991454331a43fbe9a96038b6d",
"source_validation_id": "dval_f36a29492d3047ee85d07d51a5cc5d62"
},
"merchandising": {
"best_for": "需要信息检索与知识管理能力，并使用 mcp_host的用户",
"github_forks": 0,
"github_stars": 2,
"one_liner_en": "Universal AI agent memory layer — vault + palace + temporal knowledge graph",
"one_liner_zh": "Universal AI agent memory layer — vault + palace + temporal knowledge graph",
"primary_category": {
"category_id": "research-knowledge",
"confidence": "medium",
"name_en": "Research & Knowledge",
"name_zh": "信息检索与知识管理",
"reason": "matched_keywords:knowledge, graph"
},
"target_user": "使用 mcp_host 等宿主 AI 的用户",
"title_en": "ompa",
"title_zh": "ompa 能力包",
"visible_tags": [
{
"label_en": "Security & Permissions",
"label_zh": "安全审查与权限治理",
"source": "repo_evidence_project_characteristics",
"tag_id": "product_domain-security-permissions",
"type": "product_domain"
},
{
"label_en": "Knowledge Base Q&A",
"label_zh": "知识库问答",
"source": "repo_evidence_project_characteristics",
"tag_id": "user_job-knowledge-base-q-a",
"type": "user_job"
},
{
"label_en": "Multi-agent Collaboration",
"label_zh": "多 Agent 协作",
"source": "repo_evidence_project_characteristics",
"tag_id": "core_capability-multi-agent-collaboration",
"type": "core_capability"
},
{
"label_en": "Multi-role Workflow",
"label_zh": "多角色协作流程",
"source": "repo_evidence_project_characteristics",
"tag_id": "workflow_pattern-multi-role-workflow",
"type": "workflow_pattern"
},
{
"label_en": "Evaluation Suite",
"label_zh": "评测体系",
"source": "repo_evidence_project_characteristics",
"tag_id": "selection_signal-evaluation-suite",
"type": "selection_signal"
}
]
},
"packet_id": "phit_dbfd6fa991454331a43fbe9a96038b6d",
"page_model": {
"artifacts": {
"artifact_slug": "ompa",
"files": [
"PROJECT_PACK.json",
"QUICK_START.md",
"PROMPT_PREVIEW.md",
"HUMAN_MANUAL.md",
"AI_CONTEXT_PACK.md",
"BOUNDARY_RISK_CARD.md",
"PITFALL_LOG.md",
"REPO_INSPECTION.json",
"REPO_INSPECTION.md",
"CAPABILITY_CONTRACT.json",
"EVIDENCE_INDEX.json",
"CLAIM_GRAPH.json"
],
"required_files": [
"PROJECT_PACK.json",
"QUICK_START.md",
"PROMPT_PREVIEW.md",
"HUMAN_MANUAL.md",
"AI_CONTEXT_PACK.md",
"BOUNDARY_RISK_CARD.md",
"PITFALL_LOG.md",
"REPO_INSPECTION.json"
]
},
"detail": {
"capability_source": "Project Hit Packet + DownstreamValidationResult",
"commands": [
{
"command": "pip install ompa",
"label": "Python / pip · 官方安装入口",
"source": "https://github.com/jmiaie/ompa#readme",
"verified": true
}
],
"display_tags": [
"安全审查与权限治理",
"知识库问答",
"多 Agent 协作",
"多角色协作流程",
"评测体系"
],
"eyebrow": "信息检索与知识管理",
"glance": [
{
"body": "判断自己是不是目标用户。",
"label": "最适合谁",
"value": "需要信息检索与知识管理能力，并使用 mcp_host的用户"
},
{
"body": "先理解能力边界，再决定是否继续。",
"label": "核心价值",
"value": "Universal AI agent memory layer — vault + palace + temporal knowledge graph"
},
{
"body": "未完成验证前保持审慎。",
"label": "继续前",
"value": "publish to Doramagic.ai project surfaces"
}
],
"guardrail_source": "Boundary & Risk Card",
"guardrails": [
{
"body": "Prompt Preview 只展示流程，不证明项目已安装或运行。",
"label": "Check 1",
"value": "不要把试用当真实运行"
},
{
"body": "mcp_host",
"label": "Check 2",
"value": "确认宿主兼容"
},
{
"body": "publish to Doramagic.ai project surfaces",
"label": "Check 3",
"value": "先隔离验证"
}
],
"mode": "mcp_config, recipe, host_instruction, eval, preflight",
"pitfall_log": {
"items": [
{
"body": "GitHub 社区证据显示该项目存在一个安装相关的待验证问题：OMPA v0.2.0 — The Big Rename",
"category": "安装坑",
"evidence": [
"community_evidence:github | cevd_ac771ab081be444ab18c5c1963becb64 | https://github.com/jmiaie/ompa/releases/tag/v0.2.0 | 来源讨论提到 python 相关条件，需在安装/试用前复核。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：OMPA v0.2.0 — The Big Rename",
"user_impact": "可能阻塞安装或首次运行。"
},
{
"body": "GitHub 社区证据显示该项目存在一个配置相关的待验证问题：[P0] agent_integration.py race condition — session.memory attribute not available on cold start",
"category": "配置坑",
"evidence": [
"community_evidence:github | cevd_db65ef8ac28c41048d74c03c80cbed28 | https://github.com/jmiaie/ompa/issues/6 | 来源讨论提到 python 相关条件，需在安装/试用前复核。"
],
"severity": "medium",
"suggested_check": "来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。",
"title": "来源证据：[P0] agent_integration.py race condition — session.memory attribute not available on cold start",
"user_impact": "可能阻塞安装或首次运行。"
},
{
"body": "README/documentation is current enough for a first validation pass.",
"category": "能力坑",
"evidence": [
"capability.assumptions | github_repo:1207151629 | https://github.com/jmiaie/ompa | README/documentation is current enough for a first validation pass."
],
"severity": "medium",
"suggested_check": "将假设转成下游验证清单。",
"title": "能力判断依赖假设",
"user_impact": "假设不成立时，用户拿不到承诺的能力。"
},
{
"body": "未记录 last_activity_observed。",
"category": "维护坑",
"evidence": [
"evidence.maintainer_signals | github_repo:1207151629 | https://github.com/jmiaie/ompa | last_activity_observed missing"
],
"severity": "medium",
"suggested_check": "补 GitHub 最近 commit、release、issue/PR 响应信号。",
"title": "维护活跃度未知",
"user_impact": "新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。"
},
{
"body": "no_demo",
"category": "安全/权限坑",
"evidence": [
"downstream_validation.risk_items | github_repo:1207151629 | https://github.com/jmiaie/ompa | no_demo; severity=medium"
],
"severity": "medium",
"suggested_check": "进入安全/权限治理复核队列。",
"title": "下游验证发现风险项",
"user_impact": "下游已经要求复核，不能在页面中弱化。"
},
{
"body": "No sandbox install has been executed yet; downstream must verify before user use.",
"category": "安全/权限坑",
"evidence": [
"risks.safety_notes | github_repo:1207151629 | https://github.com/jmiaie/ompa | No sandbox install has been executed yet; downstream must verify before user use."
],
"severity": "medium",
"suggested_check": "转成明确权限清单和安全审查提示。",
"title": "存在安全注意事项",
"user_impact": "用户安装前需要知道权限边界和敏感操作。"
},
{
"body": "no_demo",
"category": "安全/权限坑",
"evidence": [
"risks.scoring_risks | github_repo:1207151629 | https://github.com/jmiaie/ompa | no_demo; severity=medium"
],
"severity": "medium",
"suggested_check": "把风险写入边界卡，并确认是否需要人工复核。",
"title": "存在评分风险",
"user_impact": "风险会影响是否适合普通用户安装。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：OMPA v0.2.1 — Security & Reliability Hardening",
"category": "安全/权限坑",
"evidence": [
"community_evidence:github | cevd_ab0ad6b963354f2096bef6783c95c289 | https://github.com/jmiaie/ompa/releases/tag/v0.2.1 | 来源讨论提到 python 相关条件，需在安装/试用前复核。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：OMPA v0.2.1 — Security & Reliability Hardening",
"user_impact": "可能阻塞安装或首次运行。"
},
{
"body": "issue_or_pr_quality=unknown。",
"category": "维护坑",
"evidence": [
"evidence.maintainer_signals | github_repo:1207151629 | https://github.com/jmiaie/ompa | issue_or_pr_quality=unknown"
],
"severity": "low",
"suggested_check": "抽样最近 issue/PR，判断是否长期无人处理。",
"title": "issue/PR 响应质量未知",
"user_impact": "用户无法判断遇到问题后是否有人维护。"
},
{
"body": "release_recency=unknown。",
"category": "维护坑",
"evidence": [
"evidence.maintainer_signals | github_repo:1207151629 | https://github.com/jmiaie/ompa | release_recency=unknown"
],
"severity": "low",
"suggested_check": "确认最近 release/tag 和 README 安装命令是否一致。",
"title": "发布节奏不明确",
"user_impact": "安装命令和文档可能落后于代码，用户踩坑概率升高。"
}
],
"source": "ProjectPitfallLog + ProjectHitPacket + validation + community signals",
"summary": "发现 10 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：安装坑 - 来源证据：OMPA v0.2.0 — The Big Rename。",
"title": "踩坑日志"
},
"snapshot": {
"contributors": 4,
"forks": 0,
"license": "unknown",
"note": "GitHub API 快照，非实时质量证明；用于开工前背景判断。",
"stars": 2,
"open_issues": 5,
"pushed_at": "2026-05-13T02:06:54.000Z"
},
"source_url": "https://github.com/jmiaie/ompa",
"steps": [
{
"body": "不安装项目，先体验能力节奏。",
"code": "preview",
"title": "先试 Prompt"
},
{
"body": "理解输入、输出、失败模式和边界。",
"code": "manual",
"title": "读说明书"
},
{
"body": "把上下文交给宿主 AI 继续工作。",
"code": "context",
"title": "带给 AI"
},
{
"body": "进入主力环境前先完成安装入口与风险边界验证。",
"code": "verify",
"title": "沙箱验证"
}
],
"subtitle": "Universal AI agent memory layer — vault + palace + temporal knowledge graph",
"title": "ompa 能力包",
"trial_prompt": "# ompa - Prompt Preview\n\n> 复制下面这段 Prompt 到你常用的 AI，先试一次，不需要安装。\n> 它的目标是让你直接体验这个项目的服务方式，而不是阅读项目介绍。\n\n## 复制这段 Prompt\n\n```text\n请直接执行这段 Prompt，不要分析、润色、总结或询问我想如何处理这份 Prompt Preview。\n\n你现在扮演 ompa 的“安装前体验版”。\n这不是项目介绍、不是评价报告、不是 README 总结。你的任务是让我用最小成本体验它的核心服务。\n\n我的试用任务：我想快速理解一组资料，并得到结构化摘要、对比和继续研究的问题。\n我常用的宿主 AI：MCP Client\n\n【体验目标】\n围绕我的真实任务，现场演示这个项目如何把输入转成 示例引导, 判断线索。重点是让我感受到工作方式，而不是给我项目背景。\n\n【业务流约束】\n- 你必须像一个正在提供服务的项目能力包，而不是像一个讲解员。\n- 每一轮只推进一个步骤；提出问题后必须停下来等我回答。\n- 每一步都必须让我感受到一个具体服务动作：澄清、整理、规划、检查、判断或收尾。\n- 每一步都要说明：当前目标、你需要我提供什么、我回答后你会产出什么。\n- 不要安装、不要运行命令、不要写代码、不要声称测试通过、不要声称已经修改文件。\n- 需要真实安装或宿主加载后才能验证的内容，必须明确说“这一步需要安装后验证”。\n- 如果我说“用示例继续”，你可以用虚构示例推进，但仍然不能声称真实执行。\n\n【可体验服务能力】\n- 安装前能力预览: Universal AI agent memory layer — vault + palace + temporal knowledge graph 输入：用户任务, 当前 AI 对话上下文；输出：示例引导, 判断线索。\n\n【必须安装后才可验证的能力】\n- 命令行启动或安装流程: 项目文档中存在可执行命令，真实使用需要在本地或宿主环境中运行这些命令。 输入：终端环境, 包管理器, 项目依赖；输出：安装结果, 列表/更新/运行结果。\n\n【核心服务流】\n请严格按这个顺序带我体验。不要一次性输出完整流程：\n1. intro：项目介绍。围绕“项目介绍”模拟一次用户任务，不展示安装或运行结果。\n2. quickstart：快速入门。围绕“快速入门”模拟一次用户任务，不展示安装或运行结果。\n3. three-layer-design：三层架构设计。围绕“三层架构设计”模拟一次用户任务，不展示安装或运行结果。\n4. lifecycle-hooks：生命周期钩子。围绕“生命周期钩子”模拟一次用户任务，不展示安装或运行结果。\n5. vault：Vault存储层。围绕“Vault存储层”模拟一次用户任务，不展示安装或运行结果。\n\n【核心能力体验剧本】\n每一步都必须按“输入 -> 服务动作 -> 中间产物”执行。不要只说流程名：\n1. intro\n输入：用户提供的“项目介绍”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n2. quickstart\n输入：用户提供的“快速入门”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n3. three-layer-design\n输入：用户提供的“三层架构设计”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n4. lifecycle-hooks\n输入：用户提供的“生命周期钩子”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n5. vault\n输入：用户提供的“Vault存储层”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n【项目服务规则】\n这些规则决定你如何服务用户。不要解释规则本身，而要在每一步执行时遵守：\n- 先确认用户任务、输入材料和成功标准，再模拟项目能力。\n- 每一步都必须形成可检查的小产物，并等待用户确认后再继续。\n- 凡是需要安装、调用工具或访问外部服务的能力，都必须标记为安装后验证。\n\n【每一步的服务约束】\n- Step 1 / intro：Step 1 必须围绕“项目介绍”形成一个小中间产物，并等待用户确认。\n- Step 2 / quickstart：Step 2 必须围绕“快速入门”形成一个小中间产物，并等待用户确认。\n- Step 3 / three-layer-design：Step 3 必须围绕“三层架构设计”形成一个小中间产物，并等待用户确认。\n- Step 4 / lifecycle-hooks：Step 4 必须围绕“生命周期钩子”形成一个小中间产物，并等待用户确认。\n- Step 5 / vault：Step 5 必须围绕“Vault存储层”形成一个小中间产物，并等待用户确认。\n\n【边界与风险】\n- 不要声称已经安装、运行、调用 API、读写本地文件或完成真实任务。\n- 安装前预览只能展示工作方式，不能证明兼容性、性能或输出质量。\n- 涉及安装、插件加载、工具调用或外部服务的能力必须安装后验证。\n\n【可追溯依据】\n这些路径只用于你内部校验或在我追问“依据是什么”时简要引用。不要在首次回复主动展开：\n- https://github.com/jmiaie/ompa\n- https://github.com/jmiaie/ompa#readme\n- README.md\n- pyproject.toml\n- docs/quickstart.md\n- ompa/__init__.py\n- examples/simple_vault/demo.py\n- ompa/vault.py\n- ompa/palace.py\n- ompa/knowledge_graph.py\n- ompa/hooks.py\n- ompa/core.py\n\n【首次问题规则】\n- 首次三问必须先确认用户目标、成功标准和边界，不要提前进入工具、安装或实现细节。\n- 如果后续需要技术条件、文件路径或运行环境，必须等用户确认目标后再追问。\n\n首次回复必须只输出下面 4 个部分：\n1. 体验开始：用 1 句话说明你将带我体验 ompa 的核心服务。\n2. 当前步骤：明确进入 Step 1，并说明这一步要解决什么。\n3. 你会如何服务我：说明你会先改变我完成任务的哪个动作。\n4. 只问我 3 个问题，然后停下等待回答。\n\n首次回复禁止输出：后续完整流程、证据清单、安装命令、项目评价、营销文案、已经安装或运行的说法。\n\nStep 1 / brainstorming 的二轮协议：\n- 我回答首次三问后，你仍然停留在 Step 1 / brainstorming，不要进入 Step 2。\n- 第二次回复必须产出 6 个部分：澄清后的任务定义、成功标准、边界条件、\n 2-3 个可选方案、每个方案的权衡、推荐方案。\n- 第二次回复最后必须问我是否确认推荐方案；只有我明确确认后，才能进入下一步。\n- 第二次回复禁止输出 git worktree、代码计划、测试文件、命令或真实执行结果。\n\n后续对话规则：\n- 我回答后，你先完成当前步骤的中间产物并等待确认；只有我确认后，才能进入下一步。\n- 每一步都要生成一个小的中间产物，例如澄清后的目标、计划草案、测试意图、验证清单或继续/停止判断。\n- 所有演示都写成“我会建议/我会引导/这一步会形成”，不要写成已经真实执行。\n- 不要声称已经测试通过、文件已修改、命令已运行或结果已产生。\n- 如果某个能力必须安装后验证，请直接说“这一步需要安装后验证”。\n- 如果证据不足，请明确说“证据不足”，不要补事实。\n```\n",
"voices": [
{
"body": "来源平台：github, x。github/github_issue: [P0] agent_integration.py race condition — session.memory attribute not （https://github.com/jmiaie/ompa/issues/6）；github/github_release: OMPA v0.2.1 — Security & Reliability Hardening（https://github.com/jmiaie/ompa/releases/tag/v0.2.1）；github/github_release: OMPA v0.2.0 — The Big Rename（https://github.com/jmiaie/ompa/releases/tag/v0.2.0）；x: 100+ agentic skills, commands, and plugins for PMs. Designed for ...（https://x.com/PawelHuryn/status/2028902562905416087）；x: Zero-human company tech Open-source AI Agent orchestration ...（https://x.com/tomosman/status/2029811313182982315）。这些是项目级外部声音，不作为单独质量证明。",
"items": [
{
"kind": "github_issue",
"source": "github",
"title": "[P0] agent_integration.py race condition — session.memory attribute not ",
"url": "https://github.com/jmiaie/ompa/issues/6"
},
{
"kind": "github_release",
"source": "github",
"title": "OMPA v0.2.1 — Security & Reliability Hardening",
"url": "https://github.com/jmiaie/ompa/releases/tag/v0.2.1"
},
{
"kind": "github_release",
"source": "github",
"title": "OMPA v0.2.0 — The Big Rename",
"url": "https://github.com/jmiaie/ompa/releases/tag/v0.2.0"
},
{
"kind": "searxng_indexed",
"source": "x",
"title": "100+ agentic skills, commands, and plugins for PMs. Designed for ...",
"url": "https://x.com/PawelHuryn/status/2028902562905416087"
},
{
"kind": "searxng_indexed",
"source": "x",
"title": "Zero-human company tech Open-source AI Agent orchestration ...",
"url": "https://x.com/tomosman/status/2029811313182982315"
}
],
"status": "已收录 5 条来源",
"title": "社区讨论"
}
]
},
"homepage_card": {
"category": "信息检索与知识管理",
"desc": "Universal AI agent memory layer — vault + palace + temporal knowledge graph",
"effort": "安装已验证",
"forks": 0,
"icon": "search",
"name": "ompa 能力包",
"risk": "可发布",
"slug": "ompa",
"stars": 2,
"tags": [
"安全审查与权限治理",
"知识库问答",
"多 Agent 协作",
"多角色协作流程",
"评测体系"
],
"thumb": "blue",
"type": "MCP 配置"
},
"manual": {
"markdown": "# https://github.com/jmiaie/ompa 项目说明书\n\n生成时间：2026-05-13 05:17:58 UTC\n\n## 目录\n\n- [项目介绍](#intro)\n- [快速入门](#quickstart)\n- [三层架构设计](#three-layer-design)\n- [生命周期钩子](#lifecycle-hooks)\n- [Vault存储层](#vault)\n- [Palace元数据层](#palace)\n- [时序知识图谱](#knowledge-graph)\n- [消息分类器](#classifier)\n- [MCP服务器集成](#mcp-server)\n- [框架适配器](#adapters)\n\n\n\n## 项目介绍\n\n### 相关页面\n\n相关主题：[快速入门](#quickstart), [三层架构设计](#three-layer-design)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/jmiaie/ompa/blob/main/README.md)\n- [CLAUDE.md](https://github.com/jmiaie/ompa/blob/main/CLAUDE.md)\n- [CONTRIBUTING.md](https://github.com/jmiaie/ompa/blob/main/CONTRIBUTING.md)\n- [CHANGELOG.md](https://github.com/jmiaie/ompa/blob/main/CHANGELOG.md)\n- [STABILITY.md](https://github.com/jmiaie/ompa/blob/main/STABILITY.md)\n- [examples/mcp_desktop/README.md](https://github.com/jmiaie/ompa/blob/main/examples/mcp_desktop/README.md)\n- [ompa/core.py](https://github.com/jmiaie/ompa/blob/main/ompa/core.py)\n- [ompa/classifier.py](https://github.com/jmiaie/ompa/blob/main/ompa/classifier.py)\n \n\n# 项目介绍\n\n## 概述\n\n**OMPA**（Obsidian-MemPalace-Agnostic）是一个专为 AI Agent 设计的记忆管理系统，旨在为 Claude Code、OpenClaw、Codex 等 Agent 框架提供持久化记忆能力。项目最初从 [MemPalace](https://github.com/corbt/mem_palace) 启发而来，并融合了 obsidian-mind 等社区项目的优秀理念。\n\n资料来源：[README.md:1]()\n\nOMPA 的核心理念是**逐字存储**（verbatim storage）而非摘要，确保记忆的完整性和可追溯性。根据 MemPalace 的研究验证，逐字存储方案可达到 96.6% 的检索准确率（Recall@5）。\n\n资料来源：[CLAUDE.md:1]()\n\n## 核心定位\n\nOMPA 解决的核心问题是：**AI Agent 在长时间会话中如何有效管理、检索和利用历史信息**。\n\n传统 Agent 框架面临以下挑战：\n\n| 挑战 | OMPA 解决方案 |\n|------|--------------|\n| 上下文窗口有限 | 分层记忆架构，按需注入相关上下文 |\n| 记忆检索困难 | 语义搜索 + 知识图谱双引擎 |\n| 团队/个人内容混淆 | 双保险库（Dual-Vault）隔离机制 |\n| 框架绑定 | 纯 Python 实现，无 Agent SDK 依赖 |\n\n资料来源：[README.md:1]()\n\n## 技术架构\n\n### 整体架构图\n\n```mermaid\ngraph TB\n subgraph \"Agent Layer\"\n ClaudeCode[Claude Code]\n OpenClaw[OpenClaw]\n Codex[Codex]\n GeminiCLI[Gemini CLI]\n end\n\n subgraph \"OMPA Core\"\n Core[Ompa 核心类]\n Classifier[消息分类器]\n Hooks[生命周期钩子]\n end\n\n subgraph \"Storage Layer\"\n Vault[(Vault
记忆存储)]\n Palace[(Palace
宫殿元数据)]\n KG[(Knowledge Graph
时序知识图谱)]\n Semantic[Semantic Index
语义索引]\n end\n\n ClaudeCode --> Core\n OpenClaw --> Core\n Codex --> Core\n GeminiCLI --> Core\n\n Core --> Classifier\n Core --> Hooks\n Core --> Vault\n Core --> Palace\n Core --> KG\n Core --> Semantic\n```\n\n### 模块说明\n\n| 模块 | 文件路径 | 职责 |\n|------|---------|------|\n| **core.py** | `ompa/core.py` | Ompa 主类 — 生命周期管理、消息处理、双保险库 |\n| **vault.py** | `ompa/vault.py` | 保险库管理 — brain/work/org/perf 文件夹 CRUD |\n| **palace.py** | `ompa/palace.py` | 宫殿元数据 — wings/rooms/drawers/halls/tunnels |\n| **knowledge_graph.py** | `ompa/knowledge_graph.py` | 时序知识图谱 — SQLite 三元组 + 有效期窗口 |\n| **hooks.py** | `ompa/hooks.py` | 5 个生命周期钩子 + HookManager |\n| **classifier.py** | `ompa/classifier.py` | 15 种消息类型 + 自动路由 |\n| **semantic.py** | `ompa/semantic.py` | 本地语义搜索（延迟模型加载） |\n| **mcp_server.py** | `ompa/mcp_server.py` | MCP 协议服务器（15 个工具） |\n| **config.py** | `ompa/config.py` | 双保险库配置 |\n| **cli.py** | `ompa/cli.py` | Typer CLI（14 个命令） |\n\n资料来源：[README.md:1]()\n\n## 核心功能特性\n\n### 1. 双保险库架构（Dual-Vault）\n\nOMPA 支持将团队/组织内容与个人/私密笔记隔离存储：\n\n```python\nfrom ompa import Ompa, DualVaultConfig, IsolationMode\n\nconfig = DualVaultConfig(\n shared_vault=\"./team-vault\",\n personal_vault=\"./private-vault\",\n mode=IsolationMode.AUTO,\n)\nao = Ompa(config=config)\n```\n\n**隔离模式（IsolationMode）**：\n\n| 模式 | 说明 |\n|------|------|\n| `AUTO` | 根据消息类型自动分类到共享或个人保险库 |\n| `MANUAL` | 每个操作显式指定 `VaultTarget` |\n| `STRICT` | 强制隔离，不允许跨保险库访问 |\n\n资料来源：[README.md:1]()\n\n### 2. 消息自动分类\n\nOMPA 内置 15 种消息类型分类器，自动识别并路由消息到对应文件夹：\n\n```mermaid\ngraph LR\n Input[用户消息] --> Classifier[Classifier]\n Classifier --> DEC[DECISION]\n Classifier --> INC[INCIDENT]\n Classifier --> WIN[WIN]\n Classifier --> O1O[ONE_ON_ONE]\n Classifier --> Q[QUESTION]\n Classifier --> OTHER[...]\n```\n\n**消息类型列表**：\n\n| 枚举值 | 触发关键词 | 路由目标 |\n|--------|-----------|---------|\n| `DECISION` | decided, agreed, settled | brain/decisions/ |\n| `INCIDENT` | incident, outage, bug | brain/incidents/ |\n| `WIN` | won, shipped, launched | brain/wins/ |\n| `ONE_ON_ONE` | 1:1, feedback, career | org/1on1/ |\n| `MEETING` | meeting, standup | org/meetings/ |\n| `PROJECT_UPDATE` | project, blocked, sprint | org/projects/ |\n| `PERSON_INFO` | teammate, joined, role | org/people/ |\n| `QUESTION` | how do, what is, why | brain/questions/ |\n| `TASK` | todo, action item | work/tasks/ |\n| `ARCHITECTURE` | architecture, design | brain/architecture/ |\n| `CODE` | code, function, PR | brain/code/ |\n| `BRAIN_DUMP` | dump, stream | brain/dumps/ |\n| `WRAP_UP` | wrap up, end session | brain/sessions/ |\n| `STANDUP` | standup, daily | org/standups/ |\n\n资料来源：[ompa/classifier.py:1]()\n\n### 3. 时序知识图谱（Temporal Knowledge Graph）\n\nKG 使用 SQLite 存储三元组，支持时间维度查询：\n\n```python\n# 添加带时间窗口的三元组\nao.kg.add_triple(\"Kai\", \"works_on\", \"Orion\", valid_from=\"2025-06-01\")\n\n# 查询实体历史\ntriples = ao.kg.query_entity(\"Kai\")\n\n# 查询时间线\ntimeline = ao.kg.timeline(\"Orion\")\n```\n\n**数据模型**：\n\n```\nTriple(subject, predicate, object, valid_from, valid_to, confidence, source_file)\n```\n\n资料来源：[README.md:1]()\n\n### 4. 本地语义搜索\n\nOMPA 提供本地语义索引，无需 API 调用即可实现语义搜索：\n\n```python\nresults = ao.search(\"authentication decisions\", wing=\"Orion\")\n```\n\n**特性**：\n\n- 延迟加载模型，首次访问时才下载\n- 增量索引，仅重新嵌入修改过的文件\n- 支持 wing/room 级别的范围搜索\n\n资料来源：[README.md:1]()\n\n### 5. 生命周期钩子系统\n\n支持 5 个生命周期钩子，允许自定义扩展：\n\n```python\nclass MyHook(Hook):\n def __init__(self):\n super().__init__(\"my_hook\", token_budget=50)\n\n def execute(self, context: HookContext, **kwargs) -> HookResult:\n return HookResult(hook_name=self.name, success=True, output=\"...\", tokens_hint=50)\n\nao = Ompa(\"./workspace\")\nao.hooks.register_hook(\"my_hook\", MyHook())\n```\n\n资料来源：[CLAUDE.md:1]()\n\n## 安装与使用\n\n### 安装方式\n\n```bash\n# 核心功能\npip install ompa\n\n# 含本地语义搜索（首次运行下载约 500MB 模型）\npip install ompa[all]\n\n# 开发模式\npip install ompa[dev]\n```\n\n**环境要求**：Python 3.10+\n\n资料来源：[README.md:1]()\n\n### CLI 命令参考\n\n| 命令 | 功能 |\n|------|------|\n| `ao init` | 初始化新保险库 |\n| `ao status` | 健康检查和统计 |\n| `ao session-start` | 注入记忆上下文 |\n| `ao classify ` | 分类并路由消息 |\n| `ao search ` | 语义搜索 |\n| `ao orphans` | 检测孤立笔记 |\n| `ao wrap-up` | 会话总结并保存 |\n| `ao wings` | 列出宫殿 wing |\n| `ao rooms ` | 列出 wing 中的房间 |\n| `ao tunnel` | 创建/穿越跨 wing 隧道 |\n| `ao kg-query ` | 查询知识图谱 |\n| `ao validate` | 验证保险库结构 |\n| `ao rebuild-index` | 重建语义索引 |\n\n资料来源：[README.md:1]()\n\n### MCP 集成\n\nOMPA 提供 MCP（Model Context Protocol）服务器，可与 Claude Desktop、Cursor、Windsurf 等 IDE 集成：\n\n```bash\n# Claude Desktop\nclaude mcp add ompa -- python -m ompa.mcp_server\n\n# 或手动配置 ~/.claude/claude_desktop_config.json\n{\n \"mcpServers\": {\n \"ompa\": {\n \"command\": \"python\",\n \"args\": [\"-m\", \"ompa.mcp_server\"],\n \"env\": {\n \"OMPA_VAULT_PATH\": \"/absolute/path/to/vault\"\n }\n }\n }\n}\n```\n\n**MCP 工具列表**：\n\n```\nao_session_start, ao_classify, ao_search, ao_kg_query,\nao_kg_add, ao_kg_stats, ao_palace_wings, ao_palace_rooms,\nao_palace_tunnel, ao_validate, ao_wrap_up, ao_status, \nao_orphans, ao_init\n```\n\n资料来源：[examples/mcp_desktop/README.md:1]()\n\n## Python API 基础用法\n\n```python\nfrom ompa import Ompa\n\nao = Ompa(vault_path=\"./workspace\")\n\n# 会话生命周期\ncontext = ao.session_start() # 返回约 2K token 的上下文字符串\nhint = ao.handle_message(\"We won the enterprise deal!\")\nao.post_tool(\"write\", {\"file_path\": \"work/active/auth.md\"})\nao.stop()\n\n# 语义搜索\nresults = ao.search(\"authentication decisions\", wing=\"Orion\")\n\n# 知识图谱\nao.kg.add_triple(\"Kai\", \"works_on\", \"Orion\", valid_from=\"2025-06-01\")\ntriples = ao.kg.query_entity(\"Kai\")\ntimeline = ao.kg.timeline(\"Orion\")\n```\n\n资料来源：[README.md:1]()\n\n## 框架兼容性\n\n| Agent 框架 | 集成方式 |\n|-----------|---------|\n| Claude Code | Python API + MCP 服务器 |\n| OpenClaw | Python API + MCP 服务器 |\n| Codex | Python API + MCP 服务器 |\n| Gemini CLI | Python API + MCP 服务器 |\n| LangChain | Python API |\n\n资料来源：[README.md:1]()\n\n## 适配器生态\n\nOMPA 提供多种官方适配器，便于与其他生态系统集成：\n\n```python\n# LangChain 适配器\nfrom ompa.adapters.langchain import OmpaMemory, OmpaRetriever\n\n# LlamaIndex 适配器\nfrom ompa.adapters.llamaindex import OmpaReader, OmpaVaultRetriever\n\n# OpenAI Agents SDK 适配器\nfrom ompa.adapters.openai_agents import OmpaAgentHooks\n\n# FAISS 向量索引\nfrom ompa.adapters.faiss import FAISSSemanticIndex\n```\n\n资料来源：[STABILITY.md:1]()\n\n## 版本历史\n\n| 版本 | 日期 | 主要变更 |\n|------|------|---------|\n| 0.4.x | 2026-04 | 双保险库架构、路径遍历加固、语义延迟初始化 |\n| 0.3.x | 2026-04 | KG 自动填充、增量语义索引、脑图同步 |\n| 0.2.x | 2026-04 | 项目重命名 AgnosticObsidian → Ompa |\n| 0.1.x | 2026-04 | 初始版本发布 |\n\n资料来源：[CHANGELOG.md:1]()\n\n## 安全特性\n\n| 特性 | 说明 |\n|------|------|\n| 路径遍历防护 | 所有保险库文件操作解析并边界检查路径 |\n| UTF-8 编码强制 | 所有文件写入显式指定 UTF-8 编码 |\n| 敏感信息过滤 | 导出时自动清除个人标识符 |\n\n资料来源：[CHANGELOG.md:1]()\n\n## 开发指南\n\n### 本地开发\n\n```bash\ngit clone https://github.com/jmiaie/ompa\ncd ompa\npip install -e \".[dev,all]\"\n\n# 运行测试\npytest tests/ -v\n\n# 代码检查\nruff check ompa/\nruff format ompa/\n```\n\n资料来源：[CONTRIBUTING.md:1]()\n\n### 添加新消息类型\n\n1. 在 `classifier.py` 中添加 `MessageType` 枚举值\n2. 添加正则模式到 `PATTERNS[MessageType]`\n3. 添加路由提示到 `ROUTING_HINTS[MessageType]`\n4. 添加文件夹映射到 `FOLDER_MAP[MessageType]`\n5. 在 `tests/test_ompa.py` 中添加测试用例\n\n资料来源：[CONTRIBUTING.md:1]()\n\n## 架构设计决策\n\n| 决策 | 说明 |\n|------|------|\n| 延迟语义加载 | `SemanticIndex._model` 在首次访问时加载 |\n| 框架无关性 | 纯 Python，无 Agent SDK 依赖 |\n| 保险库 + 宫殿双层 | 保险库为数据源，宫殿为检索加速层 |\n| 逐字存储 | 不做摘要，MemPalace 验证 96.6% R@5 |\n| 时序知识图谱 | SQLite 三元组 + 有效期窗口 |\n| 路径遍历守卫 | 所有文件操作解析 + 边界检查 |\n| 上下文管理器 | SQLite 连接使用 `with` 确保无泄漏 |\n\n资料来源：[CLAUDE.md:1]()\n\n## 致谢\n\nOMPA 是 AI Agent 记忆社区优秀理念的集大成者：\n\n- **[MemPalace](https://github.com/corbt/mem_palace)** by Kyle Corbitt — 宫殿隐喻（wings/rooms/drawers/halls/tunnels）\n- **obsidian-mind** — Obsidian 记忆系统\n- **Claude Code** — Agent 框架参考\n- **OpenClaw** — Agent 框架参考\n\n资料来源：[README.md:1]()\n\n---\n\n\n\n## 快速入门\n\n### 相关页面\n\n相关主题：[项目介绍](#intro)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/jmiaie/ompa/blob/main/README.md)\n- [examples/mcp_desktop/README.md](https://github.com/jmiaie/ompa/blob/main/examples/mcp_desktop/README.md)\n- [CONTRIBUTING.md](https://github.com/jmiaie/ompa/blob/main/CONTRIBUTING.md)\n- [STABILITY.md](https://github.com/jmiaie/ompa/blob/main/STABILITY.md)\n- [CLAUDE.md](https://github.com/jmiaie/ompa/blob/main/CLAUDE.md)\n- [ompa/core.py](https://github.com/jmiaie/ompa/blob/main/ompa/core.py)\n- [ompa/mcp_server.py](https://github.com/jmiaie/ompa/blob/main/ompa/mcp_server.py)\n \n\n# 快速入门\n\n本文档面向希望快速上手 OMPA（Obsidian-MemPalace-Agnostic）的开发者。OMPA 是一个与框架无关的 AI Agent 记忆系统，提供 Vault 存储、Palace 记忆加速和 Temporal Knowledge Graph 功能。\n\n## 环境要求\n\n| 要求 | 版本/说明 |\n|------|----------|\n| Python | 3.10+ |\n| pip | 最新版 |\n\n> 资料来源：[README.md:1]()\n\n## 安装\n\nOMPA 提供多种安装方式，可根据需求选择：\n\n```bash\n# 仅核心功能（vault + palace + KG + CLI + MCP server）\npip install ompa\n\n# 包含本地语义搜索（首次运行需下载约 500MB 模型）\npip install ompa[all]\n\n# 开发版本\npip install ompa[dev]\n\n# 从源码安装\ngit clone https://github.com/jmiaie/ompa && cd ompa\npip install -e \".[all]\"\n```\n\n> 资料来源：[README.md:50-60]()\n\n## 核心概念\n\n在开始之前，了解 OMPA 的三个核心组件：\n\n```mermaid\ngraph TD\n A[Ompa 核心类] --> B[Vault 存储层]\n A --> C[Palace 检索加速]\n A --> D[Knowledge Graph 时序图谱]\n \n B --> B1[Brain Notes]\n B --> B2[Work Notes]\n B --> B3[Org Notes]\n B --> B4[Perf Notes]\n \n C --> C1[Wings 区域]\n C --> C2[Rooms 房间]\n C --> C3[Drawers 抽屉]\n \n D --> D1[Triples 三元组]\n D --> D2[Validity Windows 有效期]\n```\n\n> 资料来源：[CLAUDE.md:1]()\n\n| 组件 | 功能 | 数据存储 |\n|------|------|---------|\n| **Vault** | 笔记源文件管理 | Markdown 文件 + frontmatter |\n| **Palace** | 记忆结构化加速 | `.palace/` 元数据 |\n| **Knowledge Graph** | 时序关系图谱 | SQLite 数据库 |\n\n> 资料来源：[README.md:65-80]()\n\n## 初始化 Vault\n\nVault 是 OMPA 的源数据存储目录，包含 Brain、Work、Org、Perf 四个笔记分区。\n\n```bash\n# 初始化新的 vault\nao init\n\n# 检查 vault 健康状态\nao status\n```\n\n初始化后，将创建以下目录结构：\n\n```\n.\n├── .ompa/\n│ └── config.yaml\n├── brain/\n├── work/\n├── org/\n└── perf/\n```\n\n> 资料来源：[examples/mcp_desktop/README.md:1-10]()\n\n## CLI 快速命令\n\nOMPA 提供完整的命令行工具：\n\n```bash\n# 会话管理\nao session-start # 启动会话，注入约 2K token 上下文\nao wrap-up # 会话总结并保存\n\n# 笔记操作\nao classify # 分类并路由消息\nao search # 语义搜索\n\n# 知识图谱\nao kg-query # 查询实体\nao kg-timeline # 实体时间线\nao kg-stats # 图谱统计\n\n# Palace 导航\nao wings # 列出所有区域\nao rooms # 列出区域中的房间\nao tunnel # 创建/遍历跨区域通道\n\n# 工具\nao orphans # 检测孤立笔记\nao validate # 验证 vault 结构\nao rebuild-index # 重建语义索引\n```\n\n> 资料来源：[README.md:25-45]()\n\n## Python API 使用\n\n### 基本使用流程\n\n```python\nfrom ompa import Ompa\n\n# 初始化\nao = Ompa(vault_path=\"./workspace\")\n\n# 会话生命周期\ncontext = ao.session_start() # 获取上下文（约 2K tokens）\nhint = ao.handle_message(\"消息内容\") # 处理消息\nao.stop() # 停止会话\n\n# 语义搜索\nresults = ao.search(\"认证决策\", wing=\"Orion\")\n\n# 知识图谱\nao.kg.add_triple(\"Kai\", \"works_on\", \"Orion\", valid_from=\"2025-06-01\")\ntriples = ao.kg.query_entity(\"Kai\")\ntimeline = ao.kg.timeline(\"Orion\")\n```\n\n> 资料来源：[README.md:70-90]()\n\n### Ompa 核心类初始化参数\n\n```python\nfrom ompa import Ompa\n\nao = Ompa(\n vault_path=\"./workspace\", # Vault 路径\n agent_name=\"agent\", # Agent 名称（用于 KG 实体限定）\n enable_semantic=True, # 启用语义搜索\n embedding_backend=None, # 嵌入后端\n)\n```\n\n| 参数 | 类型 | 默认值 | 说明 |\n|------|------|--------|------|\n| `vault_path` | `str` | 必需 | Vault 根目录路径 |\n| `agent_name` | `str` | `\"agent\"` | Agent 标识符 |\n| `enable_semantic` | `bool` | `False` | 启用本地语义搜索 |\n| `embedding_backend` | `EmbeddingBackend` | `None` | 自定义嵌入后端 |\n\n> 资料来源：[STABILITY.md:10-25]()\n\n## 双 Vault 模式\n\nOMPA 支持双 Vault 架构，用于隔离团队/组织内容与个人/私密笔记。\n\n```python\nfrom ompa import Ompa, DualVaultConfig, IsolationMode\n\nconfig = DualVaultConfig(\n shared_vault=\"./team-vault\", # 共享 vault\n personal_vault=\"./private-vault\", # 个人 vault\n mode=IsolationMode.AUTO, # 自动分类模式\n)\nao = Ompa(config=config)\n```\n\n### 隔离模式\n\n| 模式 | 说明 |\n|------|------|\n| `AUTO` | 根据消息类型自动分类到共享或个人 vault |\n| `MANUAL` | 显式指定 `VaultTarget` 进行路由 |\n| `STRICT` | 严格分离，仅允许指定 vault 操作 |\n\n> 资料来源：[README.md:55-65]()\n\n### 环境变量配置\n\n| 变量 | 默认值 | 说明 |\n|------|--------|------|\n| `OMPA_VAULT_PATH` | `.` | Vault 绝对路径 |\n| `OMPA_ENABLE_SEMANTIC` | `false` | 启用本地语义搜索 |\n| `OMPA_AGENT_NAME` | `agent` | Agent 名称 |\n| `OMPA_SHARED_VAULT` | — | 双 Vault 模式下共享 vault 路径 |\n| `OMPA_PERSONAL_VAULT` | — | 双 Vault 模式下个人 vault 路径 |\n\n> 资料来源：[examples/mcp_desktop/README.md:50-60]()\n\n## MCP 服务器集成\n\nOMPA 提供 MCP（Model Context Protocol）服务器，可与 Claude Desktop、Cursor、Windsurf 等工具集成。\n\n### Claude Desktop 配置\n\n**方式一：CLI（推荐）**\n\n```bash\nclaude mcp add ompa -- python -m ompa.mcp_server\n```\n\n**方式二：手动配置**\n\n编辑 `~/.claude/claude_desktop_config.json`：\n\n```json\n{\n \"mcpServers\": {\n \"ompa\": {\n \"command\": \"python\",\n \"args\": [\"-m\", \"ompa.mcp_server\"],\n \"env\": {\n \"OMPA_VAULT_PATH\": \"/absolute/path/to/your/vault\"\n }\n }\n }\n}\n```\n\n### Cursor / Windsurf 配置\n\n创建 `.cursor/mcp.json` 或 `.windsurf/mcp.json`：\n\n```json\n{\n \"mcpServers\": {\n \"ompa\": {\n \"command\": \"python\",\n \"args\": [\"-m\", \"ompa.mcp_server\"],\n \"env\": {\n \"OMPA_VAULT_PATH\": \"${workspaceFolder}/.ompa-vault\",\n \"OMPA_ENABLE_SEMANTIC\": \"false\"\n }\n }\n }\n}\n```\n\n### MCP 可用工具\n\n| 工具 | 功能 |\n|------|------|\n| `ao_session_start` | 启动会话并注入记忆上下文 |\n| `ao_classify` | 分类消息并返回路由建议 |\n| `ao_search` | 语义搜索笔记 |\n| `ao_kg_query` | 查询知识图谱实体 |\n| `ao_kg_add` | 添加三元组到知识图谱 |\n| `ao_kg_stats` | 知识图谱统计 |\n| `ao_palace_wings` | 列出所有 Palace 区域 |\n| `ao_palace_rooms` | 列出区域中的房间 |\n| `ao_palace_tunnel` | 创建跨区域通道 |\n| `ao_validate` | 验证笔记结构 |\n| `ao_wrap_up` | 会话总结 |\n| `ao_status` | Vault 健康状态 |\n| `ao_orphans` | 检测孤立笔记 |\n| `ao_init` | 初始化 vault |\n| `ao_sync` | 同步 vault |\n| `ao_write` | 写入笔记 |\n| `ao_export` / `ao_import` | 导入导出笔记 |\n\n> 资料来源：[ompa/mcp_server.py:1-50]()\n\n## 消息分类系统\n\nOMPA 内置 15 种消息类型分类器，可自动将消息路由到正确的 vault 文件夹：\n\n```bash\nao classify \"We decided to go with Postgres\"\n```\n\n分类系统基于正则模式、路由提示和文件夹映射自动工作：\n\n1. 添加枚举值到 `MessageType`\n2. 添加正则模式到 `PATTERNS`\n3. 添加路由提示到 `ROUTING_HINTS`\n4. 添加文件夹映射到 `FOLDER_MAP`\n\n> 资料来源：[CONTRIBUTING.md:25-35]()\n\n## 项目结构\n\n```\nompa/\n├── core.py # Ompa 主类 — 生命周期、钩子、双 Vault\n├── vault.py # Vault CRUD 操作\n├── palace.py # Palace 元数据（区域/房间/抽屉/大厅/通道）\n├── knowledge_graph.py # 时序知识图谱（SQLite 三元组）\n├── hooks.py # 5 个生命周期钩子 + HookManager\n├── classifier.py # 15 种消息类型自动路由\n├── semantic.py # 本地语义搜索（惰性模型加载）\n├── mcp_server.py # MCP 协议服务器（15 个工具）\n├── config.py # 双 Vault 配置\n└── cli.py # Typer CLI（14 个命令）\n```\n\n> 资料来源：[README.md:65-80]()\n\n## 下一步\n\n- 阅读 [CLAUDE.md](https://github.com/jmiaie/ompa/blob/main/CLAUDE.md) 了解架构决策\n- 查看 [STABILITY.md](https://github.com/jmiaie/ompa/blob/main/STABILITY.md) 了解 API 稳定性承诺\n- 参考 [CONTRIBUTING.md](https://github.com/jmiaie/ompa/blob/main/CONTRIBUTING.md) 参与贡献\n\n---\n\n\n\n## 三层架构设计\n\n### 相关页面\n\n相关主题：[生命周期钩子](#lifecycle-hooks), [Vault存储层](#vault), [Palace元数据层](#palace), [时序知识图谱](#knowledge-graph)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [ompa/vault.py](https://github.com/jmiaie/ompa/blob/main/ompa/vault.py)\n- [ompa/palace.py](https://github.com/jmiaie/ompa/blob/main/ompa/palace.py)\n- [ompa/knowledge_graph.py](https://github.com/jmiaie/ompa/blob/main/ompa/knowledge_graph.py)\n- [ompa/core.py](https://github.com/jmiaie/ompa/blob/main/ompa/core.py)\n- [ompa/semantic.py](https://github.com/jmiaie/ompa/blob/main/ompa/semantic.py)\n \n\n# 三层架构设计\n\nOMPA（Obsidian-MemPalace-Agnostic）采用**三层架构设计**，将AI Agent的记忆系统分解为三个职责明确的层次：数据持久层（Vault）、元数据加速层（Palace）和时序推理层（Knowledge Graph）。这种设计遵循\"Vault是事实来源，Palace是检索加速\"的核心原则，实现了数据存储与高效检索的分离。\n\n## 架构概览\n\n```mermaid\ngraph TB\n subgraph 数据层 \"第一层：Vault（数据持久层）\"\n VAULT[\"Vault Manager
brain/work/org/perf\"]\n FILES[\"文件系统
Markdown + Frontmatter\"]\n end\n \n subgraph 加速层 \"第二层：Palace（元数据加速层）\"\n PALACE[\"Palace Manager
wings/rooms/drawers\"]\n INDEX[\"语义索引
sentence-transformers\"]\n end\n \n subgraph 推理层 \"第三层：Knowledge Graph（时序推理层）\"\n KG[\"Knowledge Graph
SQLite Triples\"]\n TEMPORAL[\"时序窗口
valid_from/valid_to\"]\n end\n \n USER[\"> 用户/Agent\"]\n \n USER --> VAULT\n USER --> PALACE\n USER --> KG\n \n VAULT --> FILES\n PALACE --> INDEX\n KG --> TEMPORAL\n \n FILES -.->|\"populate\"| KG\n INDEX -.->|\"辅助\"| PALACE\n```\n\n### 三层职责对照表\n\n| 层次 | 组件 | 职责 | 存储介质 | 数据格式 |\n|------|------|------|----------|----------|\n| 第一层 | Vault | 源数据持久化 | 文件系统 | Markdown + Frontmatter |\n| 第二层 | Palace | 元数据抽象 + 快速检索 | 内存 + 磁盘索引 | wings/rooms/drawers 结构 |\n| 第三层 | Knowledge Graph | 时序关系推理 | SQLite | 三元组 + 时效窗口 |\n\n资料来源：[CLAUDE.md:1-15](https://github.com/jmiaie/ompa/blob/main/CLAUDE.md)\n\n## 第一层：Vault（数据持久层）\n\n### 设计目标\n\nVault层作为整个记忆系统的**事实来源（Source of Truth）**，负责持久化存储所有笔记、文档和元数据。采用原文存储策略（Verbatim Storage），不进行摘要或压缩，以保证最高的信息保真度。MemPalace的研究表明，verbatim存储在LongMemEval基准上达到了96.6%的R@5召回率。\n\n### 目录结构\n\nVault采用四象限组织结构，与obsidian-mind项目的设计保持一致：\n\n```mermaid\ngraph TD\n VAULT[\"Vault Root\"]\n BRAIN[\"brain/
个人思考\"]\n WORK[\"work/
工作项目\"]\n ORG[\"org/
组织信息\"]\n PERF[\"perf/
性能数据\"]\n \n VAULT --> BRAIN\n VAULT --> WORK\n VAULT --> ORG\n VAULT --> PERF\n \n WORK --> ACTIVE[\"active/
活跃项目\"]\n WORK --> ARCHIVE[\"archive/
归档项目\"]\n PERF --> METRICS[\"metrics/
指标\"]\n PERF --> SESSIONS[\"sessions/
会话记录\"]\n```\n\n### 核心功能\n\nVault Manager提供以下核心操作：\n\n| 操作 | 方法 | 说明 |\n|------|------|------|\n| 初始化 | `Vault(vault_path)` | 创建目录结构 |\n| 统计 | `get_stats()` | 返回笔记数量、文件大小等 |\n| 笔记列表 | `list_notes()` | 遍历所有.md文件 |\n| 查找孤立笔记 | `find_orphans()` | 检测broken wikilinks |\n\n资料来源：[ompa/vault.py](https://github.com/jmiaie/ompa/blob/main/ompa/vault.py)\n\n### Frontmatter规范\n\n每条笔记都包含标准化的Frontmatter元数据：\n\n```yaml\n---\ndate: \"2025-06-01\"\ntags: [authentication, postgres, enterprise]\nvault: shared\n---\n```\n\n- `date`：创建或修改日期\n- `tags`：主题标签列表\n- `vault`：所属保险库（shared/personal，用于双库模式）\n\n### 安全机制\n\nVault层实现了完整的路径遍历防护：\n\n```python\ndef _safe_resolve(base: Path, path: str) -> Path:\n \"\"\"解析并边界检查路径\"\"\"\n full_path = (base / path).resolve()\n if not full_path.is_relative_to(base):\n raise ValueError(\"Path traversal detected\")\n return full_path\n```\n\n所有文件操作都必须经过路径解析和边界检查，防止恶意路径注入。\n\n资料来源：[CHANGELOG.md:20-25](https://github.com/jmiaie/ompa/blob/main/CHANGELOG.md)\n\n## 第二层：Palace（元数据加速层）\n\n### 设计目标\n\nPalace层在Vault之上构建元数据抽象，提供高效的导航和检索能力。采用宫殿隐喻（Palace Metaphor），将记忆空间组织为wings（翼）、rooms（房间）、drawers（抽屉）的层级结构，模拟人类记忆宫殿的空间记忆技巧。\n\n### 组织结构\n\n```mermaid\ngraph LR\n WING[\"Wing（翼）
顶级分类\"]\n ROOM[\"Room（房间）
次级分类\"]\n DRAWER[\"Drawer（抽屉）
具体主题\"]\n HALL[\"Hall（大厅）
全局连接\"]\n TUNNEL[\"Tunnel（隧道）
跨翼连接\"]\n \n WING --> ROOM\n ROOM --> DRAWER\n \n HALL -.->|\"全局\"| WING\n TUNNEL -.->|\"跨域\"| WING\n```\n\n### 层级说明\n\n| 层级 | 概念 | 用途 | 示例 |\n|------|------|------|------|\n| Wing | 翼 | 主知识领域 | Orion（猎户座命名） |\n| Room | 房间 | 子主题 | auth、database |\n| Drawer | 抽屉 | 最小单元 | postgres-config |\n| Hall | 大厅 | 全局索引 | 跨wing搜索 |\n| Tunnel | 隧道 | 跨域连接 | auth ↔ billing |\n\n资料来源：[ompa/palace.py](https://github.com/jmiaie/ompa/blob/main/ompa/palace.py)\n\n### Palace Manager API\n\n```python\n# 创建宫殿结构\nao.palace.create_wing(\"Orion\") # 创建翼\nao.palace.create_room(\"Orion\", \"auth\") # 在翼下创建房间\nao.palace.create_tunnel(\"Orion\", \"Gemini\", room=\"shared\") # 跨翼隧道\n\n# 导航查询\nwings = ao.palace.list_wings() # 列出所有翼\nrooms = ao.palace.rooms(\"Orion\") # 列出翼下房间\nstats = ao.palace.stats() # 统计信息\n```\n\n### 语义搜索集成\n\nPalace层与Semantic Index深度集成，提供零API成本的本地语义搜索：\n\n```python\n# Semantic Index延迟加载机制\nclass SemanticIndex:\n _model = None # 首次访问时加载\n \n @property\n def model(self):\n if self._model is None:\n # 首次使用时下载并加载 all-MiniLM-L6-v2 模型\n self._model = load_model()\n return self._model\n```\n\n首次启用语义搜索时自动下载约90MB的句子transformer模型（约500MB包含所有依赖）。\n\n资料来源：[ompa/semantic.py](https://github.com/jmiaie/ompa/blob/main/ompa/semantic.py)\n\n### 增量索引\n\nSemantic Index实现了增量更新机制，只重新索引修改过的文件：\n\n```python\n# 跟踪文件修改时间\nindex_state = {\n \"path/to/note.md\": {\n \"mtime\": 1709234567.123,\n \"embedding\": [...]\n }\n}\n\ndef needs_reindex(file_path, index_state) -> bool:\n \"\"\"检查文件是否需要重新索引\"\"\"\n if file_path not in index_state:\n return True\n return getmtime(file_path) > index_state[file_path][\"mtime\"]\n```\n\n资料来源：[CHANGELOG.md:45-50](https://github.com/jmiaie/ompa/blob/main/CHANGELOG.md)\n\n## 第三层：Knowledge Graph（时序推理层）\n\n### 设计目标\n\nKnowledge Graph层在Vault和Palace之上构建时序知识图谱，存储实体间的三元组关系，并支持时间窗口查询。这使得系统能够回答\"某个决策在特定时间点的状态\"等时序相关问题。\n\n### 数据模型\n\n```mermaid\ngraph LR\n subgraph 三元组结构\n SUBJ[\"Subject
主体实体\"]\n PRED[\"Predicate
关系谓词\"]\n OBJ[\"Object
客体实体\"]\n end\n \n subgraph 时序窗口\n VF[\"valid_from
生效时间\"]\n VT[\"valid_to
失效时间\"]\n end\n \n SUBJ --> PRED\n PRED --> OBJ\n SUBJ --> VF\n SUBJ --> VT\n```\n\n### SQLite存储\n\n所有三元组存储在SQLite数据库中：\n\n```sql\nCREATE TABLE triples (\n id INTEGER PRIMARY KEY,\n subject TEXT NOT NULL,\n predicate TEXT NOT NULL,\n object TEXT NOT NULL,\n valid_from TEXT,\n valid_to TEXT,\n source TEXT,\n created_at TEXT DEFAULT CURRENT_TIMESTAMP\n);\n\nCREATE INDEX idx_subject ON triples(subject);\nCREATE INDEX idx_valid_from ON triples(valid_from);\n```\n\n资料来源：[ompa/knowledge_graph.py](https://github.com/jmiaie/ompa/blob/main/ompa/knowledge_graph.py)\n\n### 核心操作\n\n| 操作 | 方法 | 说明 |\n|------|------|------|\n| 添加三元组 | `add_triple(subject, predicate, object, valid_from, source)` | 插入新关系 |\n| 查询实体 | `query_entity(entity, as_of)` | 获取实体所有关系 |\n| 时间线 | `timeline(entity)` | 实体历史变更 |\n| 统计 | `stats()` | 图谱统计信息 |\n\n### 时序查询示例\n\n```python\n# 添加带时效的三元组\nao.kg.add_triple(\n subject=\"Kai\",\n predicate=\"works_on\",\n object=\"Orion\",\n valid_from=\"2025-06-01\" # 2025年6月1日起生效\n)\n\n# 查询特定时间点的实体状态\ntriples = ao.kg.query_entity(\"Kai\", as_of=\"2025-06-15\")\n\n# 获取完整时间线\ntimeline = ao.kg.timeline(\"Kai\")\n# 返回: [{\"from\": \"2025-01-01\", \"to\": \"2025-05-31\", \"role\": \"lead\"},\n# {\"from\": \"2025-06-01\", \"to\": None, \"role\": \"architect\"}]\n```\n\n### Vault自动填充\n\nKnowledge Graph支持从Vault自动抽取知识：\n\n```python\n# populate_from_vault() 扫描现有笔记\n# 抽取来源包括：\n# 1. Frontmatter tags（如 tags: [auth, postgres]）\n# 2. 文件夹路径结构（如 work/active/auth/ → works_on:auth）\n# 3. Wikilinks（[[Note Name]] → references:Note_Name）\n```\n\n资料来源：[CHANGELOG.md:40-45](https://github.com/jmiaie/ompa/blob/main/CHANGELOG.md)\n\n## 三层协作机制\n\n### 数据流向\n\n```mermaid\nsequenceDiagram\n participant User as 用户/Agent\n participant Core as Ompa Core\n participant Vault as Vault Layer\n participant Palace as Palace Layer\n participant KG as KG Layer\n \n User->>Core: handle_message(\"决策内容\")\n Core->>Vault: 持久化存储\n Vault-->>Core: 保存成功\n Core->>Palace: 分类 + 路由\n Palace-->>Core: 建议文件夹\n Core->>KG: 抽取实体 + 关系\n KG-->>Core: 三元组已添加\n \n User->>Core: search(\"认证决策\")\n Core->>Palace: 语义搜索\n Palace-->>Core: Top-K 结果\n \n User->>Core: kg_query(\"Kai\")\n Core->>KG: 时序查询\n KG-->>Core: 历史状态\n```\n\n### 分类路由流程\n\n消息分类器（Classifier）根据内容类型自动路由到对应文件夹：\n\n| 消息类型 | 正则模式 | 目标文件夹 | 示例 |\n|----------|----------|------------|------|\n| DECISION | `决定\\|决策\\|选择\\|go with` | brain/decisions/ | \"We decided to go with Postgres\" |\n| CODE_CHANGE | `代码变更\\|commit\\|PR` | work/changes/ | \"Added auth middleware\" |\n| BLOCKER | `阻塞\\|卡住\\|blocked` | work/blockers/ | \"Stuck on the API design\" |\n\n资料来源：[ompa/classifier.py](https://github.com/jmiaie/ompa/blob/main/ompa/classifier.py)\n\n### 双库模式协作\n\n在Dual-Vault模式下，三层架构扩展为六层协作：\n\n```mermaid\ngraph TB\n subgraph 共享库 \"Shared Vault\"\n SV[\"Shared Vault\"]\n SP[\"Shared Palace\"]\n SK[\"Shared KG\"]\n end\n \n subgraph 个人库 \"Personal Vault\"\n PV[\"Personal Vault\"]\n PP[\"Personal Palace\"]\n PK[\"Personal KG\"]\n end\n \n subgraph 隔离层 \"Isolation Layer\"\n CONFIG[\"DualVaultConfig\"]\n MODE[\"IsolationMode\"]\n end\n \n CONFIG --> MODE\n MODE -->|\"AUTO\"| SV\n MODE -->|\"AUTO\"| PV\n```\n\n隔离模式说明：\n\n| 模式 | 行为 |\n|------|------|\n| `IsolationMode.AUTO` | 根据消息类型自动分类到shared或personal |\n| `IsolationMode.MANUAL` | 显式指定`VaultTarget`路由 |\n\n资料来源：[ompa/core.py:30-50](https://github.com/jmiaie/ompa/blob/main/ompa/core.py)\n\n## 生命周期钩子\n\n三层架构通过Hooks机制与Agent生命周期集成：\n\n```mermaid\nstateDiagram-v2\n [*] --> session_start: 钩子1\n session_start --> handle_message: 钩子2\n handle_message --> post_tool: 钩子3\n post_tool --> pre_compact: 钩子4\n pre_compact --> stop: 钩子5\n stop --> [*]\n```\n\n### 钩子列表\n\n| 钩子名称 | 时机 | 典型用途 |\n|----------|------|----------|\n| `on_session_start` | 会话开始 | 注入记忆上下文（~2K tokens） |\n| `on_message` | 消息处理 | 分类 + 持久化 |\n| `on_tool_call` | 工具调用 | 记录工具使用历史 |\n| `on_pre_compact` | 压缩前 | 准备会话摘要 |\n| `on_stop` | 会话结束 | 保存状态 + 更新索引 |\n\n资料来源：[ompa/hooks.py](https://github.com/jmiaie/ompa/blob/main/ompa/hooks.py)\n\n## 性能优化策略\n\n### 懒加载模式\n\n| 组件 | 懒加载策略 | 触发条件 |\n|------|------------|----------|\n| Semantic Model | `_model = None` | 首次search调用 |\n| KG Connection | `with sqlite3.connect()` | 每次查询 |\n| Palace Index | `incremental_reindex()` | 文件修改检测 |\n\n### 并发安全\n\nVault层在v0.3.1版本后支持并发访问：\n- SQLite连接使用context manager自动释放\n- 文件操作使用原子写入（write + rename）\n- UTF-8编码显式指定\n\n### 缓存策略\n\n```python\n# 内存缓存层\nclass Ompa:\n _wings_cache: list | None = None\n _stats_cache: dict | None = None\n \n def list_wings(self, use_cache=True):\n if use_cache and self._wings_cache:\n return self._wings_cache\n self._wings_cache = self.palace.list_wings()\n return self._wings_cache\n```\n\n## 总结\n\nOMPA的三层架构设计体现了现代AI Agent记忆系统的核心设计原则：\n\n1. **分层职责分离**：每层专注于特定职责，便于独立演进\n2. **原文优先**：Vault层不压缩、不摘要，保证信息完整性\n3. **时序感知**：KG层支持时间窗口查询，实现状态回溯\n4. **本地优先**：语义搜索完全在本地运行，零API成本\n5. **安全加固**：路径遍历防护、UTF-8显式编码、原子写入\n\n这种架构使得OMPA能够同时满足个人知识管理和团队协作的需求，通过双库模式实现隐私隔离与知识共享的平衡。\n\n---\n\n\n\n## 生命周期钩子\n\n### 相关页面\n\n相关主题：[三层架构设计](#three-layer-design), [消息分类器](#classifier)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [ompa/hooks.py](https://github.com/jmiaie/ompa/blob/main/ompa/hooks.py)\n- [ompa/core.py](https://github.com/jmiaie/ompa/blob/main/ompa/core.py)\n- [CONTRIBUTING.md](https://github.com/jmiaie/ompa/blob/main/CONTRIBUTING.md)\n- [STABILITY.md](https://github.com/jmiaie/ompa/blob/main/STABILITY.md)\n- [CLAUDE.md](https://github.com/jmiaie/ompa/blob/main/CLAUDE.md)\n \n\n# 生命周期钩子\n\nOMPA 的生命周期钩子系统允许开发者在会话关键节点插入自定义逻辑，实现消息处理、工具调用和会话收尾等流程的扩展与定制。\n\n## 核心概念\n\nOMPA 定义了 5 个生命周期钩子点，分别对应会话的不同阶段：\n\n| 钩子名称 | 触发时机 | 返回类型 |\n|---------|---------|---------|\n| `session_start` | 会话初始化时 | `HookResult` |\n| `handle_message` | 每条消息处理时 | `HookResult` |\n| `post_tool` | 工具调用完成后 | `HookResult` |\n| `pre_compact` | 上下文压缩前 | `HookResult` |\n| `stop` / `wrap_up` | 会话结束时 | `HookResult` |\n\n## 系统架构\n\n```mermaid\ngraph TD\n A[Ompa 实例] --> B[HookManager]\n B --> C[Hook 1]\n B --> D[Hook 2]\n B --> E[Hook N]\n \n F[触发时机] --> G[session_start]\n F --> H[handle_message]\n F --> I[post_tool]\n F --> J[pre_compact]\n F --> K[stop]\n \n G --> B\n H --> B\n I --> B\n J --> B\n K --> B\n```\n\n## 核心类\n\n### Hook 基类\n\n所有自定义钩子需继承 `Hook` 基类：\n\n```python\nfrom ompa.hooks import Hook, HookContext, HookResult\n\nclass MyHook(Hook):\n def __init__(self):\n super().__init__(\"my_hook\", token_budget=50)\n\n def execute(self, context: HookContext, **kwargs) -> HookResult:\n return HookResult(\n hook_name=self.name,\n success=True,\n output=\"...\",\n tokens_hint=50\n )\n```\n\n构造函数参数：\n| 参数 | 类型 | 说明 |\n|-----|------|-----|\n| `name` | `str` | 钩子唯一标识名 |\n| `token_budget` | `int` | 该钩子预计消耗的 token 上限 |\n\n### HookContext\n\n传递给钩子执行器的上下文对象，包含当前会话状态信息。\n\n### HookResult\n\n钩子执行结果的返回结构：\n\n| 字段 | 类型 | 说明 |\n|-----|------|-----|\n| `hook_name` | `str` | 执行钩子的名称 |\n| `success` | `bool` | 执行是否成功 |\n| `output` | `str` | 钩子输出内容 |\n| `tokens_hint` | `int` | 预估 token 消耗 |\n| `error` | `str` | 错误信息（可选） |\n\n## HookManager\n\n`HookManager` 负责管理所有已注册的钩子实例，提供注册和执行接口。\n\n```python\nfrom ompa.hooks import HookManager\n\n# 获取 HookManager 实例\nhook_manager = ao.hooks\nhook_manager.register_hook(\"my_hook\", MyHook())\n```\n\n## 注册自定义钩子\n\n```python\nfrom ompa import Ompa\nfrom ompa.hooks import Hook, HookContext, HookResult\n\nclass LoggingHook(Hook):\n def __init__(self):\n super().__init__(\"logging_hook\", token_budget=10)\n\n def execute(self, context: HookContext, **kwargs) -> HookResult:\n message = kwargs.get(\"message\", \"\")\n print(f\"[LOG] Processing: {message[:50]}\")\n return HookResult(\n hook_name=self.name,\n success=True,\n output=\"Logged successfully\",\n tokens_hint=10\n )\n\n# 创建实例并注册钩子\nao = Ompa(\"./workspace\")\nao.hooks.register_hook(\"logging\", LoggingHook())\n```\n\n## 钩子执行流程\n\n```mermaid\nsequenceDiagram\n participant User as 用户代码\n participant Ompa as Ompa 实例\n participant HM as HookManager\n participant Hook as 自定义钩子\n \n User->>Ompa: session_start() / handle_message()\n Ompa->>HM: 执行钩子链\n HM->>Hook: execute(context, **kwargs)\n Hook-->>HM: HookResult\n HM-->>Ompa: 聚合结果\n Ompa-->>User: HookResult\n```\n\n## 与 Ompa 核心集成\n\n`Ompa` 类的公共 API 均返回 `HookResult`：\n\n```python\nfrom ompa import Ompa\n\nao = Ompa(vault_path=\"./workspace\")\n\n# 所有方法返回 HookResult\ncontext = ao.session_start() # HookResult\nresult = ao.handle_message(\"msg\") # HookResult\nresult = ao.post_tool(\"write\", {\"file_path\": \"test.md\"}) # HookResult\nresult = ao.pre_compact(transcript) # HookResult\nao.stop() # HookResult\nao.wrap_up() # HookResult (stop 的别名)\nao.standup() # HookResult (session_start 的别名)\n```\n\n## 完整示例\n\n```python\nfrom ompa import Ompa\nfrom ompa.hooks import Hook, HookContext, HookResult\nimport time\n\nclass TimingHook(Hook):\n def __init__(self):\n super().__init__(\"timing\", token_budget=5)\n self.start_time = None\n\n def execute(self, context: HookContext, **kwargs) -> HookResult:\n if self.start_time is None:\n self.start_time = time.time()\n msg = \"Timer started\"\n else:\n elapsed = time.time() - self.start_time\n msg = f\"Session duration: {elapsed:.1f}s\"\n return HookResult(\n hook_name=self.name,\n success=True,\n output=msg,\n tokens_hint=5\n )\n\n# 使用\nao = Ompa(\"./workspace\")\nao.hooks.register_hook(\"timing\", TimingHook())\n\nao.session_start()\n# ... 会话操作 ...\nao.wrap_up()\n```\n\n## 注意事项\n\n1. **token_budget 建议值**：每个钩子的 `token_budget` 用于上下文管理规划，建议设置实际消耗的近似值\n2. **异常处理**：钩子执行失败时返回 `success=False`，但不会中断主流程\n3. **返回值聚合**：`HookManager` 会聚合多个钩子的结果\n4. **注册时机**：建议在 `Ompa` 实例创建后立即注册钩子\n\n## 稳定性说明\n\n> `ompa.hooks.*Hook` 类为内部实现类，可能在次版本中变更。建议使用 `HookManager.register_hook()` 接口进行注册 资料来源：[STABILITY.md]()\n\n## 相关文件\n\n| 文件 | 说明 |\n|-----|------|\n| `ompa/hooks.py` | 钩子系统核心实现 |\n| `ompa/core.py` | `Ompa` 主类与钩子集成 |\n| `CONTRIBUTING.md` | 自定义钩子开发指南 |\n\n---\n\n\n\n## Vault存储层\n\n### 相关页面\n\n相关主题：[三层架构设计](#three-layer-design), [消息分类器](#classifier)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [ompa/vault.py](https://github.com/jmiaie/ompa/blob/main/ompa/vault.py)\n- [ompa/core.py](https://github.com/jmiaie/ompa/blob/main/ompa/core.py)\n- [ompa/config.py](https://github.com/jmiaie/ompa/blob/main/ompa/config.py)\n- [ompa/knowledge_graph.py](https://github.com/jmiaie/ompa/blob/main/ompa/knowledge_graph.py)\n- [ompa/semantic.py](https://github.com/jmiaie/ompa/blob/main/ompa/semantic.py)\n- [CLAUDE.md](https://github.com/jmiaie/ompa/blob/main/CLAUDE.md)\n- [SECURITY_AUDIT.md](https://github.com/jmiaie/ompa/blob/main/SECURITY_AUDIT.md)\n- [CHANGELOG.md](https://github.com/jmiaie/ompa/blob/main/CHANGELOG.md)\n \n\n# Vault存储层\n\nVault存储层是OMPA系统的核心数据持久化组件，负责管理所有笔记、文件、元数据和知识图谱的本地存储。作为系统的\"事实来源（Source of Truth）\"，Vault层采用了严格的安全防护机制和双保险库架构，为AI Agent提供可靠、可隔离的长期记忆存储。\n\n## 核心职责\n\nVault存储层承担以下核心职责：\n\n| 职责类别 | 具体功能 |\n|---------|---------|\n| 文件管理 | 笔记的创建、读取、更新、删除（CRUD操作） |\n| 结构组织 | 按消息类型分类笔记（brain/work/org/perf等） |\n| 安全防护 | 路径遍历攻击防护、UTF-8编码强制 |\n| 双保险库 | 共享库与个人库的隔离管理 |\n| 语义索引 | 文件修改时间跟踪与增量嵌入 |\n| 元数据管理 | Frontmatter解析与存储 |\n\n> 资料来源：[CLAUDE.md:7]()\n\n## 架构设计\n\n### 双层存储架构\n\nOMPA采用Vault + Palace的双层存储架构：\n\n- **Vault层**：数据的唯一事实来源，负责原始笔记和文件的持久化存储\n- **Palace层**：作为检索加速层，提供宫殿式记忆结构（wings/rooms/drawers/halls/tunnels）来优化信息检索效率\n\n```mermaid\ngraph TD\n A[用户/Agent] --> B[Ompa Core API]\n B --> C{Mode选择}\n C -->|单库模式| D[Vault单实例]\n C -->|双库模式| E[Shared Vault]\n C -->|双库模式| F[Personal Vault]\n D --> G[文件系统]\n E --> H[文件系统 - 共享区域]\n F --> I[文件系统 - 个人区域]\n G --> J[.palace/ 目录结构]\n H --> J\n I --> J\n J --> K[Knowledge Graph SQLite]\n J --> L[Semantic Index]\n```\n\n> 资料来源：[CLAUDE.md:7](), [README.md:Package Structure]()\n\n### 双保险库架构（Dual-Vault）\n\n从v0.4.0开始，OMPA支持双保险库架构，允许在共享保险库和个人保险库之间隔离数据：\n\n```python\nfrom ompa import Ompa, DualVaultConfig, IsolationMode\n\nconfig = DualVaultConfig(\n shared_vault=\"./team-vault\",\n personal_vault=\"./private-vault\",\n mode=IsolationMode.AUTO, # 或 IsolationMode.MANUAL\n)\nao = Ompa(config=config)\n```\n\n#### 隔离模式\n\n| 模式 | 行为描述 |\n|------|---------|\n| `IsolationMode.AUTO` | 根据消息类型自动分类，团队消息进入共享库，个人消息进入个人库 |\n| `IsolationMode.MANUAL` | 通过显式`VaultTarget`参数路由每个操作 |\n| `IsolationMode.STRICT` | 严格模式，阻止跨库操作 |\n\n> 资料来源：[STABILITY.md:30-35](), [CHANGELOG.md:0.4.0](), [README.md:Dual-Vault Mode]()\n\n#### 导出时的敏感信息清理\n\n在将个人保险库笔记导出到共享库时，`Ompa._sanitize_content()`方法会自动清理以下敏感信息：\n\n- `sk-*`（OpenAI风格API密钥）\n- `AKIA*`（AWS访问密钥ID）\n- `token:`、`password:`、`secret:`、`api_key:`、`api-key:`等敏感字段\n\n> 资料来源：[SECURITY_AUDIT.md:credential-sanitization]()\n\n## 安全机制\n\n### 路径遍历防护\n\nVault层实现了严格的路径遍历攻击防护，所有文件操作都通过`_safe_resolve`函数进行路径解析和边界检查：\n\n```mermaid\ngraph TD\n A[用户请求路径] --> B[_safe_resolve调用]\n B --> C[Path.resolve 规范化]\n C --> D{路径是否在vault_root内?}\n D -->|是| E[允许访问]\n D -->|否| F[Raise ValueError]\n E --> G[执行文件操作]\n```\n\n路径遍历防护的关键实现：\n\n- 使用`Path.resolve()`将所有路径规范化为绝对路径\n- 在操作前检查路径是否在保险库根目录内\n- 任何尝试逃逸保险库根目录的操作都会被拒绝并抛出异常\n- Brain note名称中包含路径分隔符的请求在API边界处被拒绝\n\n> 资料来源：[SECURITY_AUDIT.md:path-traversal-protection](), [CHANGELOG.md:0.4.1-path-traversal]()\n\n### UTF-8编码强制\n\n从v0.4.0开始，所有vault文件写入操作都强制使用UTF-8编码：\n\n> 资料来源：[CHANGELOG.md:0.4.0](), [README.md:utf-8-enforcement]()\n\n### 并发访问支持\n\nVault层的笔记CRUD操作支持并发访问，通过以下机制确保数据一致性：\n\n- 原子文件写入操作\n- 修改时间跟踪用于增量更新\n- SemanticIndex使用文件修改时间判断是否需要重新嵌入\n\n> 资料来源：[CHANGELOG.md:0.4.0-concurrent-access]()\n\n## 目录结构\n\n### 标准Vault布局\n\n```\nvault-root/\n├── brain/ # Brain笔记（个人想法、反思）\n│ ├── reflections/\n│ └── insights/\n├── work/ # 工作相关笔记\n├── org/ # 组织/团队知识\n├── perf/ # 性能相关记录\n├── .palace/ # Palace元数据目录\n│ ├── wings.json\n│ ├── rooms.json\n│ ├── kg.db # Knowledge Graph数据库\n│ └── index/ # 语义索引目录\n└── .ompa/ # OMPA内部配置\n```\n\n### Frontmatter格式\n\n每篇笔记都包含YAML frontmatter元数据：\n\n```yaml\n---\ndate: 2025-06-01\ntags: [authentication, postgres, decision]\nvault: shared # 或 personal\n---\n```\n\n> 资料来源：[core.py:frontmatter-示例](), [SECURITY_AUDIT.md:export-sanitization]()\n\n## 笔记分类与路由\n\n### 消息类型分类\n\nVault层根据消息类型将笔记路由到对应文件夹：\n\n| 消息类型 | 目标文件夹 | 说明 |\n|---------|----------|------|\n| DECISION | work/decisions/ | 决策记录 |\n| INCIDENT | brain/incidents/ | 事件记录 |\n| WIN | brain/wins/ | 成功案例 |\n| CONCERN | brain/concerns/ | 问题关注 |\n| REFLECTION | brain/reflections/ | 个人反思 |\n| WORK | work/ | 工作相关 |\n| ORG | org/ | 组织知识 |\n| ... | ... | 其他类型 |\n\n> 资料来源：[core.py:classification-routing](), [CONTRIBUTING.md:adding-message-type]()\n\n### 分类流程\n\n```mermaid\ngraph TD\n A[输入消息] --> B[Classifier.classify]\n B --> C[确定消息类型]\n C --> D[获取routing_hint]\n D --> E[确定目标文件夹]\n E --> F{IsolationMode}\n F -->|AUTO| G[根据消息类型自动选择vault]\n F -->|MANUAL| H[使用显式VaultTarget]\n G --> I[生成安全文件名]\n H --> I\n I --> J[构建完整路径]\n J --> K[_safe_resolve验证]\n K --> L[写入Note]\n```\n\n> 资料来源：[core.py:dual-vault-routing](), [classifier.py:classification-logic]()\n\n## 与其他模块的交互\n\n### 与Knowledge Graph的集成\n\nVault层扫描笔记中的以下内容来填充知识图谱：\n\n- Frontmatter中的tags\n- 文件夹路径结构\n- Wikilink引用（`[[Note Name]]`）\n\n```python\n# 通过KnowledgeGraph.populate_from_vault()实现\nkg = KnowledgeGraph(db_path)\nkg.populate_from_vault(vault_path)\n```\n\n> 资料来源：[CHANGELOG.md:0.3.0-auto-populate-kg]()\n\n### 与SemanticIndex的集成\n\nSemanticIndex组件跟踪文件修改时间，仅对更改过的文件重新生成嵌入向量：\n\n- 首次运行时生成完整索引\n- 后续运行仅处理修改时间变更的文件\n- 索引存储在`.palace/index/`目录\n\n> 资料来源：[CHANGELOG.md:0.3.0-incremental-semantic]()\n\n### 与MCP Server的集成\n\nMCP Server通过以下工具暴露Vault功能：\n\n| MCP工具 | 功能 |\n|--------|------|\n| `ao_init` | 初始化新vault |\n| `ao_status` | 健康检查与统计 |\n| `ao_write` | 写入笔记 |\n| `ao_export` | 导出笔记 |\n| `ao_import` | 导入笔记 |\n| `ao_orphans` | 检测孤儿笔记 |\n\n> 资料来源：[mcp_server.py:tool-handlers](), [CLAUDE.md:mcp-tools]()\n\n## 配置选项\n\n### 环境变量\n\n| 变量名 | 默认值 | 说明 |\n|-------|-------|------|\n| `OMPA_VAULT_PATH` | `.` | Vault根目录绝对路径 |\n| `OMPA_SHARED_VAULT` | — | 共享vault路径（双库模式） |\n| `OMPA_PERSONAL_VAULT` | — | 个人vault路径（双库模式） |\n| `OMPA_ISOLATION_MODE` | `strict` | 隔离模式 |\n| `OMPA_ENABLE_SEMANTIC` | `false` | 启用本地语义搜索 |\n\n> 资料来源：[examples/mcp_desktop/README.md:environment-variables]()\n\n### DualVaultConfig配置\n\n```python\n@dataclass\nclass DualVaultConfig:\n shared_vault: str # 共享vault路径\n personal_vault: str # 个人vault路径\n isolation_mode: IsolationMode # AUTO | STRICT | MANUAL\n default_vault: VaultTarget # MANUAL模式的默认目标\n```\n\n> 资料来源：[config.py:DualVaultConfig](), [STABILITY.md:core-class-config]()\n\n## 版本历史关键变更\n\n| 版本 | 日期 | 关键变更 |\n|-----|------|---------|\n| 0.4.1 | 2026-04-11 | 路径遍历加固、语义索引延迟加载、brain note名称验证 |\n| 0.4.0 | 2026-04-10 | 双保险库架构、并发CRUD、UTF-8强制编码 |\n| 0.3.1 | 2026-04-09 | 孤儿笔记检测修复、wikilink大小写不敏感解析 |\n| 0.3.0 | 2026-04-08 | 自动从vault填充KG、增量语义索引 |\n\n> 资料来源：[CHANGELOG.md:完整历史]()\n\n## 使用示例\n\n### Python API基本用法\n\n```python\nfrom ompa import Ompa\n\n# 单库模式\nao = Ompa(vault_path=\"./workspace\")\n\n# 双库模式\nfrom ompa import DualVaultConfig, IsolationMode\nconfig = DualVaultConfig(\n shared_vault=\"./team-vault\",\n personal_vault=\"./private-vault\",\n mode=IsolationMode.AUTO,\n)\nao = Ompa(config=config)\n\n# 创建笔记\nresult = ao.handle_message(\"We decided to go with Postgres for the auth service\")\n```\n\n### CLI命令\n\n```bash\nao init # 初始化新vault\nao status # 健康检查\nao orphans # 检测孤儿笔记\nao validate # 验证vault结构\n```\n\n> 资料来源：[README.md:CLI-Reference](), [README.md:Python-API]()\n\n## 内部实现注意事项\n\n以下为内部实现细节，可能会在次要版本中变更：\n\n- `ompa.vault.DEFAULT_EXCLUDE_PATTERNS`\n- `ompa.vault._safe_resolve`\n- 内部vault文件布局（`.palace/`结构）\n\n> 资料来源：[STABILITY.md:not-stable-items]()\n\n## 安全审计结果\n\nVault存储层已完成全面安全审计，评级为8/10（满分10分）：\n\n- **通过项**：路径遍历防护、SQL注入预防、凭证清理、UTF-8编码强制\n- **可接受项**：2个低严重性bandit发现（git子进程使用，已接受）\n\n> 资料来源：[SECURITY_AUDIT.md:full-audit](), [CHANGELOG.md:0.4.1-security](), [CHANGELOG.md:0.4.1-tests]()\n\n---\n\n\n\n## Palace元数据层\n\n### 相关页面\n\n相关主题：[三层架构设计](#three-layer-design), [Vault存储层](#vault)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [ompa/palace.py](https://github.com/jmiaie/ompa/blob/main/ompa/palace.py)\n- [ompa/core.py](https://github.com/jmiaie/ompa/blob/main/ompa/core.py)\n- [ompa/mcp_server.py](https://github.com/jmiaie/ompa/blob/main/ompa/mcp_server.py)\n- [ompa/classifier.py](https://github.com/jmiaie/ompa/blob/main/ompa/classifier.py)\n- [CLAUDE.md](https://github.com/jmiaie/ompa/blob/main/CLAUDE.md)\n- [README.md](https://github.com/jmiaie/ompa/blob/main/README.md)\n \n\n# Palace元数据层\n\n## 概述\n\nPalace（宫殿）是 OMPA 项目中的**元数据加速层**，与 Vault（存储层）共同构成双层检索架构的核心组成部分。Vault 作为事实来源（source of truth）存储所有笔记内容，而 Palace 则提供结构化的元数据组织和高效的路径导航能力。\n\n资料来源：[CLAUDE.md]()\n\n### 设计理念\n\nPalace 借鉴了\"记忆宫殿\"（Method of Loci）的隐喻，将笔记组织为层级化的空间结构：\n\n- **Wing（翼）**：顶级分类，对应组织或项目维度\n- **Room（房间）**：二级分类，对应具体主题或功能领域\n- **Drawer（抽屉）**：三级分类，可选，用于更细粒度的组织\n- **Hall（大厅）**：跨房间的聚合视图\n- **Tunnel（隧道）**：跨翼的连接路径，用于关联不同领域的笔记\n\n这种设计使得 AI Agent 能够通过空间化的方式\"导航\"和\"穿越\"记忆结构，而非简单的关键词搜索。\n\n资料来源：[README.md]()\n\n## 架构设计\n\n### 双层架构\n\nOMPA 采用 **Vault + Palace** 双层架构：\n\n```mermaid\ngraph TD\n A[用户消息] --> B[Classifier 分类器]\n B --> C{Vault 或 Palace?}\n C -->|检索加速| D[Palace 元数据层]\n C -->|原始内容| E[Vault 存储层]\n D --> F[Wings / Rooms / Tunnels]\n E --> G[Markdown 文件 / 语义索引]\n```\n\n资料来源：[CLAUDE.md]()\n\n### Palace 核心职责\n\n| 职责 | 描述 |\n|------|------|\n| 元数据管理 | 维护 Wing/Room/Drawer/Hall/Tunnel 的索引结构 |\n| 路径导航 | 提供笔记的层级路径解析和关联查询 |\n| 跨域连接 | 创建 Tunnel 实现跨 Wing 的语义关联 |\n| 统计信息 | 提供 Palace 内各层级元素的数量和状态 |\n\n资料来源：[ompa/core.py]()\n\n## 核心概念\n\n### Wing（翼）\n\nWing 是 Palace 的顶级组织单元，通常对应一个大的主题领域或组织单元。\n\n**特性**：\n- 每个 Wing 拥有唯一的名称标识\n- Wing 下可包含多个 Room\n- 支持创建 Tunnel 连接不同 Wing\n\n```python\n# 通过 Python API 创建 Wing\nao.palace.create_wing(\"Orion\")\n```\n\n**MCP 工具**：`ao_palace_wings` — 列出所有 palace wings\n\n资料来源：[ompa/mcp_server.py](), [README.md]()\n\n### Room（房间）\n\nRoom 是 Wing 下的二级组织单元，用于更精细的主题划分。\n\n**特性**：\n- 必须隶属于某个 Wing\n- 可通过 Tunnel 与其他 Wing 的 Room 建立连接\n- 支持统计该 Wing 下的所有 Room\n\n```python\n# 通过 Python API 列出房间\nrooms = ao.palace.list_rooms(\"Orion\")\n```\n\n**MCP 工具**：`ao_palace_rooms` — 列出指定 Wing 下的所有房间\n\n资料来源：[ompa/mcp_server.py](), [README.md]()\n\n### Tunnel（隧道）\n\nTunnel 用于建立跨 Wing 的语义连接，实现不同领域知识之间的关联。\n\n**使用场景**：\n- 跨项目依赖关系的可视化\n- 相关但分属不同领域的笔记关联\n- 迁移路径的追踪（如身份认证迁移）\n\n```python\n# 创建跨 Wing 隧道\nao.palace.create_tunnel(\"Kai\", \"Orion\", \"auth-migration\")\n```\n\n**返回结果示例**：\n```json\n{\"success\": true, \"tunnel\": \"Kai <-> Orion via auth-migration\"}\n```\n\n**MCP 工具**：`ao_palace_tunnel` — 在两个 Wing 之间创建隧道\n\n资料来源：[ompa/mcp_server.py](), [README.md]()\n\n### Hall（大厅）\n\nHall 提供跨房间的聚合视图，允许用户在不限定特定 Room 的情况下进行检索。\n\n```mermaid\ngraph LR\n A[Hall] -->|聚合| B[Room A]\n A -->|聚合| C[Room B]\n A -->|聚合| D[Room C]\n```\n\n### Drawer（抽屉）\n\nDrawer 是可选的三级组织单元，提供更细粒度的分类能力。\n\n## API 参考\n\n### Python API\n\n```python\nfrom ompa import Ompa\n\nao = Ompa(vault_path=\"./workspace\")\n\n# 列出所有 Wings\nwings = ao.palace.list_wings()\n\n# 列出指定 Wing 下的 Rooms\nrooms = ao.palace.list_rooms(\"Orion\")\n\n# 创建 Tunnel\nao.palace.create_tunnel(\"Wing-A\", \"Wing-B\", \"room-name\")\n\n# 获取 Palace 统计信息\nstats = ao.palace.stats()\n```\n\n资料来源：[README.md](), [ompa/core.py]()\n\n### MCP Server 工具\n\n| 工具名 | 功能 | 参数 |\n|--------|------|------|\n| `ao_palace_wings` | 列出所有 Palace Wings | `vault_path` |\n| `ao_palace_rooms` | 列出指定 Wing 下的 Rooms | `wing`, `vault_path` |\n| `ao_palace_tunnel` | 创建跨 Wing 隧道 | `wing_a`, `wing_b`, `room`, `vault_path` |\n\n资料来源：[ompa/mcp_server.py](), [CLAUDE.md]()\n\n### CLI 命令\n\n| 命令 | 功能 |\n|------|------|\n| `ao wings` | 列出 Palace Wings |\n| `ao rooms ` | 列出指定 Wing 下的 Rooms |\n| `ao tunnel` | 创建或遍历跨 Wing 隧道 |\n\n资料来源：[README.md]()\n\n## Palace 与 Vault 的协同\n\n### 消息类型路由\n\nClassifier 根据消息内容自动分类，并将笔记路由到合适的 Vault 文件夹。Palace 则维护这些笔记的元数据索引。\n\n```mermaid\nsequenceDiagram\n participant User as 用户\n participant Core as Ompa Core\n participant Classifier as Classifier\n participant Palace as Palace\n participant Vault as Vault\n \n User->>Core: handle_message(msg)\n Core->>Classifier: classify(msg)\n Classifier-->>Core: MessageType + Folder\n Core->>Vault: write_note(folder, content)\n Core->>Palace: update_metadata(path, type)\n```\n\n资料来源：[ompa/core.py](), [ompa/classifier.py]()\n\n### 双重隔离模式\n\n在 Dual-Vault 架构下，Palace 支持按 Vault Target（shared/personal）进行元数据隔离：\n\n```python\nfrom ompa import Ompa, DualVaultConfig, IsolationMode\n\nconfig = DualVaultConfig(\n shared_vault=\"./team-vault\",\n personal_vault=\"./private-vault\",\n mode=IsolationMode.AUTO,\n)\nao = Ompa(config=config)\n```\n\nPalace 会根据 `IsolationMode` 自动将元数据写入对应的 Palace 实例。\n\n资料来源：[ompa/core.py](), [README.md]()\n\n## 配置与初始化\n\n### 环境变量\n\n| 变量 | 默认值 | 说明 |\n|------|--------|------|\n| `OMPA_VAULT_PATH` | `.` | Vault 根路径 |\n| `OMPA_ENABLE_SEMANTIC` | `false` | 启用本地语义搜索 |\n\nPalace 本身不直接使用环境变量配置，其结构由 Vault 内容动态构建。\n\n### Vault 初始化\n\n```bash\n# 初始化 Vault 结构（Palace 随之创建）\nao init\n\n# 检查状态\nao status\n```\n\n初始化后，Palace 将扫描 Vault 内容并建立初始元数据索引。\n\n资料来源：[README.md](), [CLAUDE.md]()\n\n## 使用示例\n\n### 场景：组织身份认证笔记\n\n```python\nfrom ompa import Ompa\n\nao = Ompa(vault_path=\"./workspace\")\n\n# 1. 创建组织 Wing\nao.palace.create_wing(\"Orion\")\n\n# 2. 在 Wing 下创建房间\n# （通过 Tunnel 连接不同领域的认证笔记）\n\n# 3. 创建跨域 Tunnel\nao.palace.create_tunnel(\"Kai\", \"Orion\", \"auth-migration\")\n\n# 4. 查询 Palace 统计\nstats = ao.palace.stats()\nprint(f\"Wings: {stats['wings']}\")\n```\n\n### 场景：通过 MCP 进行跨域检索\n\n```bash\n# 列出所有 Wings\nclaude mcp run ompa ao_palace_wings\n\n# 列出 Orion Wing 下的所有 Rooms\nclaude mcp run ompa ao_palace_rooms wing=Orion\n\n# 创建 Tunnel\nclaude mcp run ompa ao_palace_tunnel wing_a=Kai wing_b=Orion room=shared\n```\n\n资料来源：[README.md](), [examples/mcp_desktop/README.md]()\n\n## 扩展 Palace\n\n### 添加新概念\n\n如需扩展 Palace 的组织层级（如添加 Floor/Building），需要在以下位置进行修改：\n\n1. `ompa/palace.py` — 添加新的数据结构和操作方法\n2. `ompa/mcp_server.py` — 添加对应的 MCP 工具\n3. `ompa/cli.py` — 添加 CLI 命令\n4. 更新文档和测试\n\n### 自定义 Hook\n\nPalace 支持通过 Hook 系统进行扩展：\n\n```python\nfrom ompa.hooks import Hook, HookContext, HookResult\n\nclass PalaceMetadataHook(Hook):\n def on_note_create(self, ctx: HookContext) -> HookResult:\n # 自定义元数据更新逻辑\n return HookResult(success=True)\n```\n\n资料来源：[CLAUDE.md]()\n\n## 总结\n\nPalace 元数据层是 OMPA 项目中实现\"空间化记忆\"的核心组件。它通过层级化的组织结构（Wing → Room → Drawer）和跨域连接机制（Tunnel），为 AI Agent 提供了结构化的知识导航能力。与 Vault 的双层架构设计，使得 OMPA 能够在保持内容完整性的同时，提供高效的可检索性。\n\n**关键特性**：\n\n- ✅ 层级化的元数据组织（Wing/Room/Drawer/Hall/Tunnel）\n- ✅ 跨域 Tunnel 连接不同知识领域\n- ✅ 与 Vault 双层协同，Vault 为事实来源，Palace 为检索加速\n- ✅ 支持 Dual-Vault 隔离模式\n- ✅ 提供 Python API、MCP 工具和 CLI 三种交互方式\n\n---\n\n\n\n## 时序知识图谱\n\n### 相关页面\n\n相关主题：[三层架构设计](#three-layer-design), [Palace元数据层](#palace)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [ompa/knowledge_graph.py](https://github.com/jmiaie/ompa/blob/main/ompa/knowledge_graph.py)\n- [ompa/mcp_server.py](https://github.com/jmiaie/ompa/blob/main/ompa/mcp_server.py)\n- [ompa/core.py](https://github.com/jmiaie/ompa/blob/main/ompa/core.py)\n- [CHANGELOG.md](https://github.com/jmiaie/ompa/blob/main/CHANGELOG.md)\n- [README.md](https://github.com/jmiaie/ompa/blob/main/README.md)\n- [STABILITY.md](https://github.com/jmiaie/ompa/blob/main/STABILITY.md)\n \n\n# 时序知识图谱\n\n## 概述\n\n时序知识图谱（Temporal Knowledge Graph）是 OMPA 项目的核心组件之一，用于存储和管理具有时间维度的事实三元组。与传统知识图谱不同，时序知识图谱为每个三元组关联了有效性时间窗口，使系统能够查询任意时间点的实体状态变化历史。\n\n时序知识图谱基于 SQLite 实现，采用三重存储（Triple Store）模式，支持以下核心功能：\n\n- 三元组（Subject-Predicate-Object）的增删改查\n- 实体历史时间线查询\n- 从 Vault 自动填充知识图谱\n- 基于时间窗口的有效性过滤\n\n资料来源：[README.md](https://github.com/jmiaie/ompa/blob/main/README.md)\n\n## 架构设计\n\n### 核心概念\n\n| 概念 | 描述 |\n|------|------|\n| 三元组（Triple） | 表示 (主体, 谓词, 客体) 的知识单元 |\n| 主体（Subject） | 实体的标识符，如 \"Kai\" |\n| 谓词（Predicate） | 关系类型，如 \"works_on\"、\"knows\" |\n| 客体（Object） | 关系的目标实体或值 |\n| 有效起始时间（valid_from） | 三元组开始生效的时间点 |\n| 有效结束时间（valid_to） | 三元组失效的时间点（可选） |\n| 来源（source） | 三元组的来源标注 |\n\n### 数据模型\n\n时序知识图谱使用 SQLite 数据库存储三重数据，每个三元组包含以下字段：\n\n```mermaid\nerDiagram\n TRIPLES {\n int id PK\n text subject\n text predicate\n text object\n text valid_from\n text valid_to\n text source\n text vault_path\n }\n```\n\n资料来源：[ompa/knowledge_graph.py](https://github.com/jmiaie/ompa/blob/main/ompa/knowledge_graph.py)\n\n### 双重 Vault 与知识图谱的关系\n\n```mermaid\ngraph TD\n A[Ompa 主类] --> B[时序知识图谱]\n A --> C[Shared Vault]\n A --> D[Personal Vault]\n B -.-> E[Shared KG 查询]\n B -.-> F[Personal KG 查询]\n C --> G[brain/ 组织笔记]\n D --> H[个人笔记]\n G -.-> B\n H -.-> B\n```\n\n知识图谱的数据来源可以是共享 Vault 或个人 Vault，具体取决于隔离模式配置。\n\n资料来源：[ompa/core.py](https://github.com/jmiaie/ompa/blob/main/ompa/core.py)\n\n## 功能模块\n\n### 1. 三元组管理\n\n#### 添加三元组\n\n```python\nao.kg_add(subject, predicate, object_, valid_from=None, source=None)\n```\n\n**参数说明：**\n\n| 参数 | 类型 | 必需 | 描述 |\n|------|------|------|------|\n| subject | str | 是 | 主体实体名称 |\n| predicate | str | 是 | 谓词/关系类型 |\n| object_ | str | 是 | 客体实体或值 |\n| valid_from | str | 否 | 生效时间，格式 YYYY-MM-DD |\n| source | str | 否 | 三元组来源标注 |\n\n**示例：**\n\n```python\nfrom ompa import Ompa\n\nao = Ompa(vault_path=\"./workspace\")\n\n# 添加基础三元组\nao.kg_add(\"Kai\", \"works_on\", \"Orion\")\n\n# 添加带时间戳的三元组\nao.kg_add(\"Kai\", \"works_on\", \"Phoenix\", valid_from=\"2025-06-01\")\n\n# 添加带来源标注的三元组\nao.kg_add(\"决策\", \"approved_by\", \"Team\", source=\"2025-04-15 meeting\")\n```\n\n资料来源：[STABILITY.md](https://github.com/jmiaie/ompa/blob/main/STABILITY.md)\n\n#### 查询三元组\n\n```python\nao.kg_query(entity, as_of=None) -> list[Triple]\n```\n\n**参数说明：**\n\n| 参数 | 类型 | 必需 | 描述 |\n|------|------|------|------|\n| entity | str | 是 | 要查询的实体名称 |\n| as_of | str | 否 | 查询时间点，返回该时间点的有效状态 |\n\n**返回类型：** `list[Triple]`，每个 Triple 包含 subject、predicate、object_、valid_from、valid_to、source 属性。\n\n**示例：**\n\n```python\n# 查询实体所有历史记录\ntriples = ao.kg_query(\"Kai\")\n\n# 查询特定时间点的状态\ntriples = ao.kg_query(\"Kai\", as_of=\"2025-06-01\")\n```\n\n资料来源：[STABILITY.md](https://github.com/jmiaie/ompa/blob/main/STABILITY.md)\n\n### 2. 时间线查询\n\n```python\nao.kg_timeline(entity) -> list[dict]\n```\n\n该方法返回指定实体的完整时间线，展示实体的所有关系变化历史。\n\n**返回格式：**\n\n```python\n[\n {\n \"subject\": \"Kai\",\n \"predicate\": \"works_on\",\n \"object\": \"Orion\",\n \"valid_from\": \"2025-01-01\",\n \"valid_to\": \"2025-05-31\",\n \"source\": \"manual\"\n },\n {\n \"subject\": \"Kai\",\n \"predicate\": \"works_on\",\n \"object\": \"Phoenix\",\n \"valid_from\": \"2025-06-01\",\n \"valid_to\": None,\n \"source\": \"manual\"\n }\n]\n```\n\n**示例：**\n\n```python\n# 获取实体的完整时间线\ntimeline = ao.kg_timeline(\"Kai\")\n\n# 分析项目变更历史\nfor entry in timeline:\n print(f\"{entry['valid_from']}: {entry['subject']} {entry['predicate']} {entry['object']}\")\n```\n\n资料来源：[ompa/mcp_server.py](https://github.com/jmiaie/ompa/blob/main/ompa/mcp_server.py)\n\n### 3. 统计信息\n\n```python\nao.kg_stats() -> dict\n```\n\n返回知识图谱的统计信息，包括三元组总数、按谓词分组统计等。\n\n**示例：**\n\n```python\nstats = ao.kg_stats()\nprint(f\"Total triples: {stats['total']}\")\nprint(f\"By predicate: {stats['by_predicate']}\")\n```\n\n资料来源：[ompa/mcp_server.py](https://github.com/jmiaie/ompa/blob/main/ompa/mcp_server.py)\n\n### 4. 自动填充\n\n时序知识图谱支持从 Vault 自动提取三元组，包括：\n\n- 从 frontmatter 标签提取实体\n- 从文件夹路径提取组织结构\n- 从 `[[wikilinks]]` 提取关系\n\n```python\n# 自动从 Vault 填充知识图谱\nao.kg.populate_from_vault()\n```\n\n**工作流程：**\n\n```mermaid\ngraph LR\n A[扫描 Vault] --> B[解析笔记]\n B --> C[提取 frontmatter 标签]\n B --> D[解析 wikilinks]\n B --> E[分析文件夹路径]\n C --> F[生成三元组]\n D --> F\n E --> F\n F --> G[写入知识图谱]\n```\n\n资料来源：[CHANGELOG.md](https://github.com/jmiaie/ompa/blob/main/CHANGELOG.md)\n\n## MCP 工具接口\n\nOMPA 通过 MCP（Model Context Protocol）服务器暴露知识图谱功能，可在 Claude Desktop、Cursor、Windsurf 等工具中使用。\n\n### 可用工具列表\n\n| 工具名称 | 功能 | 必需参数 |\n|----------|------|----------|\n| `ao_kg_query` | 查询实体的三元组 | entity |\n| `ao_kg_add` | 添加三元组 | subject, predicate, object_ |\n| `ao_kg_stats` | 获取统计信息 | - |\n| `ao_kg_timeline` | 获取实体时间线 | entity |\n| `ao_kg_populate` | 从 Vault 填充 KG | - |\n\n资料来源：[CLAUDE.md](https://github.com/jmiaie/ompa/blob/main/CLAUDE.md)\n\n### MCP 使用示例\n\n```json\n{\n \"tool\": \"ao_kg_add\",\n \"arguments\": {\n \"subject\": \"Alice\",\n \"predicate\": \"reports_to\",\n \"object_\": \"Bob\",\n \"valid_from\": \"2025-01-15\",\n \"source\": \"org chart update\"\n }\n}\n```\n\n## CLI 命令\n\n### kg-query\n\n查询特定实体的所有三元组：\n\n```bash\nao kg-query Kai\n```\n\n### kg-timeline\n\n获取实体的完整时间线：\n\n```bash\nao kg-timeline Orion\n```\n\n### kg-stats\n\n查看知识图谱统计信息：\n\n```bash\nao kg-stats\n```\n\n资料来源：[README.md](https://github.com/jmiaie/ompa/blob/main/README.md)\n\n## 版本演进\n\n### v0.3.0 — 自动填充功能\n\n新增 `KnowledgeGraph.populate_from_vault()` 方法，支持从现有笔记中自动提取三元组。\n\n> 资料来源：[CHANGELOG.md](https://github.com/jmiaie/ompa/blob/main/CHANGELOG.md)\n\n### v0.4.0 — 双重 Vault 集成\n\n时序知识图谱支持双重 Vault 架构，可在共享库和个人库之间独立维护知识图谱，并支持库之间的导入导出及数据脱敏。\n\n> 资料来源：[CHANGELOG.md](https://github.com/jmiaie/ompa/blob/main/CHANGELOG.md)\n\n## 最佳实践\n\n### 1. 实体命名规范\n\n- 使用一致的实体命名格式\n- 建议使用 CamelCase 或 snake_case 命名法\n- 避免在实体名中使用特殊字符\n\n### 2. 时间戳管理\n\n- 所有时间戳使用 `YYYY-MM-DD` 格式\n- 建议为关键关系变更添加 valid_from 时间戳\n- 时间线查询可帮助理解实体状态演变\n\n### 3. 来源标注\n\n- 为自动填充的三元组标注来源笔记\n- 为手动添加的三元组添加来源说明\n- 有助于追溯知识来源和验证准确性\n\n### 4. 性能考虑\n\n- 大量插入时使用批量操作\n- 定期执行 `ao rebuild-index` 维护索引\n- 复杂查询可结合 Palace 的组织结构加速\n\n## API 稳定性\n\n时序知识图谱的公共 API 自 v1.0.0 起遵循语义化版本控制。破坏性变更仅在主版本更新时发生，并将在 CHANGELOG.md 中提供迁移指南。\n\n> 资料来源：[STABILITY.md](https://github.com/jmiaie/ompa/blob/main/STABILITY.md)\n\n---\n\n\n\n## 消息分类器\n\n### 相关页面\n\n相关主题：[生命周期钩子](#lifecycle-hooks), [Vault存储层](#vault)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [ompa/classifier.py](https://github.com/jmiaie/ompa/blob/main/ompa/classifier.py)\n- [ompa/core.py](https://github.com/jmiaie/ompa/blob/main/ompa/core.py)\n- [ompa/config.py](https://github.com/jmiaie/ompa/blob/main/ompa/config.py)\n- [CONTRIBUTING.md](https://github.com/jmiaie/ompa/blob/main/CONTRIBUTING.md)\n- [CLAUDE.md](https://github.com/jmiaie/ompa/blob/main/CLAUDE.md)\n- [README.md](https://github.com/jmiaie/ompa/blob/main/README.md)\n \n\n# 消息分类器\n\n## 概述\n\n消息分类器（Message Classifier）是 OMPA 系统的核心组件之一，负责自动识别和分类用户消息的类型，并将每条消息路由到相应的存储位置。该系统基于正则表达式模式匹配和决策树逻辑，实现了 15 种预定义消息类型的自动分类。\n\n消息分类器的主要职责包括：\n\n- **类型识别**：通过正则表达式模式分析消息内容，确定消息属于哪种类型\n- **路由建议**：为每种类型提供存储路径建议和操作提示\n- **双库支持**：在双库模式下，自动判断消息应存储到共享库还是个人库\n- **CLI 集成**：提供命令行工具 `ao classify` 用于手动消息分类\n\n资料来源：[ompa/classifier.py:1-50]()\n\n## 系统架构\n\n消息分类器采用分层架构设计，核心组件包括分类引擎、模式匹配器、路由控制器。\n\n```mermaid\ngraph TD\n A[用户消息] --> B[Classifier 分类器]\n B --> C{模式匹配引擎}\n C -->|正则匹配| D[PATTERNS 模式库]\n C --> E[ClassificationResult 结果]\n E --> F[ROUTING_HINTS 路由提示]\n E --> G[FOLDER_MAP 文件夹映射]\n E --> H[VaultTarget 目标库判定]\n H --> I[SHARED 共享库]\n H --> J[PERSONAL 个人库]\n```\n\n## MessageType 枚举\n\nOMPA 定义了 15 种消息类型，每种类型对应不同的业务场景和存储位置。\n\n| 枚举值 | 中文名称 | 典型关键词 | 存储建议 |\n|--------|----------|------------|----------|\n| `DECISION` | 决策记录 | decided, agreed, ADR | brain/Key Decisions.md |\n| `INCIDENT` | 事故记录 | incident, outage, bug | work/incidents/ |\n| `WIN` | 成果记录 | won, shipped, deployed | perf/Brag Doc.md |\n| `ONE_ON_ONE` | 一对一会议 | 1:1, feedback, check-in | work/1-1/ |\n| `MEETING` | 会议记录 | meeting, agenda, notes | work/meetings/ |\n| `PROJECT_UPDATE` | 项目更新 | project, progress, blocked | work/active/ |\n| `PERSON_INFO` | 人员信息 | joined, role, team update | org/people/ |\n| `QUESTION` | 问题咨询 | how do, what is, why | brain/questions/ |\n| `TASK` | 任务清单 | todo, action item | work/tasks/ |\n| `ARCHITECTURE` | 架构设计 | architecture, design, API | work/architecture/ |\n| `CODE` | 代码相关 | code, function, PR | work/code/ |\n| `BRAIN_DUMP` | 脑暴记录 | dump, random thoughts | brain/dumps/ |\n| `WRAP_UP` | 会议总结 | wrap up, end session | brain/sessions/ |\n| `STANDUP` | 站会记录 | standup, daily | work/standups/ |\n| `RESEARCH` | 调研记录 | researching, exploring | brain/research/ |\n\n资料来源：[ompa/classifier.py:1-100]()\n\n## 分类流程\n\n### 1. 模式匹配阶段\n\n分类器使用预定义的正则表达式模式库 `PATTERNS` 对消息进行匹配。每个消息类型对应多组正则表达式，支持灵活的匹配策略。\n\n```mermaid\ngraph LR\n A[消息文本] --> B[遍历 MessageType]\n B --> C[匹配 PATTERNS]\n C --> D{找到匹配?}\n D -->|是| E[记录类型得分]\n D -->|否| F[继续下一个类型]\n E --> G{还有类型?}\n F --> G\n G -->|是| B\n G -->|否| H[返回最高得分类型]\n```\n\n### 2. 路由决策阶段\n\n基于分类结果，系统生成 `Classification` 对象，包含：\n\n- `message_type`：识别出的消息类型\n- `suggested_folder`：建议存储文件夹\n- `confidence`：匹配置信度（基于匹配到的模式数量）\n- `routing_hints`：操作提示列表\n\n资料来源：[ompa/classifier.py:100-200]()\n\n## 核心实现\n\n### Classifier 类\n\n```python\nclass Classifier:\n def classify(self, message: str) -> Classification:\n \"\"\"核心分类方法\"\"\"\n best_match = None\n best_score = 0\n \n for msg_type in MessageType:\n score = self._calculate_score(message, msg_type)\n if score > best_score:\n best_score = score\n best_match = msg_type\n \n return Classification(\n message_type=best_match,\n suggested_folder=FOLDER_MAP.get(best_match, \"brain/\"),\n confidence=best_score / max_patterns,\n routing_hints=ROUTING_HINTS.get(best_match, [])\n )\n```\n\n### PATTERNS 模式库\n\n每个消息类型定义多组正则表达式模式：\n\n| 消息类型 | 模式示例 |\n|----------|----------|\n| DECISION | `r\"\\b(decided|going with|settled on|agreed to)\\b\"` |\n| INCIDENT | `r\"\\b(incident|outage|bug|crash|failure)\\b\"` |\n| WIN | `r\"\\b(won|praised|success|achieved|shipped)\\b\"` |\n| QUESTION | `r\"\\b(how do|how can|what is|what are|why does)\\b\"` |\n\n资料来源：[ompa/classifier.py:100-150]()\n\n### FOLDER_MAP 文件夹映射\n\n| 消息类型 | 目标文件夹 |\n|----------|------------|\n| DECISION | brain/ |\n| INCIDENT | work/incidents/ |\n| WIN | perf/ |\n| ONE_ON_ONE | work/1-1/ |\n| MEETING | work/meetings/ |\n| PROJECT_UPDATE | work/active/ |\n| PERSON_INFO | org/people/ |\n| QUESTION | brain/questions/ |\n| TASK | work/tasks/ |\n| ARCHITECTURE | work/architecture/ |\n| CODE | work/code/ |\n| BRAIN_DUMP | brain/dumps/ |\n| WRAP_UP | brain/sessions/ |\n| STANDUP | work/standups/ |\n| RESEARCH | brain/research/ |\n\n资料来源：[ompa/classifier.py:150-200]()\n\n## 双库模式集成\n\n消息分类器与双库架构（Dual-Vault）紧密集成，支持自动内容隔离。\n\n### IsolationMode.AUTO 模式\n\n在自动模式下，分类器根据消息类型自动判断存储目标：\n\n```python\n# DualVaultConfig.classify_content() 集成\ntarget = self.dual_config.classify_content(\n content=message,\n tags=tags,\n file_path=file_path\n)\n```\n\n资料来源：[ompa/core.py:50-80]()\n\n### 自动分类规则\n\n| 消息类型 | 默认目标库 | 说明 |\n|----------|------------|------|\n| WIN | PERSONAL | 个人绩效相关 |\n| ONE_ON_ONE | PERSONAL | 私密对话 |\n| BRAIN_DUMP | PERSONAL | 私人脑暴 |\n| DECISION | SHARED | 团队决策 |\n| INCIDENT | SHARED | 事故共享 |\n| PROJECT_UPDATE | SHARED | 项目信息 |\n\n## CLI 接口\n\n### ao classify 命令\n\n```bash\nao classify \"We decided to go with Postgres for the main database\"\n```\n\n输出示例：\n\n```\nType: DECISION\nConfidence: 0.85\nFolder: brain/\nHints:\n - This is a decision. Record it in brain/Key Decisions.md\n - Update relevant project notes with the decision\n - Add to Decision Log if formal ADR needed\n```\n\n资料来源：[ompa/cli.py]()\n\n## MCP 服务器集成\n\n消息分类功能通过 MCP 协议暴露为工具：\n\n```json\n{\n \"name\": \"ao_classify\",\n \"description\": \"Classify a message and get routing hints\"\n}\n```\n\n资料来源：[ompa/mcp_server.py:1-50]()\n\n## 扩展消息类型\n\n要添加新的消息类型，需完成以下步骤：\n\n### 1. 添加枚举值\n\n在 `classifier.py` 的 `MessageType` 枚举中添加新类型。\n\n### 2. 添加正则模式\n\n```python\nPATTERNS[MessageType.NEW_TYPE] = [\n r\"\\b(keyword1|keyword2)\\b\",\n r\"\\b(another pattern)\\b\",\n]\n```\n\n### 3. 添加路由提示\n\n```python\nROUTING_HINTS[MessageType.NEW_TYPE] = [\n \"Store in appropriate location\",\n \"Update relevant notes\",\n]\n```\n\n### 4. 添加文件夹映射\n\n```python\nFOLDER_MAP[MessageType.NEW_TYPE] = \"path/to/folder/\"\n```\n\n### 5. 添加测试用例\n\n在 `tests/test_ompa.py` 的 `TestClassifier` 类中添加测试用例。\n\n资料来源：[CONTRIBUTING.md:40-55]()\n\n## 配置参数\n\n消息分类器本身无需额外配置，但可通过环境变量影响其行为：\n\n| 环境变量 | 说明 | 默认值 |\n|----------|------|--------|\n| `OMPA_VAULT_PATH` | 保险库路径 | `.` |\n| `OMPA_SHARED_VAULT` | 共享库路径 | - |\n| `OMPA_PERSONAL_VAULT` | 个人库路径 | - |\n\n资料来源：[examples/mcp_desktop/README.md:1-30]()\n\n## 最佳实践\n\n### 1. 消息预处理\n\n- 消息应保持原始内容，不要提前摘要\n- 移除敏感信息后再进行分类\n- 包含足够的上下文以提高分类准确率\n\n### 2. 置信度阈值\n\n建议在下游处理中设置置信度阈值：\n\n```python\nresult = classifier.classify(message)\nif result.confidence < 0.5:\n # 人工复核或使用默认分类\n pass\n```\n\n### 3. 自定义模式\n\n可通过继承 `Classifier` 类添加自定义模式：\n\n```python\nclass CustomClassifier(Classifier):\n def _calculate_score(self, message: str, msg_type: MessageType) -> float:\n base_score = super()._calculate_score(message, msg_type)\n # 添加自定义评分逻辑\n return base_score\n```\n\n## 性能特性\n\n| 特性 | 说明 |\n|------|------|\n| 延迟 | O(n*m)，n=消息数，m=每类型模式数 |\n| 内存 | 模式编译后缓存 |\n| 并发 | 线程安全 |\n\n分类器采用延迟模式编译策略，模式在首次使用时编译并缓存，确保高性能。\n\n## 已知限制\n\n- 依赖正则表达式，对语义理解有限\n- 混合类型消息可能分类不准确\n- 不支持多语言消息分类（当前仅英文模式）\n\n## 相关资源\n\n- [CLAUDE.md](./CLAUDE.md) - 架构决策文档\n- [STABILITY.md](./STABILITY.md) - API 稳定性保证\n- [测试文件 tests/test_ompa.py](../tests/test_ompa.py) - 分类器测试用例\n\n---\n\n\n\n## MCP服务器集成\n\n### 相关页面\n\n相关主题：[框架适配器](#adapters)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [ompa/mcp_server.py](https://github.com/jmiaie/ompa/blob/main/ompa/mcp_server.py)\n- [examples/mcp_desktop/README.md](https://github.com/jmiaie/ompa/blob/main/examples/mcp_desktop/README.md)\n- [README.md](https://github.com/jmiaie/ompa/blob/main/README.md)\n- [CLAUDE.md](https://github.com/jmiaie/ompa/blob/main/CLAUDE.md)\n- [CONTRIBUTING.md](https://github.com/jmiaie/ompa/blob/main/CONTRIBUTING.md)\n \n\n# MCP服务器集成\n\n## 概述\n\nOMPA通过MCP（Model Context Protocol）服务器提供与AI代理桌面客户端的深度集成。该服务器以Python模块形式运行，通过标准输入/输出（stdin/stdout）使用JSON-RPC 2.0协议与客户端通信，使AI代理能够直接访问OMPA的核心功能。\n\nMCP服务器暴露了15个工具，涵盖保险库管理、知识图谱查询、语义搜索、宫殿导航等功能。开发者可参考稳定性文档确认这些工具为公开API的一部分。\n\n资料来源：[ompa/mcp_server.py:1-50]()\n\n## 架构设计\n\n### 通信协议\n\nMCP服务器采用JSON-RPC 2.0 over stdin/stdout的标准模式：\n\n```mermaid\ngraph LR\n A[\"Claude/Cursor/Windsurf
MCP Client\"] <-->|\"JSON-RPC
stdin/stdout\"| B[\"ompa.mcp_server
Python Process\"]\n B --> C[\"Ompa Core
Vault + Palace + KG\"]\n```\n\n服务器在初始化时返回协议版本和能力描述：\n\n```python\nresponse = {\n \"jsonrpc\": \"2.0\",\n \"id\": request_id,\n \"result\": {\n \"protocolVersion\": \"2024-11-05\",\n \"capabilities\": {\"tools\": {}},\n \"serverInfo\": {\n \"name\": \"ompa\",\n \"version\": __version__,\n },\n },\n}\n```\n\n资料来源：[ompa/mcp_server.py:160-175]()\n\n### 主循环处理\n\n服务器在`main()`函数中持续监听stdin，每次读取一行JSON-RPC请求：\n\n```python\ndef main():\n request = None\n while True:\n try:\n line = sys.stdin.readline()\n if not line:\n break\n request = json.loads(line.strip())\n # 处理请求...\n except Exception as e:\n return {\"error\": type(e).__name__}\n```\n\n资料来源：[ompa/mcp_server.py:180-195]()\n\n## MCP工具清单\n\n### 工具分类表\n\n| 类别 | 工具名称 | 功能描述 |\n|------|----------|----------|\n| 生命周期 | `ao_init` | 初始化新的OMPA保险库 |\n| 生命周期 | `ao_session_start` | 启动会话并注入记忆上下文 |\n| 生命周期 | `ao_wrap_up` | 会话总结并持久化 |\n| 生命周期 | `ao_status` | 检查保险库健康状态 |\n| 分类 | `ao_classify` | 分类消息并返回路由提示 |\n| 搜索 | `ao_search` | 执行语义搜索 |\n| 知识图谱 | `ao_kg_query` | 查询实体关系 |\n| 知识图谱 | `ao_kg_add` | 添加知识三元组 |\n| 知识图谱 | `ao_kg_stats` | 知识图谱统计 |\n| 知识图谱 | `ao_kg_populate` | 从保险库填充知识图谱 |\n| 宫殿 | `ao_palace_wings` | 列出所有宫殿翅膀 |\n| 宫殿 | `ao_palace_rooms` | 列出指定翅膀中的房间 |\n| 宫殿 | `ao_palace_tunnel` | 创建/穿越跨翅膀隧道 |\n| 工具 | `ao_orphans` | 检测孤立笔记 |\n| 工具 | `ao_validate` | 验证保险库结构 |\n| 同步 | `ao_sync` | 同步保险库 |\n| 文件 | `ao_write` | 写入笔记 |\n| 文件 | `ao_export` | 导出内容 |\n| 文件 | `ao_import` | 导入内容 |\n\n资料来源：[CLAUDE.md:1-15]()\n\n### 知识图谱工具详解\n\n#### ao_kg_add\n\n添加三元组到知识图谱：\n\n```python\nresult = ao_kg_add(\n subject=arguments[\"subject\"],\n predicate=arguments[\"predicate\"],\n object=arguments[\"object\"],\n valid_from=arguments.get(\"valid_from\"),\n source=arguments.get(\"source\"),\n vault_path=vault_path,\n)\n```\n\n参数说明：\n\n| 参数 | 类型 | 必需 | 说明 |\n|------|------|------|------|\n| `subject` | string | 是 | 主语实体 |\n| `predicate` | string | 是 | 关系谓词 |\n| `object` | string | 是 | 宾语实体 |\n| `valid_from` | string | 否 | 有效期起始日期（YYYY-MM-DD） |\n| `source` | string | 否 | 来源文件 |\n\n资料来源：[ompa/mcp_server.py:90-100]()\n\n## 桌面客户端配置\n\n### Claude Desktop\n\n#### 方式一：CLI命令（推荐）\n\n```bash\nclaude mcp add ompa -- python -m ompa.mcp_server\n```\n\n#### 方式二：手动配置\n\n编辑 `~/.claude/claude_desktop_config.json`：\n\n```json\n{\n \"mcpServers\": {\n \"ompa\": {\n \"command\": \"python\",\n \"args\": [\"-m\", \"ompa.mcp_server\"],\n \"env\": {\n \"OMPA_VAULT_PATH\": \"/absolute/path/to/your/vault\"\n }\n }\n }\n}\n```\n\n配置完成后需重启Claude Desktop应用。\n\n资料来源：[examples/mcp_desktop/README.md:1-40]()\n\n### Cursor\n\n在项目根目录创建 `.cursor/mcp.json`：\n\n```json\n{\n \"mcpServers\": {\n \"ompa\": {\n \"command\": \"python\",\n \"args\": [\"-m\", \"ompa.mcp_server\"],\n \"env\": {\n \"OMPA_VAULT_PATH\": \"${workspaceFolder}/.ompa-vault\",\n \"OMPA_ENABLE_SEMANTIC\": \"false\"\n }\n }\n }\n}\n```\n\n资料来源：[examples/mcp_desktop/README.md:50-65]()\n\n### Windsurf\n\n配置方式与Cursor相同，创建 `.windsurf/mcp.json`：\n\n```json\n{\n \"mcpServers\": {\n \"ompa\": {\n \"command\": \"python\",\n \"args\": [\"-m\", \"ompa.mcp_server\"],\n \"env\": {\n \"OMPA_VAULT_PATH\": \"/path/to/vault\"\n }\n }\n }\n}\n```\n\n资料来源：[examples/mcp_desktop/README.md:25-35]()\n\n## 环境变量配置\n\n### 配置项总览\n\n| 变量名 | 默认值 | 说明 |\n|--------|--------|------|\n| `OMPA_VAULT_PATH` | `.` | 保险库绝对路径 |\n| `OMPA_ENABLE_SEMANTIC` | `false` | 启用本地语义搜索 |\n| `OMPA_AGENT_NAME` | `agent` | 代理名称（用于知识图谱条目作用域） |\n| `OMPA_SHARED_VAULT` | — | 共享保险库路径（双保险库模式） |\n| `OMPA_PERSONAL_VAULT` | — | 个人保险库路径（双保险库模式） |\n\n资料来源：[examples/mcp_desktop/README.md:70-85]()\n\n### 语义搜索配置\n\n默认情况下，语义搜索功能关闭。如需启用本地语义搜索（首次运行会下载约500MB的`all-MiniLM-L6-v2`模型）：\n\n```bash\npip install ompa[all]\n```\n\n然后在MCP配置的`env`块中设置：\n\n```json\n{\n \"env\": {\n \"OMPA_ENABLE_SEMANTIC\": \"true\"\n }\n}\n```\n\n后续运行将直接使用缓存模型，无额外下载。\n\n资料来源：[examples/mcp_desktop/README.md:40-50]()\n\n## 双保险库模式集成\n\nMCP服务器支持双保险库架构，可隔离团队/组织内容与个人私密笔记。\n\n### MCP配置示例\n\n```json\n{\n \"mcpServers\": {\n \"ompa\": {\n \"command\": \"python\",\n \"args\": [\"-m\", \"ompa.mcp_server\"],\n \"env\": {\n \"OMPA_SHARED_VAULT\": \"/path/to/shared-vault\",\n \"OMPA_PERSONAL_VAULT\": \"/path/to/personal-vault\",\n \"OMPA_ISOLATION_MODE\": \"auto\"\n }\n }\n }\n}\n```\n\n### 隔离模式\n\n| 模式 | 说明 |\n|------|------|\n| `auto` | 内容根据消息类型自动分类到共享或个人保险库 |\n| `strict` | 严格隔离模式 |\n| `manual` | 每个操作需显式指定`VaultTarget` |\n\n资料来源：[examples/mcp_desktop/README.md:100-120]()\n\n## 连接验证\n\n配置完成后，可通过以下方式验证连接：\n\n1. 在支持MCP的客户端中，询问AI助手：\n > \"Use the ao_status tool to check my OMPA vault health\"\n\n2. 预期响应应包含保险库统计信息。\n\n### 常见问题排查\n\n| 问题 | 解决方案 |\n|------|----------|\n| 工具未出现 | 重启桌面应用 |\n| \"Vault not found\" 错误 | 确认`OMPA_VAULT_PATH`为绝对路径且已通过`ao init`初始化 |\n| 首次运行缓慢 | 若启用语义搜索，首次运行需下载模型（约90MB），后续运行应立即响应 |\n\n资料来源：[examples/mcp_desktop/README.md:120-135]()\n\n## 框架兼容性\n\nOMPA的MCP服务器支持多种AI代理框架：\n\n| 代理框架 | 集成方式 |\n|----------|----------|\n| Claude Code | Python API + MCP服务器 |\n| OpenClaw | Python API + MCP服务器 |\n| Codex | Python API + MCP服务器 |\n| Gemini CLI | Python API + MCP服务器 |\n| LangChain | Python API |\n\nMCP服务器为框架无关的纯Python实现，无代理SDK依赖。\n\n资料来源：[README.md:60-75]()\n\n## 启动方式汇总\n\n### 启动命令对照表\n\n| 环境 | 启动命令 |\n|------|----------|\n| 直接运行 | `python -m ompa.mcp_server` |\n| Claude Desktop | `claude mcp add ompa -- python -m ompa.mcp_server` |\n| 指定保险库 | 设置`OMPA_VAULT_PATH`环境变量 |\n| 启用语义搜索 | 设置`OMPA_ENABLE_SEMANTIC=true` |\n\n所有启动方式均要求目标保险库已通过`ao init`初始化。\n\n资料来源：[examples/mcp_desktop/README.md:1-20]()\n\n## 安全特性\n\nMCP服务器继承OMPA核心的安全设计：\n\n1. **路径遍历防护**：所有保险库文件操作都解析并边界检查路径\n2. **UTF-8编码强制**：所有保险库文件写入显式指定UTF-8编码\n3. **并发安全**：笔记CRUD操作支持并发访问\n\n资料来源：[CHANGELOG.md:30-50]()\n\n## 相关文档\n\n- [CLAUDE.md](https://github.com/jmiaie/ompa/blob/main/CLAUDE.md) — 架构决策与内部API文档\n- [STABILITY.md](https://github.com/jmiaie/ompa/blob/main/STABILITY.md) — API稳定性保证\n- [CONTRIBUTING.md](https://github.com/jmiaie/ompa/blob/main/CONTRIBUTING.md) — 添加新MCP工具的指南\n\n---\n\n\n\n## 框架适配器\n\n### 相关页面\n\n相关主题：[MCP服务器集成](#mcp-server)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [ompa/adapters/langchain.py](https://github.com/jmiaie/ompa/blob/main/ompa/adapters/langchain.py)\n- [ompa/adapters/llamaindex.py](https://github.com/jmiaie/ompa/blob/main/ompa/adapters/llamaindex.py)\n- [ompa/adapters/faiss.py](https://github.com/jmiaie/ompa/blob/main/ompa/adapters/faiss.py)\n- [ompa/adapters/nim.py](https://github.com/jmiaie/ompa/blob/main/ompa/adapters/nim.py)\n- [ompa/adapters/openai_agents.py](https://github.com/jmiaie/ompa/blob/main/ompa/adapters/openai_agents.py)\n- [examples/langchain_agent/ompa_memory.py](https://github.com/jmiaie/ompa/blob/main/examples/langchain_agent/ompa_memory.py)\n \n\n# 框架适配器\n\nOMPA 框架适配器（Framework Adapters）是一组将 OMPA 与主流 AI 开发框架集成的桥接模块。这些适配器位于 `ompa/adapters/` 目录下，提供了与 LangChain、LlamaIndex、OpenAI Agents SDK 等框架的无缝对接能力，使开发者能够在现有 AI 应用架构中直接利用 OMPA 的记忆管理、知识图谱和语义搜索功能。\n\n## 架构概览\n\nOMPA 适配器层采用了适配器模式（Adapter Pattern），将 OMPA 的核心功能封装为各框架所期望的接口形式。这种设计使得 OMPA 可以作为多种 AI 框架的底层存储和检索后端，而无需修改框架本身的代码。\n\n```mermaid\ngraph TB\n subgraph \"AI 应用层\"\n LC[LangChain 应用]\n LI[LlamaIndex 应用]\n OAI[OpenAI Agents]\n CUSTOM[自定义应用]\n end\n \n subgraph \"适配器层\"\n LCM[OmpaMemory
OmpaRetriever]\n LIC[OmpaReader
OmpaVaultRetriever]\n OAIC[OmpaAgentHooks]\n NIM[NIMEmbeddingBackend]\n FAISS[FAISSSemanticIndex]\n end\n \n subgraph \"OMPA 核心\"\n CORE[Ompa Core]\n VAULT[Vault]\n KG[Knowledge Graph]\n SEM[Semantic Index]\n end\n \n LC --> LCM\n LI --> LIC\n OAI --> OAIC\n CUSTOM --> NIM\n CUSTOM --> FAISS\n \n LCM --> CORE\n LIC --> CORE\n OAIC --> CORE\n NIM --> SEM\n FAISS --> SEM\n \n CORE --> VAULT\n CORE --> KG\n```\n\n## 可用适配器列表\n\n| 适配器 | 源文件 | 功能描述 |\n|--------|--------|----------|\n| `OmpaMemory` | `ompa/adapters/langchain.py` | LangChain 聊天记忆组件 |\n| `OmpaRetriever` | `ompa/adapters/langchain.py` | LangChain 检索器，用于 RAG 链 |\n| `OmpaReader` | `ompa/adapters/llamaindex.py` | LlamaIndex 文档读取器 |\n| `OmpaVaultRetriever` | `ompa/adapters/llamaindex.py` | LlamaIndex 保险库检索器 |\n| `OmpaAgentHooks` | `ompa/adapters/openai_agents.py` | OpenAI Agents SDK 生命周期钩子 |\n| `NIMEmbeddingBackend` | `ompa/adapters/nim.py` | NVIDIA NIM 嵌入后端 |\n| `FAISSSemanticIndex` | `ompa/adapters/faiss.py` | FAISS 语义索引实现 |\n\n资料来源：[STABILITY.md]()\n\n## LangChain 适配器\n\nLangChain 适配器提供了与 LangChain 框架的深度集成，支持将 OMPA 作为聊天记忆存储和检索后端使用。\n\n### OmpaMemory\n\n`OmpaMemory` 是实现 LangChain `BaseChatMemory` 接口的记忆组件，它将 OMPA 保险库作为持久化存储层。\n\n**主要方法：**\n\n```python\nload_memory_variables(inputs) -> dict\nsave_context(inputs, outputs) -> None\nclear() -> None\n```\n\n**使用示例：**\n\n```python\nfrom ompa.adapters.langchain import OmpaMemory\nfrom langchain.chains import ConversationChain\nfrom langchain_anthropic import ChatAnthropic\n\n# 初始化记忆组件\nmemory = OmpaMemory(vault_path=\"./workspace\")\n\n# 创建对话链\nchain = ConversationChain(\n llm=ChatAnthropic(model=\"claude-sonnet-4-20250514\"),\n memory=memory\n)\n\n# 对话交互\nresponse = chain.invoke({\"input\": \"用户输入内容\"})\n```\n\n资料来源：[ompa/adapters/langchain.py:51-67]()\n\n### OmpaRetriever\n\n`OmpaRetriever` 包装了 OMPA 的搜索功能，使其可以作为 LangChain RAG 链中的检索器使用。\n\n```python\nfrom ompa.adapters.langchain import OmpaRetriever\n\nretriever = OmpaRetriever(vault_path=\"./workspace\")\n# 在 RAG 链中使用\nrag_chain = create_retrieval_chain(llm, retriever)\n```\n\n## LlamaIndex 适配器\n\nLlamaIndex 适配器提供了文档读取和检索能力，使 OMPA 保险库可以作为 LlamaIndex 的数据源。\n\n### OmpaReader\n\n`OmpaReader` 用于从 OMPA 保险库中读取文档并转换为 LlamaIndex 的文档格式。\n\n```python\nfrom ompa.adapters.llamaindex import OmpaReader\n\nreader = OmpaReader(vault_path=\"./workspace\")\ndocuments = reader.load_data()\n```\n\n### OmpaVaultRetriever\n\n`OmpaVaultRetriever` 提供了对 OMPA 保险库的向量检索能力，可直接集成到 LlamaIndex 的查询引擎中。\n\n```python\nfrom ompa.adapters.llamaindex import OmpaVaultRetriever\n\nretriever = OmpaVaultRetriever(vault_path=\"./workspace\")\n```\n\n## OpenAI Agents SDK 适配器\n\n`OmpaAgentHooks` 为 OpenAI Agents SDK 提供了 OMPA 的生命周期钩子集成。\n\n```python\nfrom ompa.adapters.openai_agents import OmpaAgentHooks\n\nhooks = OmpaAgentHooks(vault_path=\"./workspace\")\n# 在 OpenAI Agents 应用中注册钩子\n```\n\n## 向量存储适配器\n\n### NIMEmbeddingBackend\n\n`NIMEmbeddingBackend` 提供了与 NVIDIA NIM（NVIDIA Inference Management）服务的集成，用于生成嵌入向量。\n\n```python\nfrom ompa.adapters.nim import NIMEmbeddingBackend\n\nbackend = NIMEmbeddingBackend(\n api_key=\"your-api-key\",\n model=\"nvidia/nvolve-4q\"\n)\n```\n\n### FAISSSemanticIndex\n\n`FAISSSemanticIndex` 使用 Facebook AI Similarity Search (FAISS) 库实现高效的向量相似度搜索。\n\n```python\nfrom ompa.adapters.faiss import FAISSSemanticIndex\n\nindex = FAISSSemanticIndex(vault_path=\"./workspace\")\n```\n\n## 安装依赖\n\n不同的适配器需要不同的可选依赖包：\n\n```bash\n# LangChain 适配器\npip install ompa[langchain]\n\n# LlamaIndex 适配器\npip install ompa[llamaindex]\n\n# 所有适配器\npip install ompa[all]\n```\n\n## 稳定性说明\n\n根据项目稳定性策略，适配器接口在以下方面保持稳定：\n\n- 公共方法签名\n- 构造函数参数\n- 返回值类型\n\n适配器的内部实现细节可能在次版本更新中发生变化，但公共 API 将保持向后兼容。 资料来源：[STABILITY.md]()\n\n## 最佳实践\n\n1. **惰性初始化**：适配器支持惰性加载模型和索引，避免在导入时触发大量资源下载。\n2. **会话管理**：在长时间运行的 AI 应用中，确保在应用关闭时正确清理资源。\n3. **并发访问**：多个框架实例可以同时访问同一个 OMPA 保险库，适配器已处理并发读写场景。\n4. **配置分离**：建议将不同框架的适配器配置分离管理，便于独立调试和优化。\n\n## 扩展适配器\n\n开发者可以通过实现相应的协议（Protocol）接口来创建自定义适配器：\n\n```python\nfrom ompa.semantic import EmbeddingBackend\n\nclass CustomEmbeddingBackend(EmbeddingBackend):\n \"\"\"自定义嵌入后端接口\"\"\"\n \n async def embed(self, texts: list[str]) -> list[list[float]]:\n # 实现自定义嵌入逻辑\n pass\n \n async def embed_query(self, query: str) -> list[float]:\n # 实现自定义查询嵌入\n pass\n```\n\n## 与核心模块的关系\n\n```mermaid\ngraph LR\n subgraph \"适配器层\"\n LANG[LangChain]\n LLAMA[LlamaIndex]\n OAI[OpenAI Agents]\n end\n \n subgraph \"OMPA 核心\"\n VAULT[Vault
笔记持久化]\n KG[Knowledge Graph
三元组存储]\n SEM[Semantic Index
向量索引]\n end\n \n LANG --> VAULT\n LANG --> SEM\n LLAMA --> VAULT\n LLAMA --> SEM\n OAI --> VAULT\n OAI --> KG\n```\n\n适配器层负责将框架特定的接口转换为 OMPA 核心模块的标准调用，实现了框架解耦和应用灵活性的平衡。\n\n---\n\n---\n\n## Doramagic 踩坑日志\n\n项目：jmiaie/ompa\n\n摘要：发现 10 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：安装坑 - 来源证据：OMPA v0.2.0 — The Big Rename。\n\n## 1. 安装坑 · 来源证据：OMPA v0.2.0 — The Big Rename\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：OMPA v0.2.0 — The Big Rename\n- 对用户的影响：可能阻塞安装或首次运行。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_ac771ab081be444ab18c5c1963becb64 | https://github.com/jmiaie/ompa/releases/tag/v0.2.0 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 2. 配置坑 · 来源证据：[P0] agent_integration.py race condition — session.memory attribute not available on cold start\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：[P0] agent_integration.py race condition — session.memory attribute not available on cold start\n- 对用户的影响：可能阻塞安装或首次运行。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_db65ef8ac28c41048d74c03c80cbed28 | https://github.com/jmiaie/ompa/issues/6 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 3. 能力坑 · 能力判断依赖假设\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：README/documentation is current enough for a first validation pass.\n- 对用户的影响：假设不成立时，用户拿不到承诺的能力。\n- 建议检查：将假设转成下游验证清单。\n- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。\n- 证据：capability.assumptions | github_repo:1207151629 | https://github.com/jmiaie/ompa | README/documentation is current enough for a first validation pass.\n\n## 4. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | github_repo:1207151629 | https://github.com/jmiaie/ompa | last_activity_observed missing\n\n## 5. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作：下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | github_repo:1207151629 | https://github.com/jmiaie/ompa | no_demo; severity=medium\n\n## 6. 安全/权限坑 · 存在安全注意事项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：No sandbox install has been executed yet; downstream must verify before user use.\n- 对用户的影响：用户安装前需要知道权限边界和敏感操作。\n- 建议检查：转成明确权限清单和安全审查提示。\n- 防护动作：安全注意事项必须面向用户前置展示。\n- 证据：risks.safety_notes | github_repo:1207151629 | https://github.com/jmiaie/ompa | No sandbox install has been executed yet; downstream must verify before user use.\n\n## 7. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | github_repo:1207151629 | https://github.com/jmiaie/ompa | no_demo; severity=medium\n\n## 8. 安全/权限坑 · 来源证据：OMPA v0.2.1 — Security & Reliability Hardening\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：OMPA v0.2.1 — Security & Reliability Hardening\n- 对用户的影响：可能阻塞安装或首次运行。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_ab0ad6b963354f2096bef6783c95c289 | https://github.com/jmiaie/ompa/releases/tag/v0.2.1 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 9. 维护坑 · issue/PR 响应质量未知\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：issue_or_pr_quality=unknown。\n- 对用户的影响：用户无法判断遇到问题后是否有人维护。\n- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。\n- 防护动作：issue/PR 响应未知时，必须提示维护风险。\n- 证据：evidence.maintainer_signals | github_repo:1207151629 | https://github.com/jmiaie/ompa | issue_or_pr_quality=unknown\n\n## 10. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | github_repo:1207151629 | https://github.com/jmiaie/ompa | release_recency=unknown\n\n\n",
"markdown_key": "ompa",
"pages": "draft",
"source_refs": [
{
"evidence_id": "github_repo:1207151629",
"kind": "repo",
"supports_claim_ids": [
"claim_identity",
"claim_distribution",
"claim_capability"
],
"url": "https://github.com/jmiaie/ompa"
},
{
"evidence_id": "art_9e131103caf84e66a7ff3a59a0d43757",
"kind": "docs",
"supports_claim_ids": [
"claim_identity",
"claim_distribution",
"claim_capability"
],
"url": "https://github.com/jmiaie/ompa#readme"
}
],
"summary": "DeepWiki/Human Wiki 完整输出，末尾追加 Discovery Agent 踩坑日志。",
"title": "ompa 说明书",
"toc": [
"https://github.com/jmiaie/ompa 项目说明书",
"目录",
"项目介绍",
"概述",
"核心定位",
"技术架构",
"核心功能特性",
"添加带时间窗口的三元组",
"Doramagic 踩坑日志"
]
}
},
"quality_gate": {
"blocking_gaps": [],
"category_confidence": "medium",
"compile_status": "ready_for_review",
"five_assets_present": true,
"install_sandbox_verified": true,
"missing_evidence": [],
"next_action": "publish to Doramagic.ai project surfaces",
"prompt_preview_boundary_ok": true,
"publish_status": "publishable",
"quick_start_verified": true,
"repo_clone_verified": true,
"repo_commit": "40ff3e241490825d6dc8714c2d5594316e0cb69c",
"repo_inspection_error": null,
"repo_inspection_files": [
"pyproject.toml",
"README.md",
"docs/index.md",
"docs/quickstart.md",
"docs/changelog.md",
"docs/api/cli.md",
"docs/api/vault.md",
"docs/api/kg.md",
"docs/api/ompa.md",
"docs/api/palace.md",
"docs/guides/dual-vault.md",
"docs/guides/hooks.md",
"docs/guides/message-types.md",
"docs/guides/mcp.md",
"examples/simple_vault/demo.py",
"examples/mcp_desktop/README.md",
"examples/langchain_agent/ompa_memory.py",
"examples/multi_agent/swarm_memory.py"
],
"repo_inspection_verified": true,
"review_reasons": [],
"tag_count_ok": true,
"unsupported_claims": []
},
"schema_version": "0.1",
"user_assets": {
"ai_context_pack": {
"asset_id": "ai_context_pack",
"filename": "AI_CONTEXT_PACK.md",
"markdown": "# ompa - Doramagic AI Context Pack\n\n> 定位：安装前体验与判断资产。它帮助宿主 AI 有一个好的开始，但不代表已经安装、执行或验证目标项目。\n\n## 充分原则\n\n- **充分原则，不是压缩原则**：AI Context Pack 应该充分到让宿主 AI 在开工前理解项目价值、能力边界、使用入口、风险和证据来源；它可以分层组织，但不以最短摘要为目标。\n- **压缩策略**：只压缩噪声和重复内容，不压缩会影响判断和开工质量的上下文。\n\n## 给宿主 AI 的使用方式\n\n你正在读取 Doramagic 为 ompa 编译的 AI Context Pack。请把它当作开工前上下文：帮助用户理解适合谁、能做什么、如何开始、哪些必须安装后验证、风险在哪里。不要声称你已经安装、运行或执行了目标项目。\n\n## Claim 消费规则\n\n- **事实来源**：Repo Evidence + Claim/Evidence Graph；Human Wiki 只提供显著性、术语和叙事结构。\n- **事实最低状态**：`supported`\n- `supported`：可以作为项目事实使用，但回答中必须引用 claim_id 和证据路径。\n- `weak`：只能作为低置信度线索，必须要求用户继续核实。\n- `inferred`：只能用于风险提示或待确认问题，不能包装成项目事实。\n- `unverified`：不得作为事实使用，应明确说证据不足。\n- `contradicted`：必须展示冲突来源，不得替用户强行选择一个版本。\n\n## 它最适合谁\n\n- **正在使用 Claude/Codex/Cursor/Gemini 等宿主 AI 的开发者**：README 或插件配置提到多个宿主 AI。 证据：`README.md` Claim：`clm_0002` supported 0.86\n\n## 它能做什么\n\n- **命令行启动或安装流程**（需要安装后验证）：项目文档中存在可执行命令，真实使用需要在本地或宿主环境中运行这些命令。 证据：`CLAUDE.md`, `README.md`, `docs/quickstart.md` Claim：`clm_0001` supported 0.86\n\n## 怎么开始\n\n- `pip install ompa` 证据：`README.md` Claim：`clm_0003` supported 0.86, `clm_0004` supported 0.86, `clm_0005` supported 0.86, `clm_0007` supported 0.86 等\n- `pip install ompa # Core only` 证据：`README.md` Claim：`clm_0004` supported 0.86, `clm_0011` supported 0.86\n- `pip install ompa[all] # Includes local semantic search` 证据：`README.md` Claim：`clm_0005` supported 0.86\n- `claude mcp add ompa -- python -m ompa.mcp_server` 证据：`README.md` Claim：`clm_0006` supported 0.86\n- `pip install ompa[all]` 证据：`README.md` Claim：`clm_0005` supported 0.86, `clm_0007` supported 0.86, `clm_0012` supported 0.86, `clm_0013` supported 0.86\n- `pip install ompa[dev]` 证据：`README.md` Claim：`clm_0008` supported 0.86\n- `git clone https://github.com/jmiaie/ompa && cd ompa` 证据：`README.md` Claim：`clm_0009` supported 0.86\n- `pip install -e \".[all]\"` 证据：`README.md` Claim：`clm_0010` supported 0.86, `clm_0014` supported 0.86\n- `pip install ompa # Core only (vault + palace + KG + CLI + MCP)` 证据：`docs/quickstart.md` Claim：`clm_0011` supported 0.86\n- `pip install ompa[all] # Adds local semantic search (sentence-transformers)` 证据：`docs/quickstart.md` Claim：`clm_0012` supported 0.86\n\n## 继续前判断卡\n\n- **当前建议**：先做角色匹配试用\n- **为什么**：这个项目更像角色库，核心风险是选错角色或把角色文案当执行能力；先用 Prompt Preview 试角色匹配，再决定是否沙盒导入。\n\n### 30 秒判断\n\n- **现在怎么做**：先做角色匹配试用\n- **最小安全下一步**：先用 Prompt Preview 试角色匹配；满意后再隔离导入\n- **先别相信**：角色质量和任务匹配不能直接相信。\n- **继续会触碰**：角色选择偏差、命令执行、宿主 AI 配置\n\n### 现在可以相信\n\n- **适合人群线索：正在使用 Claude/Codex/Cursor/Gemini 等宿主 AI 的开发者**（supported）：有 supported claim 或项目证据支撑，但仍不等于真实安装效果。 证据：`README.md` Claim：`clm_0002` supported 0.86\n- **能力存在：命令行启动或安装流程**（supported）：可以相信项目包含这类能力线索；是否适合你的具体任务仍要试用或安装后验证。 证据：`CLAUDE.md`, `README.md`, `docs/quickstart.md` Claim：`clm_0001` supported 0.86\n- **存在 Quick Start / 安装命令线索**（supported）：可以相信项目文档出现过启动或安装入口；不要因此直接在主力环境运行。 证据：`README.md` Claim：`clm_0003` supported 0.86, `clm_0004` supported 0.86, `clm_0005` supported 0.86, `clm_0007` supported 0.86\n\n### 现在还不能相信\n\n- **角色质量和任务匹配不能直接相信。**（unverified）：角色库证明有很多角色，不证明每个角色都适合你的具体任务，也不证明角色能产生高质量结果。\n- **不能把角色文案当成真实执行能力。**（unverified）：安装前只能判断角色描述和任务画像是否匹配，不能证明它能在宿主 AI 里完成任务。\n- **真实输出质量不能在安装前相信。**（unverified）：Prompt Preview 只能展示引导方式，不能证明真实项目中的结果质量。\n- **宿主 AI 版本兼容性不能在安装前相信。**（unverified）：Claude、Cursor、Codex、Gemini 等宿主加载规则和版本差异必须在真实环境验证。\n- **不会污染现有宿主 AI 行为，不能直接相信。**（inferred）：Skill、plugin、AGENTS/CLAUDE/GEMINI 指令可能改变宿主 AI 的默认行为。 证据：`CLAUDE.md`\n- **可安全回滚不能默认相信。**（unverified）：除非项目明确提供卸载和恢复说明，否则必须先在隔离环境验证。\n- **真实安装后是否与用户当前宿主 AI 版本兼容？**（unverified）：兼容性只能通过实际宿主环境验证。\n- **项目输出质量是否满足用户具体任务？**（unverified）：安装前预览只能展示流程和边界，不能替代真实评测。\n\n### 继续会触碰什么\n\n- **角色选择偏差**：用户对任务应该由哪个专家角色处理的判断。 原因：选错角色会让 AI 从错误专业视角回答，浪费时间或误导决策。\n- **命令执行**：包管理器、网络下载、本地插件目录、项目配置或用户主目录。 原因：运行第一条命令就可能产生环境改动；必须先判断是否值得跑。 证据：`CLAUDE.md`, `README.md`, `docs/quickstart.md`\n- **宿主 AI 配置**：Claude/Codex/Cursor/Gemini/OpenCode 等宿主的 plugin、Skill 或规则加载配置。 原因：宿主配置会改变 AI 后续工作方式，可能和用户已有规则冲突。 证据：`CLAUDE.md`\n- **本地环境或项目文件**：安装结果、插件缓存、项目配置或本地依赖目录。 原因：安装前无法证明写入范围和回滚方式，需要隔离验证。 证据：`CLAUDE.md`, `README.md`, `docs/quickstart.md`\n- **宿主 AI 上下文**：AI Context Pack、Prompt Preview、Skill 路由、风险规则和项目事实。 原因：导入上下文会影响宿主 AI 后续判断，必须避免把未验证项包装成事实。\n\n### 最小安全下一步\n\n- **先跑 Prompt Preview**：先用交互式试用验证任务画像和角色匹配，不要先导入整套角色库。（适用：任何项目都适用，尤其是输出质量未知时。）\n- **只在隔离目录或测试账号试装**：避免安装命令污染主力宿主 AI、真实项目或用户主目录。（适用：存在命令执行、插件配置或本地写入线索时。）\n- **先备份宿主 AI 配置**：Skill、plugin、规则文件可能改变 Claude/Cursor/Codex 的默认行为。（适用：存在插件 manifest、Skill 或宿主规则入口时。）\n- **安装后只验证一个最小任务**：先验证加载、兼容、输出质量和回滚，再决定是否深用。（适用：准备从试用进入真实工作流时。）\n\n### 退出方式\n\n- **保留安装前状态**：记录原始宿主配置和项目状态，后续才能判断是否可恢复。\n- **准备移除宿主 plugin / Skill / 规则入口**：如果试装后行为异常，可以把宿主 AI 恢复到试装前状态。\n- **保留原始角色选择记录**：如果输出偏题，可以回到任务画像阶段重新选择角色，而不是继续沿着错误角色推进。\n- **记录安装命令和写入路径**：没有明确卸载说明时，至少要知道哪些目录或配置需要手动清理。\n- **如果没有回滚路径，不进入主力环境**：不可回滚是继续前阻断项，不应靠信任或运气继续。\n\n## 哪些只能预览\n\n- 解释项目适合谁和能做什么\n- 基于项目文档演示典型对话流程\n- 帮助用户判断是否值得安装或继续研究\n\n## 哪些必须安装后验证\n\n- 真实安装 Skill、插件或 CLI\n- 执行脚本、修改本地文件或访问外部服务\n- 验证真实输出质量、性能和兼容性\n\n## 边界与风险判断卡\n\n- **把安装前预览误认为真实运行**：用户可能高估项目已经完成的配置、权限和兼容性验证。 处理方式：明确区分 prompt_preview_can_do 与 runtime_required。 Claim：`clm_0016` inferred 0.45\n- **命令执行会修改本地环境**：安装命令可能写入用户主目录、宿主插件目录或项目配置。 处理方式：先在隔离环境或测试账号中运行。 证据：`CLAUDE.md`, `README.md`, `docs/quickstart.md` Claim：`clm_0017` supported 0.86\n- **待确认**：真实安装后是否与用户当前宿主 AI 版本兼容？。原因：兼容性只能通过实际宿主环境验证。\n- **待确认**：项目输出质量是否满足用户具体任务？。原因：安装前预览只能展示流程和边界，不能替代真实评测。\n- **待确认**：安装命令是否需要网络、权限或全局写入？。原因：这影响企业环境和个人环境的安装风险。\n\n## 开工前工作上下文\n\n### 加载顺序\n\n- 先读取 how_to_use.host_ai_instruction，建立安装前判断资产的边界。\n- 读取 claim_graph_summary，确认事实来自 Claim/Evidence Graph，而不是 Human Wiki 叙事。\n- 再读取 intended_users、capabilities 和 quick_start_candidates，判断用户是否匹配。\n- 需要执行具体任务时，优先查 role_skill_index，再查 evidence_index。\n- 遇到真实安装、文件修改、网络访问、性能或兼容性问题时，转入 risk_card 和 boundaries.runtime_required。\n\n### 任务路由\n\n- **命令行启动或安装流程**：先说明这是安装后验证能力，再给出安装前检查清单。 边界：必须真实安装或运行后验证。 证据：`CLAUDE.md`, `README.md`, `docs/quickstart.md` Claim：`clm_0001` supported 0.86\n\n### 上下文规模\n\n- 文件总数：63\n- 重要文件覆盖：40/63\n- 证据索引条目：44\n- 角色 / Skill 条目：22\n\n### 证据不足时的处理\n\n- **missing_evidence**：说明证据不足，要求用户提供目标文件、README 段落或安装后验证记录；不要补全事实。\n- **out_of_scope_request**：说明该任务超出当前 AI Context Pack 证据范围，并建议用户先查看 Human Manual 或真实安装后验证。\n- **runtime_request**：给出安装前检查清单和命令来源，但不要替用户执行命令或声称已执行。\n- **source_conflict**：同时展示冲突来源，标记为待核实，不要强行选择一个版本。\n\n## Prompt Recipes\n\n### 适配判断\n\n- 目标：判断这个项目是否适合用户当前任务。\n- 预期输出：适配结论、关键理由、证据引用、安装前可预览内容、必须安装后验证内容、下一步建议。\n\n```text\n请基于 ompa 的 AI Context Pack，先问我 3 个必要问题，然后判断它是否适合我的任务。回答必须包含：适合谁、能做什么、不能做什么、是否值得安装、证据来自哪里。所有项目事实必须引用 evidence_refs、source_paths 或 claim_id。\n```\n\n### 安装前体验\n\n- 目标：让用户在安装前感受核心工作流，同时避免把预览包装成真实能力或营销承诺。\n- 预期输出：一段带边界标签的体验剧本、安装后验证清单和谨慎建议；不含真实运行承诺或强营销表述。\n\n```text\n请把 ompa 当作安装前体验资产，而不是已安装工具或真实运行环境。\n\n请严格输出四段：\n1. 先问我 3 个必要问题。\n2. 给出一段“体验剧本”：用 [安装前可预览]、[必须安装后验证]、[证据不足] 三种标签展示它可能如何引导工作流。\n3. 给出安装后验证清单：列出哪些能力只有真实安装、真实宿主加载、真实项目运行后才能确认。\n4. 给出谨慎建议：只能说“值得继续研究/试装”“先补充信息后再判断”或“不建议继续”，不得替项目背书。\n\n硬性边界：\n- 不要声称已经安装、运行、执行测试、修改文件或产生真实结果。\n- 不要写“自动适配”“确保通过”“完美适配”“强烈建议安装”等承诺性表达。\n- 如果描述安装后的工作方式，必须使用“如果安装成功且宿主正确加载 Skill，它可能会……”这种条件句。\n- 体验剧本只能写成“示例台词/假设流程”：使用“可能会询问/可能会建议/可能会展示”，不要写“已写入、已生成、已通过、正在运行、正在生成”。\n- Prompt Preview 不负责给安装命令；如用户准备试装，只能提示先阅读 Quick Start 和 Risk Card，并在隔离环境验证。\n- 所有项目事实必须来自 supported claim、evidence_refs 或 source_paths；inferred/unverified 只能作风险或待确认项。\n\n```\n\n### 角色 / Skill 选择\n\n- 目标：从项目里的角色或 Skill 中挑选最匹配的资产。\n- 预期输出：候选角色或 Skill 列表，每项包含适用场景、证据路径、风险边界和是否需要安装后验证。\n\n```text\n请读取 role_skill_index，根据我的目标任务推荐 3-5 个最相关的角色或 Skill。每个推荐都要说明适用场景、可能输出、风险边界和 evidence_refs。\n```\n\n### 风险预检\n\n- 目标：安装或引入前识别环境、权限、规则冲突和质量风险。\n- 预期输出：环境、权限、依赖、许可、宿主冲突、质量风险和未知项的检查清单。\n\n```text\n请基于 risk_card、boundaries 和 quick_start_candidates，给我一份安装前风险预检清单。不要替我执行命令，只说明我应该检查什么、为什么检查、失败会有什么影响。\n```\n\n### 宿主 AI 开工指令\n\n- 目标：把项目上下文转成一次对话开始前的宿主 AI 指令。\n- 预期输出：一段边界明确、证据引用明确、适合复制给宿主 AI 的开工前指令。\n\n```text\n请基于 ompa 的 AI Context Pack，生成一段我可以粘贴给宿主 AI 的开工前指令。这段指令必须遵守 not_runtime=true，不能声称项目已经安装、运行或产生真实结果。\n```\n\n\n## 角色 / Skill 索引\n\n- 共索引 22 个角色 / Skill / 项目文档条目。\n\n- **CLAUDE.md — OMPA**（project_doc）：You are building OMPA Obsidian-MemPalace-Agnostic — a universal AI agent memory layer. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`CLAUDE.md`\n- **Why OMPA?**（project_doc）：OMPA Universal AI Agent Memory Layer Vault · Palace · Temporal Knowledge Graph 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`README.md`\n- **MCP Desktop Setup**（project_doc）：Step-by-step guide for connecting OMPA to Claude Desktop, Cursor, or Windsurf via MCP. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`examples/mcp_desktop/README.md`\n- **Contributing to OMPA**（project_doc）：Thanks for your interest in contributing. Here's everything you need to get started. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`CONTRIBUTING.md`\n- **Changelog**（project_doc）： 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/changelog.md`\n- **OMPA**（project_doc）：Universal AI Agent Memory Layer — Vault · Palace · Temporal Knowledge Graph 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/index.md`\n- **Quickstart**（project_doc）：This guide walks you from zero to a running OMPA vault in under 5 minutes. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/quickstart.md`\n- **CLI Reference**（project_doc）：All CLI commands are available via ao . 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/api/cli.md`\n- **Knowledge Graph**（project_doc）：The KnowledgeGraph stores temporal triples: subject → predicate → object with optional validity windows. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/api/kg.md`\n- **Ompa**（project_doc）：The Ompa class is the main entry point. It integrates all three layers Vault, Palace, Knowledge Graph with lifecycle hooks, message classification, and semantic search. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/api/ompa.md`\n- **Palace**（project_doc）：The Palace is the agent-accessible metadata layer — a navigational index over the vault. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/api/palace.md`\n- **Vault**（project_doc）：The Vault class manages the markdown note storage layer. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/api/vault.md`\n- **Dual-Vault**（project_doc）：Dual-vault mode separates shared team/org content from personal private/sensitive content into two isolated vaults. Each vault has its own palace, knowledge graph, and semantic index. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/guides/dual-vault.md`\n- **Lifecycle Hooks**（project_doc）：OMPA provides 5 lifecycle hooks that wrap your agent's natural event loop. Each hook has a token budget — the maximum context it injects into your agent. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/guides/hooks.md`\n- **MCP Server**（project_doc）：OMPA exposes all of its capabilities as an MCP Model Context Protocol server with 15 tools. This lets Claude Desktop, Cursor, Windsurf, and any MCP-compatible client access your vault directly — no code changes needed. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/guides/mcp.md`\n- **Message Types**（project_doc）：OMPA classifies messages into 15 types, each with auto-routing rules that file content in the right vault folder. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/guides/message-types.md`\n- **Summary**（project_doc）：- Bug fix - New feature - Breaking change - Documentation - Refactor / chore 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`.github/pull_request_template.md`\n- **Changelog**（project_doc）：All notable changes to OMPA are documented here. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`CHANGELOG.md`\n- **Security Audit — OMPA v1.0.0**（project_doc）：Date: 2026-05-07 Version: 1.0.0 Tool versions: bandit 1.8.x, mypy 1.x, manual review 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`SECURITY_AUDIT.md`\n- **API Stability**（project_doc）：OMPA follows Semantic Versioning https://semver.org/ starting at v1.0.0. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`STABILITY.md`\n- **Bug report**（project_doc）：Describe the bug A clear description of what went wrong. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`.github/ISSUE_TEMPLATE/bug_report.md`\n- **Feature request**（project_doc）：Problem this solves What problem or gap is this feature addressing? Be specific. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`.github/ISSUE_TEMPLATE/feature_request.md`\n\n## 证据索引\n\n- 共索引 44 条证据。\n\n- **CLAUDE.md — OMPA**（documentation）：You are building OMPA Obsidian-MemPalace-Agnostic — a universal AI agent memory layer. 证据：`CLAUDE.md`\n- **Why OMPA?**（documentation）：OMPA Universal AI Agent Memory Layer Vault · Palace · Temporal Knowledge Graph 证据：`README.md`\n- **MCP Desktop Setup**（documentation）：Step-by-step guide for connecting OMPA to Claude Desktop, Cursor, or Windsurf via MCP. 证据：`examples/mcp_desktop/README.md`\n- **Contributing to OMPA**（documentation）：Thanks for your interest in contributing. Here's everything you need to get started. 证据：`CONTRIBUTING.md`\n- **License**（source_file）：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: 证据：`LICENSE`\n- **Changelog**（documentation）：Changelog 证据：`docs/changelog.md`\n- **OMPA**（documentation）：Universal AI Agent Memory Layer — Vault · Palace · Temporal Knowledge Graph 证据：`docs/index.md`\n- **Quickstart**（documentation）：This guide walks you from zero to a running OMPA vault in under 5 minutes. 证据：`docs/quickstart.md`\n- **CLI Reference**（documentation）：All CLI commands are available via ao . 证据：`docs/api/cli.md`\n- **Knowledge Graph**（documentation）：The KnowledgeGraph stores temporal triples: subject → predicate → object with optional validity windows. 证据：`docs/api/kg.md`\n- **Ompa**（documentation）：The Ompa class is the main entry point. It integrates all three layers Vault, Palace, Knowledge Graph with lifecycle hooks, message classification, and semantic search. 证据：`docs/api/ompa.md`\n- **Palace**（documentation）：The Palace is the agent-accessible metadata layer — a navigational index over the vault. 证据：`docs/api/palace.md`\n- **Vault**（documentation）：The Vault class manages the markdown note storage layer. 证据：`docs/api/vault.md`\n- **Dual-Vault**（documentation）：Dual-vault mode separates shared team/org content from personal private/sensitive content into two isolated vaults. Each vault has its own palace, knowledge graph, and semantic index. 证据：`docs/guides/dual-vault.md`\n- **Lifecycle Hooks**（documentation）：OMPA provides 5 lifecycle hooks that wrap your agent's natural event loop. Each hook has a token budget — the maximum context it injects into your agent. 证据：`docs/guides/hooks.md`\n- **MCP Server**（documentation）：OMPA exposes all of its capabilities as an MCP Model Context Protocol server with 15 tools. This lets Claude Desktop, Cursor, Windsurf, and any MCP-compatible client access your vault directly — no code changes needed. 证据：`docs/guides/mcp.md`\n- **Message Types**（documentation）：OMPA classifies messages into 15 types, each with auto-routing rules that file content in the right vault folder. 证据：`docs/guides/message-types.md`\n- **Summary**（documentation）：- Bug fix - New feature - Breaking change - Documentation - Refactor / chore 证据：`.github/pull_request_template.md`\n- **Changelog**（documentation）：All notable changes to OMPA are documented here. 证据：`CHANGELOG.md`\n- **Security Audit — OMPA v1.0.0**（documentation）：Date: 2026-05-07 Version: 1.0.0 Tool versions: bandit 1.8.x, mypy 1.x, manual review 证据：`SECURITY_AUDIT.md`\n- **API Stability**（documentation）：OMPA follows Semantic Versioning https://semver.org/ starting at v1.0.0. 证据：`STABILITY.md`\n- **Minimal code that reproduces the issue**（documentation）：Describe the bug A clear description of what went wrong. 证据：`.github/ISSUE_TEMPLATE/bug_report.md`\n- **What the API/CLI might look like**（documentation）：Problem this solves What problem or gap is this feature addressing? Be specific. 证据：`.github/ISSUE_TEMPLATE/feature_request.md`\n- **.Markdownlint**（structured_config）：{ \"MD013\": false, \"MD024\": { \"siblings only\": true } } 证据：`.markdownlint.json`\n- **Byte-compiled / optimized / DLL files**（source_file）：Byte-compiled / optimized / DLL files pycache / .py cod $py.class 证据：`.gitignore`\n- **---------------------------------------------------------------------------**（source_file）：Measures Recall@5 on a subset of LongMemEval-style questions using OMPA's verbatim storage + semantic search. Reports the headline metric that OMPA claims: 96.6% R@5 established by MemPalace on the same storage approach . 证据：`benchmarks/longmemeval.py`\n- **Demo**（source_file）：{\"version\": 2, \"width\": 80, \"height\": 24, \"duration\": 7.89794135093689, \"command\": \"ao demo\", \"title\": \"AgnosticObsidian \\u2014 Universal AI Agent Memory\", \"env\": {\"TERM\": \"xterm-256color\", \"SHELL\": \"/bin/bash\"}} 0.5000827312469482, \"o\", \"\\u001b 1;36m\\u2554\\u2550\\u2550\\u2550\\u2550\\u2550\\u2550\\u2550\\u2550\\u2550\\u2550\\u2550\\u2550\\u2550\\u2550\\u2550\\u2550\\u2550\\u2550\\u2550\\u2550\\u2550\\u2550\\u2550\\u2550\\u2550\\u2550\\u2550\\u2550\\u2550\\u2550\\u2550\\u2550\\u2550\\u2550\\u2550\\u2550\\u2550\\u2550\\u2550\\u2550\\u2550\\u2550\\u2550\\u2550\\u2550\\u2550\\u2550\\u2550\\u2550\\u2550\\u2550\\u2550\\u2550\\u2550\\u2550\\u2550\\u2557\\u001b 0m\\r\\n\" 0.5000901222229004, \"o\", \"\\u001b 1;36m\\u2551 AgnosticObsidian \\u2014 Universal AI Age… 证据：`demo.cast`\n- **Mkdocs**（source_file）：site name: OMPA site description: Universal AI agent memory layer — vault + palace + temporal knowledge graph site author: Micap AI repo url: https://github.com/jmiaie/ompa repo name: jmiaie/ompa edit uri: edit/main/docs/ 证据：`mkdocs.yml`\n- **Backward compatibility alias**（source_file）：\"\"\" OMPA — Obsidian-MemPalace-Agnostic 证据：`ompa/__init__.py`\n- **Main**（source_file）：\"\"\"Allow running OMPA as a module: python -m ompa\"\"\" 证据：`ompa/__main__.py`\n- **Or manually:**（source_file）：\"\"\" AsyncOmpa — async-native wrapper around Ompa. 证据：`ompa/async_api.py`\n- **Regex patterns for classification**（source_file）：\"\"\" Message classification for routing and context injection. Classifies user messages into categories and injects routing hints. Also classifies content for dual-vault routing shared vs personal . \"\"\" 证据：`ompa/classifier.py`\n- **Dual-vault init**（source_file）：\"\"\" CLI for OMPA. Run with: ao or ao-mcp \"\"\" 证据：`ompa/cli.py`\n- **Default classification indicators**（source_file）：\"\"\" OMPA Configuration — Dual-vault settings and content classification rules. 证据：`ompa/config.py`\n- **Dual-vault parameters**（source_file）：\"\"\" OMPA — Universal AI Agent Memory Layer Core module integrating vault, palace, KG, hooks, classifier, and semantic search. Supports single-vault legacy and dual-vault shared + personal architecture. \"\"\" 证据：`ompa/core.py`\n- **North Star**（source_file）：\"\"\" Lifecycle hooks for OMPA. Handles session start, user message, post tool, pre compact, and stop events. \"\"\" 证据：`ompa/hooks.py`\n- **WAL mode: readers don't block writers; writers don't block readers.**（source_file）：\"\"\" Knowledge Graph — Temporal Entity-Relationship Graph for OMPA. Inspired by MemPalace's knowledge graph.py. SQLite-based triples with validity windows. 证据：`ompa/knowledge_graph.py`\n- **Claude Desktop**（source_file）：\"\"\" OMPA MCP Server Provides 15+ tools via the Model Context Protocol. Works with Claude Desktop, Cursor, Windsurf, and any MCP-compatible client. 证据：`ompa/mcp_server.py`\n- **Increment this when new migrations are added.**（source_file）：Detects the version of an existing vault and applies any needed schema upgrades: KG index additions, palace rebuilds, semantic index refreshes. 证据：`ompa/migration.py`\n- **Wing operations**（source_file）：\"\"\" Palace — Wing/Room/Closet/Drawer metadata layer for OMPA. Inspired by MemPalace. Manages the structured metadata that accelerates retrieval. \"\"\" 证据：`ompa/palace.py`\n- **Accept a pre-built backend e.g. NIMEmbeddingBackend or load lazily**（source_file）：\"\"\" Semantic search for OMPA. Provides hybrid keyword + semantic search across the vault. Supports a pluggable embedding backend sentence-transformers by default, or any object with an encode text: str - array interface . \"\"\" 证据：`ompa/semantic.py`\n- **Heuristic: ~1.3 tokens per whitespace-delimited word conservative for code**（source_file）：\"\"\" Token counting with tiktoken precise or word-count heuristic fallback . 证据：`ompa/token_counter.py`\n- **Shared exclude patterns for vault traversal**（source_file）：\"\"\" Vault management for OMPA. Handles note organization, templates, wikilinks, and frontmatter validation. \"\"\" 证据：`ompa/vault.py`\n- **Pyproject**（source_file）：project name = \"ompa\" version = \"1.0.8\" description = \"Universal AI agent memory layer — vault + palace + temporal knowledge graph\" readme = \"README.md\" license = {text = \"MIT\"} requires-python = \" =3.10\" authors = {name = \"Micap AI\", email = \"info@micap.ai\"}, keywords = \"ai\", \"agent\", \"memory\", \"obsidian\", \"knowledge-graph\", \"mcp\", \"claude\", \"llm\", \"rag\", \"semantic-search\", \"langchain\", \"llamaindex\", \"nvidia\", \"nim\", \"multi-agent\" classifiers = \"Development Status :: 5 - Production/Stable\", \"Intended Audience :: Developers\", \"License :: OSI Approved :: MIT License\", \"Programming Language :: Python :: 3.10\", \"Programming Language :: Python :: 3.11\", \"Programming Language :: Python :: 3.12\",… 证据：`pyproject.toml`\n\n## 宿主 AI 必须遵守的规则\n\n- **把本资产当作开工前上下文，而不是运行环境。**：AI Context Pack 只包含证据化项目理解，不包含目标项目的可执行状态。 证据：`CLAUDE.md`, `README.md`, `examples/mcp_desktop/README.md`\n- **回答用户时区分可预览内容与必须安装后才能验证的内容。**：安装前体验的消费者价值来自降低误装和误判，而不是伪装成真实运行。 证据：`CLAUDE.md`, `README.md`, `examples/mcp_desktop/README.md`\n\n## 用户开工前应该回答的问题\n\n- 你准备在哪个宿主 AI 或本地环境中使用它？\n- 你只是想先体验工作流，还是准备真实安装？\n- 你最在意的是安装成本、输出质量、还是和现有规则的冲突？\n\n## 验收标准\n\n- 所有能力声明都能回指到 evidence_refs 中的文件路径。\n- AI_CONTEXT_PACK.md 没有把预览包装成真实运行。\n- 用户能在 3 分钟内看懂适合谁、能做什么、如何开始和风险边界。\n\n---\n\n## Doramagic Context Augmentation\n\n下面内容用于强化 Repomix/AI Context Pack 主体。Human Manual 只提供阅读骨架；踩坑日志会被转成宿主 AI 必须遵守的工作约束。\n\n## Human Manual 骨架\n\n使用规则：这里只是项目阅读路线和显著性信号，不是事实权威。具体事实仍必须回到 repo evidence / Claim Graph。\n\n宿主 AI 硬性规则：\n- 不得把页标题、章节顺序、摘要或 importance 当作项目事实证据。\n- 解释 Human Manual 骨架时，必须明确说它只是阅读路线/显著性信号。\n- 能力、安装、兼容性、运行状态和风险判断必须引用 repo evidence、source path 或 Claim Graph。\n\n- **项目介绍**：importance `high`\n - source_paths: README.md, pyproject.toml\n- **快速入门**：importance `high`\n - source_paths: docs/quickstart.md, ompa/__init__.py, examples/simple_vault/demo.py\n- **三层架构设计**：importance `high`\n - source_paths: ompa/vault.py, ompa/palace.py, ompa/knowledge_graph.py\n- **生命周期钩子**：importance `high`\n - source_paths: ompa/hooks.py, ompa/core.py\n- **Vault存储层**：importance `high`\n - source_paths: ompa/vault.py, ompa/core.py\n- **Palace元数据层**：importance `high`\n - source_paths: ompa/palace.py\n- **时序知识图谱**：importance `high`\n - source_paths: ompa/knowledge_graph.py\n- **消息分类器**：importance `medium`\n - source_paths: ompa/classifier.py\n\n## Repo Inspection Evidence / 源码检查证据\n\n- repo_clone_verified: true\n- repo_inspection_verified: true\n- repo_commit: `40ff3e241490825d6dc8714c2d5594316e0cb69c`\n- inspected_files: `pyproject.toml`, `README.md`, `docs/index.md`, `docs/quickstart.md`, `docs/changelog.md`, `docs/api/cli.md`, `docs/api/vault.md`, `docs/api/kg.md`, `docs/api/ompa.md`, `docs/api/palace.md`, `docs/guides/dual-vault.md`, `docs/guides/hooks.md`, `docs/guides/message-types.md`, `docs/guides/mcp.md`, `examples/simple_vault/demo.py`, `examples/mcp_desktop/README.md`, `examples/langchain_agent/ompa_memory.py`, `examples/multi_agent/swarm_memory.py`\n\n宿主 AI 硬性规则：\n- 没有 repo_clone_verified=true 时，不得声称已经读过源码。\n- 没有 repo_inspection_verified=true 时，不得把 README/docs/package 文件判断写成事实。\n- 没有 quick_start_verified=true 时，不得声称 Quick Start 已跑通。\n\n## Doramagic Pitfall Constraints / 踩坑约束\n\n这些规则来自 Doramagic 发现、验证或编译过程中的项目专属坑点。宿主 AI 必须把它们当作工作约束，而不是普通说明文字。\n\n### Constraint 1: 来源证据：OMPA v0.2.0 — The Big Rename\n\n- Trigger: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：OMPA v0.2.0 — The Big Rename\n- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Why it matters: 可能阻塞安装或首次运行。\n- Evidence: community_evidence:github | cevd_ac771ab081be444ab18c5c1963becb64 | https://github.com/jmiaie/ompa/releases/tag/v0.2.0 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 2: 来源证据：[P0] agent_integration.py race condition — session.memory attribute not available on cold start\n\n- Trigger: GitHub 社区证据显示该项目存在一个配置相关的待验证问题：[P0] agent_integration.py race condition — session.memory attribute not available on cold start\n- Host AI rule: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Why it matters: 可能阻塞安装或首次运行。\n- Evidence: community_evidence:github | cevd_db65ef8ac28c41048d74c03c80cbed28 | https://github.com/jmiaie/ompa/issues/6 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 3: 能力判断依赖假设\n\n- Trigger: README/documentation is current enough for a first validation pass.\n- Host AI rule: 将假设转成下游验证清单。\n- Why it matters: 假设不成立时，用户拿不到承诺的能力。\n- Evidence: capability.assumptions | github_repo:1207151629 | https://github.com/jmiaie/ompa | README/documentation is current enough for a first validation pass.\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 4: 维护活跃度未知\n\n- Trigger: 未记录 last_activity_observed。\n- Host AI rule: 补 GitHub 最近 commit、release、issue/PR 响应信号。\n- Why it matters: 新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- Evidence: evidence.maintainer_signals | github_repo:1207151629 | https://github.com/jmiaie/ompa | last_activity_observed missing\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 5: 下游验证发现风险项\n\n- Trigger: no_demo\n- Host AI rule: 进入安全/权限治理复核队列。\n- Why it matters: 下游已经要求复核，不能在页面中弱化。\n- Evidence: downstream_validation.risk_items | github_repo:1207151629 | https://github.com/jmiaie/ompa | no_demo; severity=medium\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 6: 存在安全注意事项\n\n- Trigger: No sandbox install has been executed yet; downstream must verify before user use.\n- Host AI rule: 转成明确权限清单和安全审查提示。\n- Why it matters: 用户安装前需要知道权限边界和敏感操作。\n- Evidence: risks.safety_notes | github_repo:1207151629 | https://github.com/jmiaie/ompa | No sandbox install has been executed yet; downstream must verify before user use.\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 7: 存在评分风险\n\n- Trigger: no_demo\n- Host AI rule: 把风险写入边界卡，并确认是否需要人工复核。\n- Why it matters: 风险会影响是否适合普通用户安装。\n- Evidence: risks.scoring_risks | github_repo:1207151629 | https://github.com/jmiaie/ompa | no_demo; severity=medium\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 8: 来源证据：OMPA v0.2.1 — Security & Reliability Hardening\n\n- Trigger: GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：OMPA v0.2.1 — Security & Reliability Hardening\n- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Why it matters: 可能阻塞安装或首次运行。\n- Evidence: community_evidence:github | cevd_ab0ad6b963354f2096bef6783c95c289 | https://github.com/jmiaie/ompa/releases/tag/v0.2.1 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 9: issue/PR 响应质量未知\n\n- Trigger: issue_or_pr_quality=unknown。\n- Host AI rule: 抽样最近 issue/PR，判断是否长期无人处理。\n- Why it matters: 用户无法判断遇到问题后是否有人维护。\n- Evidence: evidence.maintainer_signals | github_repo:1207151629 | https://github.com/jmiaie/ompa | issue_or_pr_quality=unknown\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 10: 发布节奏不明确\n\n- Trigger: release_recency=unknown。\n- Host AI rule: 确认最近 release/tag 和 README 安装命令是否一致。\n- Why it matters: 安装命令和文档可能落后于代码，用户踩坑概率升高。\n- Evidence: evidence.maintainer_signals | github_repo:1207151629 | https://github.com/jmiaie/ompa | release_recency=unknown\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n",
"summary": "给宿主 AI 的上下文和工作边界。",
"title": "AI Context Pack / 带给我的 AI"
},
"boundary_risk_card": {
"asset_id": "boundary_risk_card",
"filename": "BOUNDARY_RISK_CARD.md",
"markdown": "# Boundary & Risk Card / 安装前决策卡\n\n项目：jmiaie/ompa\n\n## Doramagic 试用结论\n\n当前结论：可以进入发布前推荐检查；首次使用仍应从最小权限、临时目录和可回滚配置开始。\n\n## 用户现在可以做\n\n- 可以先阅读 Human Manual，理解项目目的和主要工作流。\n- 可以复制 Prompt Preview 做安装前体验；这只验证交互感，不代表真实运行。\n- 可以把官方 Quick Start 命令放到隔离环境中验证，不要直接进主力环境。\n\n## 现在不要做\n\n- 不要把 Prompt Preview 当成项目实际运行结果。\n- 不要把 metadata-only validation 当成沙箱安装验证。\n- 不要把未验证能力写成“已支持、已跑通、可放心安装”。\n- 不要在首次试用时交出生产数据、私人文件、真实密钥或主力配置目录。\n\n## 安装前检查\n\n- 宿主 AI 是否匹配：mcp_host\n- 官方安装入口状态：已发现官方入口\n- 是否在临时目录、临时宿主或容器中验证：必须是\n- 是否能回滚配置改动：必须能\n- 是否需要 API Key、网络访问、读写文件或修改宿主配置：未确认前按高风险处理\n- 是否记录了安装命令、实际输出和失败日志：必须记录\n\n## 当前阻塞项\n\n- 无阻塞项。\n\n## 项目专属踩坑\n\n- 来源证据：OMPA v0.2.0 — The Big Rename（medium）：可能阻塞安装或首次运行。 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 来源证据：[P0] agent_integration.py race condition — session.memory attribute not available on cold start（medium）：可能阻塞安装或首次运行。 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 能力判断依赖假设（medium）：假设不成立时，用户拿不到承诺的能力。 建议检查：将假设转成下游验证清单。\n- 维护活跃度未知（medium）：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 下游验证发现风险项（medium）：下游已经要求复核，不能在页面中弱化。 建议检查：进入安全/权限治理复核队列。\n\n## 风险与权限提示\n\n- no_demo: medium\n\n## 证据缺口\n\n- 暂未发现结构化证据缺口。\n",
"summary": "安装、权限、验证和推荐前风险。",
"title": "Boundary & Risk Card / 边界与风险卡"
},
"human_manual": {
"asset_id": "human_manual",
"filename": "HUMAN_MANUAL.md",
"markdown": "# https://github.com/jmiaie/ompa 项目说明书\n\n生成时间：2026-05-13 05:17:58 UTC\n\n## 目录\n\n- [项目介绍](#intro)\n- [快速入门](#quickstart)\n- [三层架构设计](#three-layer-design)\n- [生命周期钩子](#lifecycle-hooks)\n- [Vault存储层](#vault)\n- [Palace元数据层](#palace)\n- [时序知识图谱](#knowledge-graph)\n- [消息分类器](#classifier)\n- [MCP服务器集成](#mcp-server)\n- [框架适配器](#adapters)\n\n\n\n## 项目介绍\n\n### 相关页面\n\n相关主题：[快速入门](#quickstart), [三层架构设计](#three-layer-design)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/jmiaie/ompa/blob/main/README.md)\n- [CLAUDE.md](https://github.com/jmiaie/ompa/blob/main/CLAUDE.md)\n- [CONTRIBUTING.md](https://github.com/jmiaie/ompa/blob/main/CONTRIBUTING.md)\n- [CHANGELOG.md](https://github.com/jmiaie/ompa/blob/main/CHANGELOG.md)\n- [STABILITY.md](https://github.com/jmiaie/ompa/blob/main/STABILITY.md)\n- [examples/mcp_desktop/README.md](https://github.com/jmiaie/ompa/blob/main/examples/mcp_desktop/README.md)\n- [ompa/core.py](https://github.com/jmiaie/ompa/blob/main/ompa/core.py)\n- [ompa/classifier.py](https://github.com/jmiaie/ompa/blob/main/ompa/classifier.py)\n \n\n# 项目介绍\n\n## 概述\n\n**OMPA**（Obsidian-MemPalace-Agnostic）是一个专为 AI Agent 设计的记忆管理系统，旨在为 Claude Code、OpenClaw、Codex 等 Agent 框架提供持久化记忆能力。项目最初从 [MemPalace](https://github.com/corbt/mem_palace) 启发而来，并融合了 obsidian-mind 等社区项目的优秀理念。\n\n资料来源：[README.md:1]()\n\nOMPA 的核心理念是**逐字存储**（verbatim storage）而非摘要，确保记忆的完整性和可追溯性。根据 MemPalace 的研究验证，逐字存储方案可达到 96.6% 的检索准确率（Recall@5）。\n\n资料来源：[CLAUDE.md:1]()\n\n## 核心定位\n\nOMPA 解决的核心问题是：**AI Agent 在长时间会话中如何有效管理、检索和利用历史信息**。\n\n传统 Agent 框架面临以下挑战：\n\n| 挑战 | OMPA 解决方案 |\n|------|--------------|\n| 上下文窗口有限 | 分层记忆架构，按需注入相关上下文 |\n| 记忆检索困难 | 语义搜索 + 知识图谱双引擎 |\n| 团队/个人内容混淆 | 双保险库（Dual-Vault）隔离机制 |\n| 框架绑定 | 纯 Python 实现，无 Agent SDK 依赖 |\n\n资料来源：[README.md:1]()\n\n## 技术架构\n\n### 整体架构图\n\n```mermaid\ngraph TB\n subgraph \"Agent Layer\"\n ClaudeCode[Claude Code]\n OpenClaw[OpenClaw]\n Codex[Codex]\n GeminiCLI[Gemini CLI]\n end\n\n subgraph \"OMPA Core\"\n Core[Ompa 核心类]\n Classifier[消息分类器]\n Hooks[生命周期钩子]\n end\n\n subgraph \"Storage Layer\"\n Vault[(Vault
记忆存储)]\n Palace[(Palace
宫殿元数据)]\n KG[(Knowledge Graph
时序知识图谱)]\n Semantic[Semantic Index
语义索引]\n end\n\n ClaudeCode --> Core\n OpenClaw --> Core\n Codex --> Core\n GeminiCLI --> Core\n\n Core --> Classifier\n Core --> Hooks\n Core --> Vault\n Core --> Palace\n Core --> KG\n Core --> Semantic\n```\n\n### 模块说明\n\n| 模块 | 文件路径 | 职责 |\n|------|---------|------|\n| **core.py** | `ompa/core.py` | Ompa 主类 — 生命周期管理、消息处理、双保险库 |\n| **vault.py** | `ompa/vault.py` | 保险库管理 — brain/work/org/perf 文件夹 CRUD |\n| **palace.py** | `ompa/palace.py` | 宫殿元数据 — wings/rooms/drawers/halls/tunnels |\n| **knowledge_graph.py** | `ompa/knowledge_graph.py` | 时序知识图谱 — SQLite 三元组 + 有效期窗口 |\n| **hooks.py** | `ompa/hooks.py` | 5 个生命周期钩子 + HookManager |\n| **classifier.py** | `ompa/classifier.py` | 15 种消息类型 + 自动路由 |\n| **semantic.py** | `ompa/semantic.py` | 本地语义搜索（延迟模型加载） |\n| **mcp_server.py** | `ompa/mcp_server.py` | MCP 协议服务器（15 个工具） |\n| **config.py** | `ompa/config.py` | 双保险库配置 |\n| **cli.py** | `ompa/cli.py` | Typer CLI（14 个命令） |\n\n资料来源：[README.md:1]()\n\n## 核心功能特性\n\n### 1. 双保险库架构（Dual-Vault）\n\nOMPA 支持将团队/组织内容与个人/私密笔记隔离存储：\n\n```python\nfrom ompa import Ompa, DualVaultConfig, IsolationMode\n\nconfig = DualVaultConfig(\n shared_vault=\"./team-vault\",\n personal_vault=\"./private-vault\",\n mode=IsolationMode.AUTO,\n)\nao = Ompa(config=config)\n```\n\n**隔离模式（IsolationMode）**：\n\n| 模式 | 说明 |\n|------|------|\n| `AUTO` | 根据消息类型自动分类到共享或个人保险库 |\n| `MANUAL` | 每个操作显式指定 `VaultTarget` |\n| `STRICT` | 强制隔离，不允许跨保险库访问 |\n\n资料来源：[README.md:1]()\n\n### 2. 消息自动分类\n\nOMPA 内置 15 种消息类型分类器，自动识别并路由消息到对应文件夹：\n\n```mermaid\ngraph LR\n Input[用户消息] --> Classifier[Classifier]\n Classifier --> DEC[DECISION]\n Classifier --> INC[INCIDENT]\n Classifier --> WIN[WIN]\n Classifier --> O1O[ONE_ON_ONE]\n Classifier --> Q[QUESTION]\n Classifier --> OTHER[...]\n```\n\n**消息类型列表**：\n\n| 枚举值 | 触发关键词 | 路由目标 |\n|--------|-----------|---------|\n| `DECISION` | decided, agreed, settled | brain/decisions/ |\n| `INCIDENT` | incident, outage, bug | brain/incidents/ |\n| `WIN` | won, shipped, launched | brain/wins/ |\n| `ONE_ON_ONE` | 1:1, feedback, career | org/1on1/ |\n| `MEETING` | meeting, standup | org/meetings/ |\n| `PROJECT_UPDATE` | project, blocked, sprint | org/projects/ |\n| `PERSON_INFO` | teammate, joined, role | org/people/ |\n| `QUESTION` | how do, what is, why | brain/questions/ |\n| `TASK` | todo, action item | work/tasks/ |\n| `ARCHITECTURE` | architecture, design | brain/architecture/ |\n| `CODE` | code, function, PR | brain/code/ |\n| `BRAIN_DUMP` | dump, stream | brain/dumps/ |\n| `WRAP_UP` | wrap up, end session | brain/sessions/ |\n| `STANDUP` | standup, daily | org/standups/ |\n\n资料来源：[ompa/classifier.py:1]()\n\n### 3. 时序知识图谱（Temporal Knowledge Graph）\n\nKG 使用 SQLite 存储三元组，支持时间维度查询：\n\n```python\n# 添加带时间窗口的三元组\nao.kg.add_triple(\"Kai\", \"works_on\", \"Orion\", valid_from=\"2025-06-01\")\n\n# 查询实体历史\ntriples = ao.kg.query_entity(\"Kai\")\n\n# 查询时间线\ntimeline = ao.kg.timeline(\"Orion\")\n```\n\n**数据模型**：\n\n```\nTriple(subject, predicate, object, valid_from, valid_to, confidence, source_file)\n```\n\n资料来源：[README.md:1]()\n\n### 4. 本地语义搜索\n\nOMPA 提供本地语义索引，无需 API 调用即可实现语义搜索：\n\n```python\nresults = ao.search(\"authentication decisions\", wing=\"Orion\")\n```\n\n**特性**：\n\n- 延迟加载模型，首次访问时才下载\n- 增量索引，仅重新嵌入修改过的文件\n- 支持 wing/room 级别的范围搜索\n\n资料来源：[README.md:1]()\n\n### 5. 生命周期钩子系统\n\n支持 5 个生命周期钩子，允许自定义扩展：\n\n```python\nclass MyHook(Hook):\n def __init__(self):\n super().__init__(\"my_hook\", token_budget=50)\n\n def execute(self, context: HookContext, **kwargs) -> HookResult:\n return HookResult(hook_name=self.name, success=True, output=\"...\", tokens_hint=50)\n\nao = Ompa(\"./workspace\")\nao.hooks.register_hook(\"my_hook\", MyHook())\n```\n\n资料来源：[CLAUDE.md:1]()\n\n## 安装与使用\n\n### 安装方式\n\n```bash\n# 核心功能\npip install ompa\n\n# 含本地语义搜索（首次运行下载约 500MB 模型）\npip install ompa[all]\n\n# 开发模式\npip install ompa[dev]\n```\n\n**环境要求**：Python 3.10+\n\n资料来源：[README.md:1]()\n\n### CLI 命令参考\n\n| 命令 | 功能 |\n|------|------|\n| `ao init` | 初始化新保险库 |\n| `ao status` | 健康检查和统计 |\n| `ao session-start` | 注入记忆上下文 |\n| `ao classify ` | 分类并路由消息 |\n| `ao search ` | 语义搜索 |\n| `ao orphans` | 检测孤立笔记 |\n| `ao wrap-up` | 会话总结并保存 |\n| `ao wings` | 列出宫殿 wing |\n| `ao rooms ` | 列出 wing 中的房间 |\n| `ao tunnel` | 创建/穿越跨 wing 隧道 |\n| `ao kg-query ` | 查询知识图谱 |\n| `ao validate` | 验证保险库结构 |\n| `ao rebuild-index` | 重建语义索引 |\n\n资料来源：[README.md:1]()\n\n### MCP 集成\n\nOMPA 提供 MCP（Model Context Protocol）服务器，可与 Claude Desktop、Cursor、Windsurf 等 IDE 集成：\n\n```bash\n# Claude Desktop\nclaude mcp add ompa -- python -m ompa.mcp_server\n\n# 或手动配置 ~/.claude/claude_desktop_config.json\n{\n \"mcpServers\": {\n \"ompa\": {\n \"command\": \"python\",\n \"args\": [\"-m\", \"ompa.mcp_server\"],\n \"env\": {\n \"OMPA_VAULT_PATH\": \"/absolute/path/to/vault\"\n }\n }\n }\n}\n```\n\n**MCP 工具列表**：\n\n```\nao_session_start, ao_classify, ao_search, ao_kg_query,\nao_kg_add, ao_kg_stats, ao_palace_wings, ao_palace_rooms,\nao_palace_tunnel, ao_validate, ao_wrap_up, ao_status, \nao_orphans, ao_init\n```\n\n资料来源：[examples/mcp_desktop/README.md:1]()\n\n## Python API 基础用法\n\n```python\nfrom ompa import Ompa\n\nao = Ompa(vault_path=\"./workspace\")\n\n# 会话生命周期\ncontext = ao.session_start() # 返回约 2K token 的上下文字符串\nhint = ao.handle_message(\"We won the enterprise deal!\")\nao.post_tool(\"write\", {\"file_path\": \"work/active/auth.md\"})\nao.stop()\n\n# 语义搜索\nresults = ao.search(\"authentication decisions\", wing=\"Orion\")\n\n# 知识图谱\nao.kg.add_triple(\"Kai\", \"works_on\", \"Orion\", valid_from=\"2025-06-01\")\ntriples = ao.kg.query_entity(\"Kai\")\ntimeline = ao.kg.timeline(\"Orion\")\n```\n\n资料来源：[README.md:1]()\n\n## 框架兼容性\n\n| Agent 框架 | 集成方式 |\n|-----------|---------|\n| Claude Code | Python API + MCP 服务器 |\n| OpenClaw | Python API + MCP 服务器 |\n| Codex | Python API + MCP 服务器 |\n| Gemini CLI | Python API + MCP 服务器 |\n| LangChain | Python API |\n\n资料来源：[README.md:1]()\n\n## 适配器生态\n\nOMPA 提供多种官方适配器，便于与其他生态系统集成：\n\n```python\n# LangChain 适配器\nfrom ompa.adapters.langchain import OmpaMemory, OmpaRetriever\n\n# LlamaIndex 适配器\nfrom ompa.adapters.llamaindex import OmpaReader, OmpaVaultRetriever\n\n# OpenAI Agents SDK 适配器\nfrom ompa.adapters.openai_agents import OmpaAgentHooks\n\n# FAISS 向量索引\nfrom ompa.adapters.faiss import FAISSSemanticIndex\n```\n\n资料来源：[STABILITY.md:1]()\n\n## 版本历史\n\n| 版本 | 日期 | 主要变更 |\n|------|------|---------|\n| 0.4.x | 2026-04 | 双保险库架构、路径遍历加固、语义延迟初始化 |\n| 0.3.x | 2026-04 | KG 自动填充、增量语义索引、脑图同步 |\n| 0.2.x | 2026-04 | 项目重命名 AgnosticObsidian → Ompa |\n| 0.1.x | 2026-04 | 初始版本发布 |\n\n资料来源：[CHANGELOG.md:1]()\n\n## 安全特性\n\n| 特性 | 说明 |\n|------|------|\n| 路径遍历防护 | 所有保险库文件操作解析并边界检查路径 |\n| UTF-8 编码强制 | 所有文件写入显式指定 UTF-8 编码 |\n| 敏感信息过滤 | 导出时自动清除个人标识符 |\n\n资料来源：[CHANGELOG.md:1]()\n\n## 开发指南\n\n### 本地开发\n\n```bash\ngit clone https://github.com/jmiaie/ompa\ncd ompa\npip install -e \".[dev,all]\"\n\n# 运行测试\npytest tests/ -v\n\n# 代码检查\nruff check ompa/\nruff format ompa/\n```\n\n资料来源：[CONTRIBUTING.md:1]()\n\n### 添加新消息类型\n\n1. 在 `classifier.py` 中添加 `MessageType` 枚举值\n2. 添加正则模式到 `PATTERNS[MessageType]`\n3. 添加路由提示到 `ROUTING_HINTS[MessageType]`\n4. 添加文件夹映射到 `FOLDER_MAP[MessageType]`\n5. 在 `tests/test_ompa.py` 中添加测试用例\n\n资料来源：[CONTRIBUTING.md:1]()\n\n## 架构设计决策\n\n| 决策 | 说明 |\n|------|------|\n| 延迟语义加载 | `SemanticIndex._model` 在首次访问时加载 |\n| 框架无关性 | 纯 Python，无 Agent SDK 依赖 |\n| 保险库 + 宫殿双层 | 保险库为数据源，宫殿为检索加速层 |\n| 逐字存储 | 不做摘要，MemPalace 验证 96.6% R@5 |\n| 时序知识图谱 | SQLite 三元组 + 有效期窗口 |\n| 路径遍历守卫 | 所有文件操作解析 + 边界检查 |\n| 上下文管理器 | SQLite 连接使用 `with` 确保无泄漏 |\n\n资料来源：[CLAUDE.md:1]()\n\n## 致谢\n\nOMPA 是 AI Agent 记忆社区优秀理念的集大成者：\n\n- **[MemPalace](https://github.com/corbt/mem_palace)** by Kyle Corbitt — 宫殿隐喻（wings/rooms/drawers/halls/tunnels）\n- **obsidian-mind** — Obsidian 记忆系统\n- **Claude Code** — Agent 框架参考\n- **OpenClaw** — Agent 框架参考\n\n资料来源：[README.md:1]()\n\n---\n\n\n\n## 快速入门\n\n### 相关页面\n\n相关主题：[项目介绍](#intro)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/jmiaie/ompa/blob/main/README.md)\n- [examples/mcp_desktop/README.md](https://github.com/jmiaie/ompa/blob/main/examples/mcp_desktop/README.md)\n- [CONTRIBUTING.md](https://github.com/jmiaie/ompa/blob/main/CONTRIBUTING.md)\n- [STABILITY.md](https://github.com/jmiaie/ompa/blob/main/STABILITY.md)\n- [CLAUDE.md](https://github.com/jmiaie/ompa/blob/main/CLAUDE.md)\n- [ompa/core.py](https://github.com/jmiaie/ompa/blob/main/ompa/core.py)\n- [ompa/mcp_server.py](https://github.com/jmiaie/ompa/blob/main/ompa/mcp_server.py)\n \n\n# 快速入门\n\n本文档面向希望快速上手 OMPA（Obsidian-MemPalace-Agnostic）的开发者。OMPA 是一个与框架无关的 AI Agent 记忆系统，提供 Vault 存储、Palace 记忆加速和 Temporal Knowledge Graph 功能。\n\n## 环境要求\n\n| 要求 | 版本/说明 |\n|------|----------|\n| Python | 3.10+ |\n| pip | 最新版 |\n\n> 资料来源：[README.md:1]()\n\n## 安装\n\nOMPA 提供多种安装方式，可根据需求选择：\n\n```bash\n# 仅核心功能（vault + palace + KG + CLI + MCP server）\npip install ompa\n\n# 包含本地语义搜索（首次运行需下载约 500MB 模型）\npip install ompa[all]\n\n# 开发版本\npip install ompa[dev]\n\n# 从源码安装\ngit clone https://github.com/jmiaie/ompa && cd ompa\npip install -e \".[all]\"\n```\n\n> 资料来源：[README.md:50-60]()\n\n## 核心概念\n\n在开始之前，了解 OMPA 的三个核心组件：\n\n```mermaid\ngraph TD\n A[Ompa 核心类] --> B[Vault 存储层]\n A --> C[Palace 检索加速]\n A --> D[Knowledge Graph 时序图谱]\n \n B --> B1[Brain Notes]\n B --> B2[Work Notes]\n B --> B3[Org Notes]\n B --> B4[Perf Notes]\n \n C --> C1[Wings 区域]\n C --> C2[Rooms 房间]\n C --> C3[Drawers 抽屉]\n \n D --> D1[Triples 三元组]\n D --> D2[Validity Windows 有效期]\n```\n\n> 资料来源：[CLAUDE.md:1]()\n\n| 组件 | 功能 | 数据存储 |\n|------|------|---------|\n| **Vault** | 笔记源文件管理 | Markdown 文件 + frontmatter |\n| **Palace** | 记忆结构化加速 | `.palace/` 元数据 |\n| **Knowledge Graph** | 时序关系图谱 | SQLite 数据库 |\n\n> 资料来源：[README.md:65-80]()\n\n## 初始化 Vault\n\nVault 是 OMPA 的源数据存储目录，包含 Brain、Work、Org、Perf 四个笔记分区。\n\n```bash\n# 初始化新的 vault\nao init\n\n# 检查 vault 健康状态\nao status\n```\n\n初始化后，将创建以下目录结构：\n\n```\n.\n├── .ompa/\n│ └── config.yaml\n├── brain/\n├── work/\n├── org/\n└── perf/\n```\n\n> 资料来源：[examples/mcp_desktop/README.md:1-10]()\n\n## CLI 快速命令\n\nOMPA 提供完整的命令行工具：\n\n```bash\n# 会话管理\nao session-start # 启动会话，注入约 2K token 上下文\nao wrap-up # 会话总结并保存\n\n# 笔记操作\nao classify # 分类并路由消息\nao search # 语义搜索\n\n# 知识图谱\nao kg-query # 查询实体\nao kg-timeline # 实体时间线\nao kg-stats # 图谱统计\n\n# Palace 导航\nao wings # 列出所有区域\nao rooms # 列出区域中的房间\nao tunnel # 创建/遍历跨区域通道\n\n# 工具\nao orphans # 检测孤立笔记\nao validate # 验证 vault 结构\nao rebuild-index # 重建语义索引\n```\n\n> 资料来源：[README.md:25-45]()\n\n## Python API 使用\n\n### 基本使用流程\n\n```python\nfrom ompa import Ompa\n\n# 初始化\nao = Ompa(vault_path=\"./workspace\")\n\n# 会话生命周期\ncontext = ao.session_start() # 获取上下文（约 2K tokens）\nhint = ao.handle_message(\"消息内容\") # 处理消息\nao.stop() # 停止会话\n\n# 语义搜索\nresults = ao.search(\"认证决策\", wing=\"Orion\")\n\n# 知识图谱\nao.kg.add_triple(\"Kai\", \"works_on\", \"Orion\", valid_from=\"2025-06-01\")\ntriples = ao.kg.query_entity(\"Kai\")\ntimeline = ao.kg.timeline(\"Orion\")\n```\n\n> 资料来源：[README.md:70-90]()\n\n### Ompa 核心类初始化参数\n\n```python\nfrom ompa import Ompa\n\nao = Ompa(\n vault_path=\"./workspace\", # Vault 路径\n agent_name=\"agent\", # Agent 名称（用于 KG 实体限定）\n enable_semantic=True, # 启用语义搜索\n embedding_backend=None, # 嵌入后端\n)\n```\n\n| 参数 | 类型 | 默认值 | 说明 |\n|------|------|--------|------|\n| `vault_path` | `str` | 必需 | Vault 根目录路径 |\n| `agent_name` | `str` | `\"agent\"` | Agent 标识符 |\n| `enable_semantic` | `bool` | `False` | 启用本地语义搜索 |\n| `embedding_backend` | `EmbeddingBackend` | `None` | 自定义嵌入后端 |\n\n> 资料来源：[STABILITY.md:10-25]()\n\n## 双 Vault 模式\n\nOMPA 支持双 Vault 架构，用于隔离团队/组织内容与个人/私密笔记。\n\n```python\nfrom ompa import Ompa, DualVaultConfig, IsolationMode\n\nconfig = DualVaultConfig(\n shared_vault=\"./team-vault\", # 共享 vault\n personal_vault=\"./private-vault\", # 个人 vault\n mode=IsolationMode.AUTO, # 自动分类模式\n)\nao = Ompa(config=config)\n```\n\n### 隔离模式\n\n| 模式 | 说明 |\n|------|------|\n| `AUTO` | 根据消息类型自动分类到共享或个人 vault |\n| `MANUAL` | 显式指定 `VaultTarget` 进行路由 |\n| `STRICT` | 严格分离，仅允许指定 vault 操作 |\n\n> 资料来源：[README.md:55-65]()\n\n### 环境变量配置\n\n| 变量 | 默认值 | 说明 |\n|------|--------|------|\n| `OMPA_VAULT_PATH` | `.` | Vault 绝对路径 |\n| `OMPA_ENABLE_SEMANTIC` | `false` | 启用本地语义搜索 |\n| `OMPA_AGENT_NAME` | `agent` | Agent 名称 |\n| `OMPA_SHARED_VAULT` | — | 双 Vault 模式下共享 vault 路径 |\n| `OMPA_PERSONAL_VAULT` | — | 双 Vault 模式下个人 vault 路径 |\n\n> 资料来源：[examples/mcp_desktop/README.md:50-60]()\n\n## MCP 服务器集成\n\nOMPA 提供 MCP（Model Context Protocol）服务器，可与 Claude Desktop、Cursor、Windsurf 等工具集成。\n\n### Claude Desktop 配置\n\n**方式一：CLI（推荐）**\n\n```bash\nclaude mcp add ompa -- python -m ompa.mcp_server\n```\n\n**方式二：手动配置**\n\n编辑 `~/.claude/claude_desktop_config.json`：\n\n```json\n{\n \"mcpServers\": {\n \"ompa\": {\n \"command\": \"python\",\n \"args\": [\"-m\", \"ompa.mcp_server\"],\n \"env\": {\n \"OMPA_VAULT_PATH\": \"/absolute/path/to/your/vault\"\n }\n }\n }\n}\n```\n\n### Cursor / Windsurf 配置\n\n创建 `.cursor/mcp.json` 或 `.windsurf/mcp.json`：\n\n```json\n{\n \"mcpServers\": {\n \"ompa\": {\n \"command\": \"python\",\n \"args\": [\"-m\", \"ompa.mcp_server\"],\n \"env\": {\n \"OMPA_VAULT_PATH\": \"${workspaceFolder}/.ompa-vault\",\n \"OMPA_ENABLE_SEMANTIC\": \"false\"\n }\n }\n }\n}\n```\n\n### MCP 可用工具\n\n| 工具 | 功能 |\n|------|------|\n| `ao_session_start` | 启动会话并注入记忆上下文 |\n| `ao_classify` | 分类消息并返回路由建议 |\n| `ao_search` | 语义搜索笔记 |\n| `ao_kg_query` | 查询知识图谱实体 |\n| `ao_kg_add` | 添加三元组到知识图谱 |\n| `ao_kg_stats` | 知识图谱统计 |\n| `ao_palace_wings` | 列出所有 Palace 区域 |\n| `ao_palace_rooms` | 列出区域中的房间 |\n| `ao_palace_tunnel` | 创建跨区域通道 |\n| `ao_validate` | 验证笔记结构 |\n| `ao_wrap_up` | 会话总结 |\n| `ao_status` | Vault 健康状态 |\n| `ao_orphans` | 检测孤立笔记 |\n| `ao_init` | 初始化 vault |\n| `ao_sync` | 同步 vault |\n| `ao_write` | 写入笔记 |\n| `ao_export` / `ao_import` | 导入导出笔记 |\n\n> 资料来源：[ompa/mcp_server.py:1-50]()\n\n## 消息分类系统\n\nOMPA 内置 15 种消息类型分类器，可自动将消息路由到正确的 vault 文件夹：\n\n```bash\nao classify \"We decided to go with Postgres\"\n```\n\n分类系统基于正则模式、路由提示和文件夹映射自动工作：\n\n1. 添加枚举值到 `MessageType`\n2. 添加正则模式到 `PATTERNS`\n3. 添加路由提示到 `ROUTING_HINTS`\n4. 添加文件夹映射到 `FOLDER_MAP`\n\n> 资料来源：[CONTRIBUTING.md:25-35]()\n\n## 项目结构\n\n```\nompa/\n├── core.py # Ompa 主类 — 生命周期、钩子、双 Vault\n├── vault.py # Vault CRUD 操作\n├── palace.py # Palace 元数据（区域/房间/抽屉/大厅/通道）\n├── knowledge_graph.py # 时序知识图谱（SQLite 三元组）\n├── hooks.py # 5 个生命周期钩子 + HookManager\n├── classifier.py # 15 种消息类型自动路由\n├── semantic.py # 本地语义搜索（惰性模型加载）\n├── mcp_server.py # MCP 协议服务器（15 个工具）\n├── config.py # 双 Vault 配置\n└── cli.py # Typer CLI（14 个命令）\n```\n\n> 资料来源：[README.md:65-80]()\n\n## 下一步\n\n- 阅读 [CLAUDE.md](https://github.com/jmiaie/ompa/blob/main/CLAUDE.md) 了解架构决策\n- 查看 [STABILITY.md](https://github.com/jmiaie/ompa/blob/main/STABILITY.md) 了解 API 稳定性承诺\n- 参考 [CONTRIBUTING.md](https://github.com/jmiaie/ompa/blob/main/CONTRIBUTING.md) 参与贡献\n\n---\n\n\n\n## 三层架构设计\n\n### 相关页面\n\n相关主题：[生命周期钩子](#lifecycle-hooks), [Vault存储层](#vault), [Palace元数据层](#palace), [时序知识图谱](#knowledge-graph)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [ompa/vault.py](https://github.com/jmiaie/ompa/blob/main/ompa/vault.py)\n- [ompa/palace.py](https://github.com/jmiaie/ompa/blob/main/ompa/palace.py)\n- [ompa/knowledge_graph.py](https://github.com/jmiaie/ompa/blob/main/ompa/knowledge_graph.py)\n- [ompa/core.py](https://github.com/jmiaie/ompa/blob/main/ompa/core.py)\n- [ompa/semantic.py](https://github.com/jmiaie/ompa/blob/main/ompa/semantic.py)\n \n\n# 三层架构设计\n\nOMPA（Obsidian-MemPalace-Agnostic）采用**三层架构设计**，将AI Agent的记忆系统分解为三个职责明确的层次：数据持久层（Vault）、元数据加速层（Palace）和时序推理层（Knowledge Graph）。这种设计遵循\"Vault是事实来源，Palace是检索加速\"的核心原则，实现了数据存储与高效检索的分离。\n\n## 架构概览\n\n```mermaid\ngraph TB\n subgraph 数据层 \"第一层：Vault（数据持久层）\"\n VAULT[\"Vault Manager
brain/work/org/perf\"]\n FILES[\"文件系统
Markdown + Frontmatter\"]\n end\n \n subgraph 加速层 \"第二层：Palace（元数据加速层）\"\n PALACE[\"Palace Manager
wings/rooms/drawers\"]\n INDEX[\"语义索引
sentence-transformers\"]\n end\n \n subgraph 推理层 \"第三层：Knowledge Graph（时序推理层）\"\n KG[\"Knowledge Graph
SQLite Triples\"]\n TEMPORAL[\"时序窗口
valid_from/valid_to\"]\n end\n \n USER[\"> 用户/Agent\"]\n \n USER --> VAULT\n USER --> PALACE\n USER --> KG\n \n VAULT --> FILES\n PALACE --> INDEX\n KG --> TEMPORAL\n \n FILES -.->|\"populate\"| KG\n INDEX -.->|\"辅助\"| PALACE\n```\n\n### 三层职责对照表\n\n| 层次 | 组件 | 职责 | 存储介质 | 数据格式 |\n|------|------|------|----------|----------|\n| 第一层 | Vault | 源数据持久化 | 文件系统 | Markdown + Frontmatter |\n| 第二层 | Palace | 元数据抽象 + 快速检索 | 内存 + 磁盘索引 | wings/rooms/drawers 结构 |\n| 第三层 | Knowledge Graph | 时序关系推理 | SQLite | 三元组 + 时效窗口 |\n\n资料来源：[CLAUDE.md:1-15](https://github.com/jmiaie/ompa/blob/main/CLAUDE.md)\n\n## 第一层：Vault（数据持久层）\n\n### 设计目标\n\nVault层作为整个记忆系统的**事实来源（Source of Truth）**，负责持久化存储所有笔记、文档和元数据。采用原文存储策略（Verbatim Storage），不进行摘要或压缩，以保证最高的信息保真度。MemPalace的研究表明，verbatim存储在LongMemEval基准上达到了96.6%的R@5召回率。\n\n### 目录结构\n\nVault采用四象限组织结构，与obsidian-mind项目的设计保持一致：\n\n```mermaid\ngraph TD\n VAULT[\"Vault Root\"]\n BRAIN[\"brain/
个人思考\"]\n WORK[\"work/
工作项目\"]\n ORG[\"org/
组织信息\"]\n PERF[\"perf/
性能数据\"]\n \n VAULT --> BRAIN\n VAULT --> WORK\n VAULT --> ORG\n VAULT --> PERF\n \n WORK --> ACTIVE[\"active/
活跃项目\"]\n WORK --> ARCHIVE[\"archive/
归档项目\"]\n PERF --> METRICS[\"metrics/
指标\"]\n PERF --> SESSIONS[\"sessions/
会话记录\"]\n```\n\n### 核心功能\n\nVault Manager提供以下核心操作：\n\n| 操作 | 方法 | 说明 |\n|------|------|------|\n| 初始化 | `Vault(vault_path)` | 创建目录结构 |\n| 统计 | `get_stats()` | 返回笔记数量、文件大小等 |\n| 笔记列表 | `list_notes()` | 遍历所有.md文件 |\n| 查找孤立笔记 | `find_orphans()` | 检测broken wikilinks |\n\n资料来源：[ompa/vault.py](https://github.com/jmiaie/ompa/blob/main/ompa/vault.py)\n\n### Frontmatter规范\n\n每条笔记都包含标准化的Frontmatter元数据：\n\n```yaml\n---\ndate: \"2025-06-01\"\ntags: [authentication, postgres, enterprise]\nvault: shared\n---\n```\n\n- `date`：创建或修改日期\n- `tags`：主题标签列表\n- `vault`：所属保险库（shared/personal，用于双库模式）\n\n### 安全机制\n\nVault层实现了完整的路径遍历防护：\n\n```python\ndef _safe_resolve(base: Path, path: str) -> Path:\n \"\"\"解析并边界检查路径\"\"\"\n full_path = (base / path).resolve()\n if not full_path.is_relative_to(base):\n raise ValueError(\"Path traversal detected\")\n return full_path\n```\n\n所有文件操作都必须经过路径解析和边界检查，防止恶意路径注入。\n\n资料来源：[CHANGELOG.md:20-25](https://github.com/jmiaie/ompa/blob/main/CHANGELOG.md)\n\n## 第二层：Palace（元数据加速层）\n\n### 设计目标\n\nPalace层在Vault之上构建元数据抽象，提供高效的导航和检索能力。采用宫殿隐喻（Palace Metaphor），将记忆空间组织为wings（翼）、rooms（房间）、drawers（抽屉）的层级结构，模拟人类记忆宫殿的空间记忆技巧。\n\n### 组织结构\n\n```mermaid\ngraph LR\n WING[\"Wing（翼）
顶级分类\"]\n ROOM[\"Room（房间）
次级分类\"]\n DRAWER[\"Drawer（抽屉）
具体主题\"]\n HALL[\"Hall（大厅）
全局连接\"]\n TUNNEL[\"Tunnel（隧道）
跨翼连接\"]\n \n WING --> ROOM\n ROOM --> DRAWER\n \n HALL -.->|\"全局\"| WING\n TUNNEL -.->|\"跨域\"| WING\n```\n\n### 层级说明\n\n| 层级 | 概念 | 用途 | 示例 |\n|------|------|------|------|\n| Wing | 翼 | 主知识领域 | Orion（猎户座命名） |\n| Room | 房间 | 子主题 | auth、database |\n| Drawer | 抽屉 | 最小单元 | postgres-config |\n| Hall | 大厅 | 全局索引 | 跨wing搜索 |\n| Tunnel | 隧道 | 跨域连接 | auth ↔ billing |\n\n资料来源：[ompa/palace.py](https://github.com/jmiaie/ompa/blob/main/ompa/palace.py)\n\n### Palace Manager API\n\n```python\n# 创建宫殿结构\nao.palace.create_wing(\"Orion\") # 创建翼\nao.palace.create_room(\"Orion\", \"auth\") # 在翼下创建房间\nao.palace.create_tunnel(\"Orion\", \"Gemini\", room=\"shared\") # 跨翼隧道\n\n# 导航查询\nwings = ao.palace.list_wings() # 列出所有翼\nrooms = ao.palace.rooms(\"Orion\") # 列出翼下房间\nstats = ao.palace.stats() # 统计信息\n```\n\n### 语义搜索集成\n\nPalace层与Semantic Index深度集成，提供零API成本的本地语义搜索：\n\n```python\n# Semantic Index延迟加载机制\nclass SemanticIndex:\n _model = None # 首次访问时加载\n \n @property\n def model(self):\n if self._model is None:\n # 首次使用时下载并加载 all-MiniLM-L6-v2 模型\n self._model = load_model()\n return self._model\n```\n\n首次启用语义搜索时自动下载约90MB的句子transformer模型（约500MB包含所有依赖）。\n\n资料来源：[ompa/semantic.py](https://github.com/jmiaie/ompa/blob/main/ompa/semantic.py)\n\n### 增量索引\n\nSemantic Index实现了增量更新机制，只重新索引修改过的文件：\n\n```python\n# 跟踪文件修改时间\nindex_state = {\n \"path/to/note.md\": {\n \"mtime\": 1709234567.123,\n \"embedding\": [...]\n }\n}\n\ndef needs_reindex(file_path, index_state) -> bool:\n \"\"\"检查文件是否需要重新索引\"\"\"\n if file_path not in index_state:\n return True\n return getmtime(file_path) > index_state[file_path][\"mtime\"]\n```\n\n资料来源：[CHANGELOG.md:45-50](https://github.com/jmiaie/ompa/blob/main/CHANGELOG.md)\n\n## 第三层：Knowledge Graph（时序推理层）\n\n### 设计目标\n\nKnowledge Graph层在Vault和Palace之上构建时序知识图谱，存储实体间的三元组关系，并支持时间窗口查询。这使得系统能够回答\"某个决策在特定时间点的状态\"等时序相关问题。\n\n### 数据模型\n\n```mermaid\ngraph LR\n subgraph 三元组结构\n SUBJ[\"Subject
主体实体\"]\n PRED[\"Predicate
关系谓词\"]\n OBJ[\"Object
客体实体\"]\n end\n \n subgraph 时序窗口\n VF[\"valid_from
生效时间\"]\n VT[\"valid_to
失效时间\"]\n end\n \n SUBJ --> PRED\n PRED --> OBJ\n SUBJ --> VF\n SUBJ --> VT\n```\n\n### SQLite存储\n\n所有三元组存储在SQLite数据库中：\n\n```sql\nCREATE TABLE triples (\n id INTEGER PRIMARY KEY,\n subject TEXT NOT NULL,\n predicate TEXT NOT NULL,\n object TEXT NOT NULL,\n valid_from TEXT,\n valid_to TEXT,\n source TEXT,\n created_at TEXT DEFAULT CURRENT_TIMESTAMP\n);\n\nCREATE INDEX idx_subject ON triples(subject);\nCREATE INDEX idx_valid_from ON triples(valid_from);\n```\n\n资料来源：[ompa/knowledge_graph.py](https://github.com/jmiaie/ompa/blob/main/ompa/knowledge_graph.py)\n\n### 核心操作\n\n| 操作 | 方法 | 说明 |\n|------|------|------|\n| 添加三元组 | `add_triple(subject, predicate, object, valid_from, source)` | 插入新关系 |\n| 查询实体 | `query_entity(entity, as_of)` | 获取实体所有关系 |\n| 时间线 | `timeline(entity)` | 实体历史变更 |\n| 统计 | `stats()` | 图谱统计信息 |\n\n### 时序查询示例\n\n```python\n# 添加带时效的三元组\nao.kg.add_triple(\n subject=\"Kai\",\n predicate=\"works_on\",\n object=\"Orion\",\n valid_from=\"2025-06-01\" # 2025年6月1日起生效\n)\n\n# 查询特定时间点的实体状态\ntriples = ao.kg.query_entity(\"Kai\", as_of=\"2025-06-15\")\n\n# 获取完整时间线\ntimeline = ao.kg.timeline(\"Kai\")\n# 返回: [{\"from\": \"2025-01-01\", \"to\": \"2025-05-31\", \"role\": \"lead\"},\n# {\"from\": \"2025-06-01\", \"to\": None, \"role\": \"architect\"}]\n```\n\n### Vault自动填充\n\nKnowledge Graph支持从Vault自动抽取知识：\n\n```python\n# populate_from_vault() 扫描现有笔记\n# 抽取来源包括：\n# 1. Frontmatter tags（如 tags: [auth, postgres]）\n# 2. 文件夹路径结构（如 work/active/auth/ → works_on:auth）\n# 3. Wikilinks（[[Note Name]] → references:Note_Name）\n```\n\n资料来源：[CHANGELOG.md:40-45](https://github.com/jmiaie/ompa/blob/main/CHANGELOG.md)\n\n## 三层协作机制\n\n### 数据流向\n\n```mermaid\nsequenceDiagram\n participant User as 用户/Agent\n participant Core as Ompa Core\n participant Vault as Vault Layer\n participant Palace as Palace Layer\n participant KG as KG Layer\n \n User->>Core: handle_message(\"决策内容\")\n Core->>Vault: 持久化存储\n Vault-->>Core: 保存成功\n Core->>Palace: 分类 + 路由\n Palace-->>Core: 建议文件夹\n Core->>KG: 抽取实体 + 关系\n KG-->>Core: 三元组已添加\n \n User->>Core: search(\"认证决策\")\n Core->>Palace: 语义搜索\n Palace-->>Core: Top-K 结果\n \n User->>Core: kg_query(\"Kai\")\n Core->>KG: 时序查询\n KG-->>Core: 历史状态\n```\n\n### 分类路由流程\n\n消息分类器（Classifier）根据内容类型自动路由到对应文件夹：\n\n| 消息类型 | 正则模式 | 目标文件夹 | 示例 |\n|----------|----------|------------|------|\n| DECISION | `决定\\|决策\\|选择\\|go with` | brain/decisions/ | \"We decided to go with Postgres\" |\n| CODE_CHANGE | `代码变更\\|commit\\|PR` | work/changes/ | \"Added auth middleware\" |\n| BLOCKER | `阻塞\\|卡住\\|blocked` | work/blockers/ | \"Stuck on the API design\" |\n\n资料来源：[ompa/classifier.py](https://github.com/jmiaie/ompa/blob/main/ompa/classifier.py)\n\n### 双库模式协作\n\n在Dual-Vault模式下，三层架构扩展为六层协作：\n\n```mermaid\ngraph TB\n subgraph 共享库 \"Shared Vault\"\n SV[\"Shared Vault\"]\n SP[\"Shared Palace\"]\n SK[\"Shared KG\"]\n end\n \n subgraph 个人库 \"Personal Vault\"\n PV[\"Personal Vault\"]\n PP[\"Personal Palace\"]\n PK[\"Personal KG\"]\n end\n \n subgraph 隔离层 \"Isolation Layer\"\n CONFIG[\"DualVaultConfig\"]\n MODE[\"IsolationMode\"]\n end\n \n CONFIG --> MODE\n MODE -->|\"AUTO\"| SV\n MODE -->|\"AUTO\"| PV\n```\n\n隔离模式说明：\n\n| 模式 | 行为 |\n|------|------|\n| `IsolationMode.AUTO` | 根据消息类型自动分类到shared或personal |\n| `IsolationMode.MANUAL` | 显式指定`VaultTarget`路由 |\n\n资料来源：[ompa/core.py:30-50](https://github.com/jmiaie/ompa/blob/main/ompa/core.py)\n\n## 生命周期钩子\n\n三层架构通过Hooks机制与Agent生命周期集成：\n\n```mermaid\nstateDiagram-v2\n [*] --> session_start: 钩子1\n session_start --> handle_message: 钩子2\n handle_message --> post_tool: 钩子3\n post_tool --> pre_compact: 钩子4\n pre_compact --> stop: 钩子5\n stop --> [*]\n```\n\n### 钩子列表\n\n| 钩子名称 | 时机 | 典型用途 |\n|----------|------|----------|\n| `on_session_start` | 会话开始 | 注入记忆上下文（~2K tokens） |\n| `on_message` | 消息处理 | 分类 + 持久化 |\n| `on_tool_call` | 工具调用 | 记录工具使用历史 |\n| `on_pre_compact` | 压缩前 | 准备会话摘要 |\n| `on_stop` | 会话结束 | 保存状态 + 更新索引 |\n\n资料来源：[ompa/hooks.py](https://github.com/jmiaie/ompa/blob/main/ompa/hooks.py)\n\n## 性能优化策略\n\n### 懒加载模式\n\n| 组件 | 懒加载策略 | 触发条件 |\n|------|------------|----------|\n| Semantic Model | `_model = None` | 首次search调用 |\n| KG Connection | `with sqlite3.connect()` | 每次查询 |\n| Palace Index | `incremental_reindex()` | 文件修改检测 |\n\n### 并发安全\n\nVault层在v0.3.1版本后支持并发访问：\n- SQLite连接使用context manager自动释放\n- 文件操作使用原子写入（write + rename）\n- UTF-8编码显式指定\n\n### 缓存策略\n\n```python\n# 内存缓存层\nclass Ompa:\n _wings_cache: list | None = None\n _stats_cache: dict | None = None\n \n def list_wings(self, use_cache=True):\n if use_cache and self._wings_cache:\n return self._wings_cache\n self._wings_cache = self.palace.list_wings()\n return self._wings_cache\n```\n\n## 总结\n\nOMPA的三层架构设计体现了现代AI Agent记忆系统的核心设计原则：\n\n1. **分层职责分离**：每层专注于特定职责，便于独立演进\n2. **原文优先**：Vault层不压缩、不摘要，保证信息完整性\n3. **时序感知**：KG层支持时间窗口查询，实现状态回溯\n4. **本地优先**：语义搜索完全在本地运行，零API成本\n5. **安全加固**：路径遍历防护、UTF-8显式编码、原子写入\n\n这种架构使得OMPA能够同时满足个人知识管理和团队协作的需求，通过双库模式实现隐私隔离与知识共享的平衡。\n\n---\n\n\n\n## 生命周期钩子\n\n### 相关页面\n\n相关主题：[三层架构设计](#three-layer-design), [消息分类器](#classifier)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [ompa/hooks.py](https://github.com/jmiaie/ompa/blob/main/ompa/hooks.py)\n- [ompa/core.py](https://github.com/jmiaie/ompa/blob/main/ompa/core.py)\n- [CONTRIBUTING.md](https://github.com/jmiaie/ompa/blob/main/CONTRIBUTING.md)\n- [STABILITY.md](https://github.com/jmiaie/ompa/blob/main/STABILITY.md)\n- [CLAUDE.md](https://github.com/jmiaie/ompa/blob/main/CLAUDE.md)\n \n\n# 生命周期钩子\n\nOMPA 的生命周期钩子系统允许开发者在会话关键节点插入自定义逻辑，实现消息处理、工具调用和会话收尾等流程的扩展与定制。\n\n## 核心概念\n\nOMPA 定义了 5 个生命周期钩子点，分别对应会话的不同阶段：\n\n| 钩子名称 | 触发时机 | 返回类型 |\n|---------|---------|---------|\n| `session_start` | 会话初始化时 | `HookResult` |\n| `handle_message` | 每条消息处理时 | `HookResult` |\n| `post_tool` | 工具调用完成后 | `HookResult` |\n| `pre_compact` | 上下文压缩前 | `HookResult` |\n| `stop` / `wrap_up` | 会话结束时 | `HookResult` |\n\n## 系统架构\n\n```mermaid\ngraph TD\n A[Ompa 实例] --> B[HookManager]\n B --> C[Hook 1]\n B --> D[Hook 2]\n B --> E[Hook N]\n \n F[触发时机] --> G[session_start]\n F --> H[handle_message]\n F --> I[post_tool]\n F --> J[pre_compact]\n F --> K[stop]\n \n G --> B\n H --> B\n I --> B\n J --> B\n K --> B\n```\n\n## 核心类\n\n### Hook 基类\n\n所有自定义钩子需继承 `Hook` 基类：\n\n```python\nfrom ompa.hooks import Hook, HookContext, HookResult\n\nclass MyHook(Hook):\n def __init__(self):\n super().__init__(\"my_hook\", token_budget=50)\n\n def execute(self, context: HookContext, **kwargs) -> HookResult:\n return HookResult(\n hook_name=self.name,\n success=True,\n output=\"...\",\n tokens_hint=50\n )\n```\n\n构造函数参数：\n| 参数 | 类型 | 说明 |\n|-----|------|-----|\n| `name` | `str` | 钩子唯一标识名 |\n| `token_budget` | `int` | 该钩子预计消耗的 token 上限 |\n\n### HookContext\n\n传递给钩子执行器的上下文对象，包含当前会话状态信息。\n\n### HookResult\n\n钩子执行结果的返回结构：\n\n| 字段 | 类型 | 说明 |\n|-----|------|-----|\n| `hook_name` | `str` | 执行钩子的名称 |\n| `success` | `bool` | 执行是否成功 |\n| `output` | `str` | 钩子输出内容 |\n| `tokens_hint` | `int` | 预估 token 消耗 |\n| `error` | `str` | 错误信息（可选） |\n\n## HookManager\n\n`HookManager` 负责管理所有已注册的钩子实例，提供注册和执行接口。\n\n```python\nfrom ompa.hooks import HookManager\n\n# 获取 HookManager 实例\nhook_manager = ao.hooks\nhook_manager.register_hook(\"my_hook\", MyHook())\n```\n\n## 注册自定义钩子\n\n```python\nfrom ompa import Ompa\nfrom ompa.hooks import Hook, HookContext, HookResult\n\nclass LoggingHook(Hook):\n def __init__(self):\n super().__init__(\"logging_hook\", token_budget=10)\n\n def execute(self, context: HookContext, **kwargs) -> HookResult:\n message = kwargs.get(\"message\", \"\")\n print(f\"[LOG] Processing: {message[:50]}\")\n return HookResult(\n hook_name=self.name,\n success=True,\n output=\"Logged successfully\",\n tokens_hint=10\n )\n\n# 创建实例并注册钩子\nao = Ompa(\"./workspace\")\nao.hooks.register_hook(\"logging\", LoggingHook())\n```\n\n## 钩子执行流程\n\n```mermaid\nsequenceDiagram\n participant User as 用户代码\n participant Ompa as Ompa 实例\n participant HM as HookManager\n participant Hook as 自定义钩子\n \n User->>Ompa: session_start() / handle_message()\n Ompa->>HM: 执行钩子链\n HM->>Hook: execute(context, **kwargs)\n Hook-->>HM: HookResult\n HM-->>Ompa: 聚合结果\n Ompa-->>User: HookResult\n```\n\n## 与 Ompa 核心集成\n\n`Ompa` 类的公共 API 均返回 `HookResult`：\n\n```python\nfrom ompa import Ompa\n\nao = Ompa(vault_path=\"./workspace\")\n\n# 所有方法返回 HookResult\ncontext = ao.session_start() # HookResult\nresult = ao.handle_message(\"msg\") # HookResult\nresult = ao.post_tool(\"write\", {\"file_path\": \"test.md\"}) # HookResult\nresult = ao.pre_compact(transcript) # HookResult\nao.stop() # HookResult\nao.wrap_up() # HookResult (stop 的别名)\nao.standup() # HookResult (session_start 的别名)\n```\n\n## 完整示例\n\n```python\nfrom ompa import Ompa\nfrom ompa.hooks import Hook, HookContext, HookResult\nimport time\n\nclass TimingHook(Hook):\n def __init__(self):\n super().__init__(\"timing\", token_budget=5)\n self.start_time = None\n\n def execute(self, context: HookContext, **kwargs) -> HookResult:\n if self.start_time is None:\n self.start_time = time.time()\n msg = \"Timer started\"\n else:\n elapsed = time.time() - self.start_time\n msg = f\"Session duration: {elapsed:.1f}s\"\n return HookResult(\n hook_name=self.name,\n success=True,\n output=msg,\n tokens_hint=5\n )\n\n# 使用\nao = Ompa(\"./workspace\")\nao.hooks.register_hook(\"timing\", TimingHook())\n\nao.session_start()\n# ... 会话操作 ...\nao.wrap_up()\n```\n\n## 注意事项\n\n1. **token_budget 建议值**：每个钩子的 `token_budget` 用于上下文管理规划，建议设置实际消耗的近似值\n2. **异常处理**：钩子执行失败时返回 `success=False`，但不会中断主流程\n3. **返回值聚合**：`HookManager` 会聚合多个钩子的结果\n4. **注册时机**：建议在 `Ompa` 实例创建后立即注册钩子\n\n## 稳定性说明\n\n> `ompa.hooks.*Hook` 类为内部实现类，可能在次版本中变更。建议使用 `HookManager.register_hook()` 接口进行注册 资料来源：[STABILITY.md]()\n\n## 相关文件\n\n| 文件 | 说明 |\n|-----|------|\n| `ompa/hooks.py` | 钩子系统核心实现 |\n| `ompa/core.py` | `Ompa` 主类与钩子集成 |\n| `CONTRIBUTING.md` | 自定义钩子开发指南 |\n\n---\n\n\n\n## Vault存储层\n\n### 相关页面\n\n相关主题：[三层架构设计](#three-layer-design), [消息分类器](#classifier)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [ompa/vault.py](https://github.com/jmiaie/ompa/blob/main/ompa/vault.py)\n- [ompa/core.py](https://github.com/jmiaie/ompa/blob/main/ompa/core.py)\n- [ompa/config.py](https://github.com/jmiaie/ompa/blob/main/ompa/config.py)\n- [ompa/knowledge_graph.py](https://github.com/jmiaie/ompa/blob/main/ompa/knowledge_graph.py)\n- [ompa/semantic.py](https://github.com/jmiaie/ompa/blob/main/ompa/semantic.py)\n- [CLAUDE.md](https://github.com/jmiaie/ompa/blob/main/CLAUDE.md)\n- [SECURITY_AUDIT.md](https://github.com/jmiaie/ompa/blob/main/SECURITY_AUDIT.md)\n- [CHANGELOG.md](https://github.com/jmiaie/ompa/blob/main/CHANGELOG.md)\n \n\n# Vault存储层\n\nVault存储层是OMPA系统的核心数据持久化组件，负责管理所有笔记、文件、元数据和知识图谱的本地存储。作为系统的\"事实来源（Source of Truth）\"，Vault层采用了严格的安全防护机制和双保险库架构，为AI Agent提供可靠、可隔离的长期记忆存储。\n\n## 核心职责\n\nVault存储层承担以下核心职责：\n\n| 职责类别 | 具体功能 |\n|---------|---------|\n| 文件管理 | 笔记的创建、读取、更新、删除（CRUD操作） |\n| 结构组织 | 按消息类型分类笔记（brain/work/org/perf等） |\n| 安全防护 | 路径遍历攻击防护、UTF-8编码强制 |\n| 双保险库 | 共享库与个人库的隔离管理 |\n| 语义索引 | 文件修改时间跟踪与增量嵌入 |\n| 元数据管理 | Frontmatter解析与存储 |\n\n> 资料来源：[CLAUDE.md:7]()\n\n## 架构设计\n\n### 双层存储架构\n\nOMPA采用Vault + Palace的双层存储架构：\n\n- **Vault层**：数据的唯一事实来源，负责原始笔记和文件的持久化存储\n- **Palace层**：作为检索加速层，提供宫殿式记忆结构（wings/rooms/drawers/halls/tunnels）来优化信息检索效率\n\n```mermaid\ngraph TD\n A[用户/Agent] --> B[Ompa Core API]\n B --> C{Mode选择}\n C -->|单库模式| D[Vault单实例]\n C -->|双库模式| E[Shared Vault]\n C -->|双库模式| F[Personal Vault]\n D --> G[文件系统]\n E --> H[文件系统 - 共享区域]\n F --> I[文件系统 - 个人区域]\n G --> J[.palace/ 目录结构]\n H --> J\n I --> J\n J --> K[Knowledge Graph SQLite]\n J --> L[Semantic Index]\n```\n\n> 资料来源：[CLAUDE.md:7](), [README.md:Package Structure]()\n\n### 双保险库架构（Dual-Vault）\n\n从v0.4.0开始，OMPA支持双保险库架构，允许在共享保险库和个人保险库之间隔离数据：\n\n```python\nfrom ompa import Ompa, DualVaultConfig, IsolationMode\n\nconfig = DualVaultConfig(\n shared_vault=\"./team-vault\",\n personal_vault=\"./private-vault\",\n mode=IsolationMode.AUTO, # 或 IsolationMode.MANUAL\n)\nao = Ompa(config=config)\n```\n\n#### 隔离模式\n\n| 模式 | 行为描述 |\n|------|---------|\n| `IsolationMode.AUTO` | 根据消息类型自动分类，团队消息进入共享库，个人消息进入个人库 |\n| `IsolationMode.MANUAL` | 通过显式`VaultTarget`参数路由每个操作 |\n| `IsolationMode.STRICT` | 严格模式，阻止跨库操作 |\n\n> 资料来源：[STABILITY.md:30-35](), [CHANGELOG.md:0.4.0](), [README.md:Dual-Vault Mode]()\n\n#### 导出时的敏感信息清理\n\n在将个人保险库笔记导出到共享库时，`Ompa._sanitize_content()`方法会自动清理以下敏感信息：\n\n- `sk-*`（OpenAI风格API密钥）\n- `AKIA*`（AWS访问密钥ID）\n- `token:`、`password:`、`secret:`、`api_key:`、`api-key:`等敏感字段\n\n> 资料来源：[SECURITY_AUDIT.md:credential-sanitization]()\n\n## 安全机制\n\n### 路径遍历防护\n\nVault层实现了严格的路径遍历攻击防护，所有文件操作都通过`_safe_resolve`函数进行路径解析和边界检查：\n\n```mermaid\ngraph TD\n A[用户请求路径] --> B[_safe_resolve调用]\n B --> C[Path.resolve 规范化]\n C --> D{路径是否在vault_root内?}\n D -->|是| E[允许访问]\n D -->|否| F[Raise ValueError]\n E --> G[执行文件操作]\n```\n\n路径遍历防护的关键实现：\n\n- 使用`Path.resolve()`将所有路径规范化为绝对路径\n- 在操作前检查路径是否在保险库根目录内\n- 任何尝试逃逸保险库根目录的操作都会被拒绝并抛出异常\n- Brain note名称中包含路径分隔符的请求在API边界处被拒绝\n\n> 资料来源：[SECURITY_AUDIT.md:path-traversal-protection](), [CHANGELOG.md:0.4.1-path-traversal]()\n\n### UTF-8编码强制\n\n从v0.4.0开始，所有vault文件写入操作都强制使用UTF-8编码：\n\n> 资料来源：[CHANGELOG.md:0.4.0](), [README.md:utf-8-enforcement]()\n\n### 并发访问支持\n\nVault层的笔记CRUD操作支持并发访问，通过以下机制确保数据一致性：\n\n- 原子文件写入操作\n- 修改时间跟踪用于增量更新\n- SemanticIndex使用文件修改时间判断是否需要重新嵌入\n\n> 资料来源：[CHANGELOG.md:0.4.0-concurrent-access]()\n\n## 目录结构\n\n### 标准Vault布局\n\n```\nvault-root/\n├── brain/ # Brain笔记（个人想法、反思）\n│ ├── reflections/\n│ └── insights/\n├── work/ # 工作相关笔记\n├── org/ # 组织/团队知识\n├── perf/ # 性能相关记录\n├── .palace/ # Palace元数据目录\n│ ├── wings.json\n│ ├── rooms.json\n│ ├── kg.db # Knowledge Graph数据库\n│ └── index/ # 语义索引目录\n└── .ompa/ # OMPA内部配置\n```\n\n### Frontmatter格式\n\n每篇笔记都包含YAML frontmatter元数据：\n\n```yaml\n---\ndate: 2025-06-01\ntags: [authentication, postgres, decision]\nvault: shared # 或 personal\n---\n```\n\n> 资料来源：[core.py:frontmatter-示例](), [SECURITY_AUDIT.md:export-sanitization]()\n\n## 笔记分类与路由\n\n### 消息类型分类\n\nVault层根据消息类型将笔记路由到对应文件夹：\n\n| 消息类型 | 目标文件夹 | 说明 |\n|---------|----------|------|\n| DECISION | work/decisions/ | 决策记录 |\n| INCIDENT | brain/incidents/ | 事件记录 |\n| WIN | brain/wins/ | 成功案例 |\n| CONCERN | brain/concerns/ | 问题关注 |\n| REFLECTION | brain/reflections/ | 个人反思 |\n| WORK | work/ | 工作相关 |\n| ORG | org/ | 组织知识 |\n| ... | ... | 其他类型 |\n\n> 资料来源：[core.py:classification-routing](), [CONTRIBUTING.md:adding-message-type]()\n\n### 分类流程\n\n```mermaid\ngraph TD\n A[输入消息] --> B[Classifier.classify]\n B --> C[确定消息类型]\n C --> D[获取routing_hint]\n D --> E[确定目标文件夹]\n E --> F{IsolationMode}\n F -->|AUTO| G[根据消息类型自动选择vault]\n F -->|MANUAL| H[使用显式VaultTarget]\n G --> I[生成安全文件名]\n H --> I\n I --> J[构建完整路径]\n J --> K[_safe_resolve验证]\n K --> L[写入Note]\n```\n\n> 资料来源：[core.py:dual-vault-routing](), [classifier.py:classification-logic]()\n\n## 与其他模块的交互\n\n### 与Knowledge Graph的集成\n\nVault层扫描笔记中的以下内容来填充知识图谱：\n\n- Frontmatter中的tags\n- 文件夹路径结构\n- Wikilink引用（`[[Note Name]]`）\n\n```python\n# 通过KnowledgeGraph.populate_from_vault()实现\nkg = KnowledgeGraph(db_path)\nkg.populate_from_vault(vault_path)\n```\n\n> 资料来源：[CHANGELOG.md:0.3.0-auto-populate-kg]()\n\n### 与SemanticIndex的集成\n\nSemanticIndex组件跟踪文件修改时间，仅对更改过的文件重新生成嵌入向量：\n\n- 首次运行时生成完整索引\n- 后续运行仅处理修改时间变更的文件\n- 索引存储在`.palace/index/`目录\n\n> 资料来源：[CHANGELOG.md:0.3.0-incremental-semantic]()\n\n### 与MCP Server的集成\n\nMCP Server通过以下工具暴露Vault功能：\n\n| MCP工具 | 功能 |\n|--------|------|\n| `ao_init` | 初始化新vault |\n| `ao_status` | 健康检查与统计 |\n| `ao_write` | 写入笔记 |\n| `ao_export` | 导出笔记 |\n| `ao_import` | 导入笔记 |\n| `ao_orphans` | 检测孤儿笔记 |\n\n> 资料来源：[mcp_server.py:tool-handlers](), [CLAUDE.md:mcp-tools]()\n\n## 配置选项\n\n### 环境变量\n\n| 变量名 | 默认值 | 说明 |\n|-------|-------|------|\n| `OMPA_VAULT_PATH` | `.` | Vault根目录绝对路径 |\n| `OMPA_SHARED_VAULT` | — | 共享vault路径（双库模式） |\n| `OMPA_PERSONAL_VAULT` | — | 个人vault路径（双库模式） |\n| `OMPA_ISOLATION_MODE` | `strict` | 隔离模式 |\n| `OMPA_ENABLE_SEMANTIC` | `false` | 启用本地语义搜索 |\n\n> 资料来源：[examples/mcp_desktop/README.md:environment-variables]()\n\n### DualVaultConfig配置\n\n```python\n@dataclass\nclass DualVaultConfig:\n shared_vault: str # 共享vault路径\n personal_vault: str # 个人vault路径\n isolation_mode: IsolationMode # AUTO | STRICT | MANUAL\n default_vault: VaultTarget # MANUAL模式的默认目标\n```\n\n> 资料来源：[config.py:DualVaultConfig](), [STABILITY.md:core-class-config]()\n\n## 版本历史关键变更\n\n| 版本 | 日期 | 关键变更 |\n|-----|------|---------|\n| 0.4.1 | 2026-04-11 | 路径遍历加固、语义索引延迟加载、brain note名称验证 |\n| 0.4.0 | 2026-04-10 | 双保险库架构、并发CRUD、UTF-8强制编码 |\n| 0.3.1 | 2026-04-09 | 孤儿笔记检测修复、wikilink大小写不敏感解析 |\n| 0.3.0 | 2026-04-08 | 自动从vault填充KG、增量语义索引 |\n\n> 资料来源：[CHANGELOG.md:完整历史]()\n\n## 使用示例\n\n### Python API基本用法\n\n```python\nfrom ompa import Ompa\n\n# 单库模式\nao = Ompa(vault_path=\"./workspace\")\n\n# 双库模式\nfrom ompa import DualVaultConfig, IsolationMode\nconfig = DualVaultConfig(\n shared_vault=\"./team-vault\",\n personal_vault=\"./private-vault\",\n mode=IsolationMode.AUTO,\n)\nao = Ompa(config=config)\n\n# 创建笔记\nresult = ao.handle_message(\"We decided to go with Postgres for the auth service\")\n```\n\n### CLI命令\n\n```bash\nao init # 初始化新vault\nao status # 健康检查\nao orphans # 检测孤儿笔记\nao validate # 验证vault结构\n```\n\n> 资料来源：[README.md:CLI-Reference](), [README.md:Python-API]()\n\n## 内部实现注意事项\n\n以下为内部实现细节，可能会在次要版本中变更：\n\n- `ompa.vault.DEFAULT_EXCLUDE_PATTERNS`\n- `ompa.vault._safe_resolve`\n- 内部vault文件布局（`.palace/`结构）\n\n> 资料来源：[STABILITY.md:not-stable-items]()\n\n## 安全审计结果\n\nVault存储层已完成全面安全审计，评级为8/10（满分10分）：\n\n- **通过项**：路径遍历防护、SQL注入预防、凭证清理、UTF-8编码强制\n- **可接受项**：2个低严重性bandit发现（git子进程使用，已接受）\n\n> 资料来源：[SECURITY_AUDIT.md:full-audit](), [CHANGELOG.md:0.4.1-security](), [CHANGELOG.md:0.4.1-tests]()\n\n---\n\n\n\n## Palace元数据层\n\n### 相关页面\n\n相关主题：[三层架构设计](#three-layer-design), [Vault存储层](#vault)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [ompa/palace.py](https://github.com/jmiaie/ompa/blob/main/ompa/palace.py)\n- [ompa/core.py](https://github.com/jmiaie/ompa/blob/main/ompa/core.py)\n- [ompa/mcp_server.py](https://github.com/jmiaie/ompa/blob/main/ompa/mcp_server.py)\n- [ompa/classifier.py](https://github.com/jmiaie/ompa/blob/main/ompa/classifier.py)\n- [CLAUDE.md](https://github.com/jmiaie/ompa/blob/main/CLAUDE.md)\n- [README.md](https://github.com/jmiaie/ompa/blob/main/README.md)\n \n\n# Palace元数据层\n\n## 概述\n\nPalace（宫殿）是 OMPA 项目中的**元数据加速层**，与 Vault（存储层）共同构成双层检索架构的核心组成部分。Vault 作为事实来源（source of truth）存储所有笔记内容，而 Palace 则提供结构化的元数据组织和高效的路径导航能力。\n\n资料来源：[CLAUDE.md]()\n\n### 设计理念\n\nPalace 借鉴了\"记忆宫殿\"（Method of Loci）的隐喻，将笔记组织为层级化的空间结构：\n\n- **Wing（翼）**：顶级分类，对应组织或项目维度\n- **Room（房间）**：二级分类，对应具体主题或功能领域\n- **Drawer（抽屉）**：三级分类，可选，用于更细粒度的组织\n- **Hall（大厅）**：跨房间的聚合视图\n- **Tunnel（隧道）**：跨翼的连接路径，用于关联不同领域的笔记\n\n这种设计使得 AI Agent 能够通过空间化的方式\"导航\"和\"穿越\"记忆结构，而非简单的关键词搜索。\n\n资料来源：[README.md]()\n\n## 架构设计\n\n### 双层架构\n\nOMPA 采用 **Vault + Palace** 双层架构：\n\n```mermaid\ngraph TD\n A[用户消息] --> B[Classifier 分类器]\n B --> C{Vault 或 Palace?}\n C -->|检索加速| D[Palace 元数据层]\n C -->|原始内容| E[Vault 存储层]\n D --> F[Wings / Rooms / Tunnels]\n E --> G[Markdown 文件 / 语义索引]\n```\n\n资料来源：[CLAUDE.md]()\n\n### Palace 核心职责\n\n| 职责 | 描述 |\n|------|------|\n| 元数据管理 | 维护 Wing/Room/Drawer/Hall/Tunnel 的索引结构 |\n| 路径导航 | 提供笔记的层级路径解析和关联查询 |\n| 跨域连接 | 创建 Tunnel 实现跨 Wing 的语义关联 |\n| 统计信息 | 提供 Palace 内各层级元素的数量和状态 |\n\n资料来源：[ompa/core.py]()\n\n## 核心概念\n\n### Wing（翼）\n\nWing 是 Palace 的顶级组织单元，通常对应一个大的主题领域或组织单元。\n\n**特性**：\n- 每个 Wing 拥有唯一的名称标识\n- Wing 下可包含多个 Room\n- 支持创建 Tunnel 连接不同 Wing\n\n```python\n# 通过 Python API 创建 Wing\nao.palace.create_wing(\"Orion\")\n```\n\n**MCP 工具**：`ao_palace_wings` — 列出所有 palace wings\n\n资料来源：[ompa/mcp_server.py](), [README.md]()\n\n### Room（房间）\n\nRoom 是 Wing 下的二级组织单元，用于更精细的主题划分。\n\n**特性**：\n- 必须隶属于某个 Wing\n- 可通过 Tunnel 与其他 Wing 的 Room 建立连接\n- 支持统计该 Wing 下的所有 Room\n\n```python\n# 通过 Python API 列出房间\nrooms = ao.palace.list_rooms(\"Orion\")\n```\n\n**MCP 工具**：`ao_palace_rooms` — 列出指定 Wing 下的所有房间\n\n资料来源：[ompa/mcp_server.py](), [README.md]()\n\n### Tunnel（隧道）\n\nTunnel 用于建立跨 Wing 的语义连接，实现不同领域知识之间的关联。\n\n**使用场景**：\n- 跨项目依赖关系的可视化\n- 相关但分属不同领域的笔记关联\n- 迁移路径的追踪（如身份认证迁移）\n\n```python\n# 创建跨 Wing 隧道\nao.palace.create_tunnel(\"Kai\", \"Orion\", \"auth-migration\")\n```\n\n**返回结果示例**：\n```json\n{\"success\": true, \"tunnel\": \"Kai <-> Orion via auth-migration\"}\n```\n\n**MCP 工具**：`ao_palace_tunnel` — 在两个 Wing 之间创建隧道\n\n资料来源：[ompa/mcp_server.py](), [README.md]()\n\n### Hall（大厅）\n\nHall 提供跨房间的聚合视图，允许用户在不限定特定 Room 的情况下进行检索。\n\n```mermaid\ngraph LR\n A[Hall] -->|聚合| B[Room A]\n A -->|聚合| C[Room B]\n A -->|聚合| D[Room C]\n```\n\n### Drawer（抽屉）\n\nDrawer 是可选的三级组织单元，提供更细粒度的分类能力。\n\n## API 参考\n\n### Python API\n\n```python\nfrom ompa import Ompa\n\nao = Ompa(vault_path=\"./workspace\")\n\n# 列出所有 Wings\nwings = ao.palace.list_wings()\n\n# 列出指定 Wing 下的 Rooms\nrooms = ao.palace.list_rooms(\"Orion\")\n\n# 创建 Tunnel\nao.palace.create_tunnel(\"Wing-A\", \"Wing-B\", \"room-name\")\n\n# 获取 Palace 统计信息\nstats = ao.palace.stats()\n```\n\n资料来源：[README.md](), [ompa/core.py]()\n\n### MCP Server 工具\n\n| 工具名 | 功能 | 参数 |\n|--------|------|------|\n| `ao_palace_wings` | 列出所有 Palace Wings | `vault_path` |\n| `ao_palace_rooms` | 列出指定 Wing 下的 Rooms | `wing`, `vault_path` |\n| `ao_palace_tunnel` | 创建跨 Wing 隧道 | `wing_a`, `wing_b`, `room`, `vault_path` |\n\n资料来源：[ompa/mcp_server.py](), [CLAUDE.md]()\n\n### CLI 命令\n\n| 命令 | 功能 |\n|------|------|\n| `ao wings` | 列出 Palace Wings |\n| `ao rooms ` | 列出指定 Wing 下的 Rooms |\n| `ao tunnel` | 创建或遍历跨 Wing 隧道 |\n\n资料来源：[README.md]()\n\n## Palace 与 Vault 的协同\n\n### 消息类型路由\n\nClassifier 根据消息内容自动分类，并将笔记路由到合适的 Vault 文件夹。Palace 则维护这些笔记的元数据索引。\n\n```mermaid\nsequenceDiagram\n participant User as 用户\n participant Core as Ompa Core\n participant Classifier as Classifier\n participant Palace as Palace\n participant Vault as Vault\n \n User->>Core: handle_message(msg)\n Core->>Classifier: classify(msg)\n Classifier-->>Core: MessageType + Folder\n Core->>Vault: write_note(folder, content)\n Core->>Palace: update_metadata(path, type)\n```\n\n资料来源：[ompa/core.py](), [ompa/classifier.py]()\n\n### 双重隔离模式\n\n在 Dual-Vault 架构下，Palace 支持按 Vault Target（shared/personal）进行元数据隔离：\n\n```python\nfrom ompa import Ompa, DualVaultConfig, IsolationMode\n\nconfig = DualVaultConfig(\n shared_vault=\"./team-vault\",\n personal_vault=\"./private-vault\",\n mode=IsolationMode.AUTO,\n)\nao = Ompa(config=config)\n```\n\nPalace 会根据 `IsolationMode` 自动将元数据写入对应的 Palace 实例。\n\n资料来源：[ompa/core.py](), [README.md]()\n\n## 配置与初始化\n\n### 环境变量\n\n| 变量 | 默认值 | 说明 |\n|------|--------|------|\n| `OMPA_VAULT_PATH` | `.` | Vault 根路径 |\n| `OMPA_ENABLE_SEMANTIC` | `false` | 启用本地语义搜索 |\n\nPalace 本身不直接使用环境变量配置，其结构由 Vault 内容动态构建。\n\n### Vault 初始化\n\n```bash\n# 初始化 Vault 结构（Palace 随之创建）\nao init\n\n# 检查状态\nao status\n```\n\n初始化后，Palace 将扫描 Vault 内容并建立初始元数据索引。\n\n资料来源：[README.md](), [CLAUDE.md]()\n\n## 使用示例\n\n### 场景：组织身份认证笔记\n\n```python\nfrom ompa import Ompa\n\nao = Ompa(vault_path=\"./workspace\")\n\n# 1. 创建组织 Wing\nao.palace.create_wing(\"Orion\")\n\n# 2. 在 Wing 下创建房间\n# （通过 Tunnel 连接不同领域的认证笔记）\n\n# 3. 创建跨域 Tunnel\nao.palace.create_tunnel(\"Kai\", \"Orion\", \"auth-migration\")\n\n# 4. 查询 Palace 统计\nstats = ao.palace.stats()\nprint(f\"Wings: {stats['wings']}\")\n```\n\n### 场景：通过 MCP 进行跨域检索\n\n```bash\n# 列出所有 Wings\nclaude mcp run ompa ao_palace_wings\n\n# 列出 Orion Wing 下的所有 Rooms\nclaude mcp run ompa ao_palace_rooms wing=Orion\n\n# 创建 Tunnel\nclaude mcp run ompa ao_palace_tunnel wing_a=Kai wing_b=Orion room=shared\n```\n\n资料来源：[README.md](), [examples/mcp_desktop/README.md]()\n\n## 扩展 Palace\n\n### 添加新概念\n\n如需扩展 Palace 的组织层级（如添加 Floor/Building），需要在以下位置进行修改：\n\n1. `ompa/palace.py` — 添加新的数据结构和操作方法\n2. `ompa/mcp_server.py` — 添加对应的 MCP 工具\n3. `ompa/cli.py` — 添加 CLI 命令\n4. 更新文档和测试\n\n### 自定义 Hook\n\nPalace 支持通过 Hook 系统进行扩展：\n\n```python\nfrom ompa.hooks import Hook, HookContext, HookResult\n\nclass PalaceMetadataHook(Hook):\n def on_note_create(self, ctx: HookContext) -> HookResult:\n # 自定义元数据更新逻辑\n return HookResult(success=True)\n```\n\n资料来源：[CLAUDE.md]()\n\n## 总结\n\nPalace 元数据层是 OMPA 项目中实现\"空间化记忆\"的核心组件。它通过层级化的组织结构（Wing → Room → Drawer）和跨域连接机制（Tunnel），为 AI Agent 提供了结构化的知识导航能力。与 Vault 的双层架构设计，使得 OMPA 能够在保持内容完整性的同时，提供高效的可检索性。\n\n**关键特性**：\n\n- ✅ 层级化的元数据组织（Wing/Room/Drawer/Hall/Tunnel）\n- ✅ 跨域 Tunnel 连接不同知识领域\n- ✅ 与 Vault 双层协同，Vault 为事实来源，Palace 为检索加速\n- ✅ 支持 Dual-Vault 隔离模式\n- ✅ 提供 Python API、MCP 工具和 CLI 三种交互方式\n\n---\n\n\n\n## 时序知识图谱\n\n### 相关页面\n\n相关主题：[三层架构设计](#three-layer-design), [Palace元数据层](#palace)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [ompa/knowledge_graph.py](https://github.com/jmiaie/ompa/blob/main/ompa/knowledge_graph.py)\n- [ompa/mcp_server.py](https://github.com/jmiaie/ompa/blob/main/ompa/mcp_server.py)\n- [ompa/core.py](https://github.com/jmiaie/ompa/blob/main/ompa/core.py)\n- [CHANGELOG.md](https://github.com/jmiaie/ompa/blob/main/CHANGELOG.md)\n- [README.md](https://github.com/jmiaie/ompa/blob/main/README.md)\n- [STABILITY.md](https://github.com/jmiaie/ompa/blob/main/STABILITY.md)\n \n\n# 时序知识图谱\n\n## 概述\n\n时序知识图谱（Temporal Knowledge Graph）是 OMPA 项目的核心组件之一，用于存储和管理具有时间维度的事实三元组。与传统知识图谱不同，时序知识图谱为每个三元组关联了有效性时间窗口，使系统能够查询任意时间点的实体状态变化历史。\n\n时序知识图谱基于 SQLite 实现，采用三重存储（Triple Store）模式，支持以下核心功能：\n\n- 三元组（Subject-Predicate-Object）的增删改查\n- 实体历史时间线查询\n- 从 Vault 自动填充知识图谱\n- 基于时间窗口的有效性过滤\n\n资料来源：[README.md](https://github.com/jmiaie/ompa/blob/main/README.md)\n\n## 架构设计\n\n### 核心概念\n\n| 概念 | 描述 |\n|------|------|\n| 三元组（Triple） | 表示 (主体, 谓词, 客体) 的知识单元 |\n| 主体（Subject） | 实体的标识符，如 \"Kai\" |\n| 谓词（Predicate） | 关系类型，如 \"works_on\"、\"knows\" |\n| 客体（Object） | 关系的目标实体或值 |\n| 有效起始时间（valid_from） | 三元组开始生效的时间点 |\n| 有效结束时间（valid_to） | 三元组失效的时间点（可选） |\n| 来源（source） | 三元组的来源标注 |\n\n### 数据模型\n\n时序知识图谱使用 SQLite 数据库存储三重数据，每个三元组包含以下字段：\n\n```mermaid\nerDiagram\n TRIPLES {\n int id PK\n text subject\n text predicate\n text object\n text valid_from\n text valid_to\n text source\n text vault_path\n }\n```\n\n资料来源：[ompa/knowledge_graph.py](https://github.com/jmiaie/ompa/blob/main/ompa/knowledge_graph.py)\n\n### 双重 Vault 与知识图谱的关系\n\n```mermaid\ngraph TD\n A[Ompa 主类] --> B[时序知识图谱]\n A --> C[Shared Vault]\n A --> D[Personal Vault]\n B -.-> E[Shared KG 查询]\n B -.-> F[Personal KG 查询]\n C --> G[brain/ 组织笔记]\n D --> H[个人笔记]\n G -.-> B\n H -.-> B\n```\n\n知识图谱的数据来源可以是共享 Vault 或个人 Vault，具体取决于隔离模式配置。\n\n资料来源：[ompa/core.py](https://github.com/jmiaie/ompa/blob/main/ompa/core.py)\n\n## 功能模块\n\n### 1. 三元组管理\n\n#### 添加三元组\n\n```python\nao.kg_add(subject, predicate, object_, valid_from=None, source=None)\n```\n\n**参数说明：**\n\n| 参数 | 类型 | 必需 | 描述 |\n|------|------|------|------|\n| subject | str | 是 | 主体实体名称 |\n| predicate | str | 是 | 谓词/关系类型 |\n| object_ | str | 是 | 客体实体或值 |\n| valid_from | str | 否 | 生效时间，格式 YYYY-MM-DD |\n| source | str | 否 | 三元组来源标注 |\n\n**示例：**\n\n```python\nfrom ompa import Ompa\n\nao = Ompa(vault_path=\"./workspace\")\n\n# 添加基础三元组\nao.kg_add(\"Kai\", \"works_on\", \"Orion\")\n\n# 添加带时间戳的三元组\nao.kg_add(\"Kai\", \"works_on\", \"Phoenix\", valid_from=\"2025-06-01\")\n\n# 添加带来源标注的三元组\nao.kg_add(\"决策\", \"approved_by\", \"Team\", source=\"2025-04-15 meeting\")\n```\n\n资料来源：[STABILITY.md](https://github.com/jmiaie/ompa/blob/main/STABILITY.md)\n\n#### 查询三元组\n\n```python\nao.kg_query(entity, as_of=None) -> list[Triple]\n```\n\n**参数说明：**\n\n| 参数 | 类型 | 必需 | 描述 |\n|------|------|------|------|\n| entity | str | 是 | 要查询的实体名称 |\n| as_of | str | 否 | 查询时间点，返回该时间点的有效状态 |\n\n**返回类型：** `list[Triple]`，每个 Triple 包含 subject、predicate、object_、valid_from、valid_to、source 属性。\n\n**示例：**\n\n```python\n# 查询实体所有历史记录\ntriples = ao.kg_query(\"Kai\")\n\n# 查询特定时间点的状态\ntriples = ao.kg_query(\"Kai\", as_of=\"2025-06-01\")\n```\n\n资料来源：[STABILITY.md](https://github.com/jmiaie/ompa/blob/main/STABILITY.md)\n\n### 2. 时间线查询\n\n```python\nao.kg_timeline(entity) -> list[dict]\n```\n\n该方法返回指定实体的完整时间线，展示实体的所有关系变化历史。\n\n**返回格式：**\n\n```python\n[\n {\n \"subject\": \"Kai\",\n \"predicate\": \"works_on\",\n \"object\": \"Orion\",\n \"valid_from\": \"2025-01-01\",\n \"valid_to\": \"2025-05-31\",\n \"source\": \"manual\"\n },\n {\n \"subject\": \"Kai\",\n \"predicate\": \"works_on\",\n \"object\": \"Phoenix\",\n \"valid_from\": \"2025-06-01\",\n \"valid_to\": None,\n \"source\": \"manual\"\n }\n]\n```\n\n**示例：**\n\n```python\n# 获取实体的完整时间线\ntimeline = ao.kg_timeline(\"Kai\")\n\n# 分析项目变更历史\nfor entry in timeline:\n print(f\"{entry['valid_from']}: {entry['subject']} {entry['predicate']} {entry['object']}\")\n```\n\n资料来源：[ompa/mcp_server.py](https://github.com/jmiaie/ompa/blob/main/ompa/mcp_server.py)\n\n### 3. 统计信息\n\n```python\nao.kg_stats() -> dict\n```\n\n返回知识图谱的统计信息，包括三元组总数、按谓词分组统计等。\n\n**示例：**\n\n```python\nstats = ao.kg_stats()\nprint(f\"Total triples: {stats['total']}\")\nprint(f\"By predicate: {stats['by_predicate']}\")\n```\n\n资料来源：[ompa/mcp_server.py](https://github.com/jmiaie/ompa/blob/main/ompa/mcp_server.py)\n\n### 4. 自动填充\n\n时序知识图谱支持从 Vault 自动提取三元组，包括：\n\n- 从 frontmatter 标签提取实体\n- 从文件夹路径提取组织结构\n- 从 `[[wikilinks]]` 提取关系\n\n```python\n# 自动从 Vault 填充知识图谱\nao.kg.populate_from_vault()\n```\n\n**工作流程：**\n\n```mermaid\ngraph LR\n A[扫描 Vault] --> B[解析笔记]\n B --> C[提取 frontmatter 标签]\n B --> D[解析 wikilinks]\n B --> E[分析文件夹路径]\n C --> F[生成三元组]\n D --> F\n E --> F\n F --> G[写入知识图谱]\n```\n\n资料来源：[CHANGELOG.md](https://github.com/jmiaie/ompa/blob/main/CHANGELOG.md)\n\n## MCP 工具接口\n\nOMPA 通过 MCP（Model Context Protocol）服务器暴露知识图谱功能，可在 Claude Desktop、Cursor、Windsurf 等工具中使用。\n\n### 可用工具列表\n\n| 工具名称 | 功能 | 必需参数 |\n|----------|------|----------|\n| `ao_kg_query` | 查询实体的三元组 | entity |\n| `ao_kg_add` | 添加三元组 | subject, predicate, object_ |\n| `ao_kg_stats` | 获取统计信息 | - |\n| `ao_kg_timeline` | 获取实体时间线 | entity |\n| `ao_kg_populate` | 从 Vault 填充 KG | - |\n\n资料来源：[CLAUDE.md](https://github.com/jmiaie/ompa/blob/main/CLAUDE.md)\n\n### MCP 使用示例\n\n```json\n{\n \"tool\": \"ao_kg_add\",\n \"arguments\": {\n \"subject\": \"Alice\",\n \"predicate\": \"reports_to\",\n \"object_\": \"Bob\",\n \"valid_from\": \"2025-01-15\",\n \"source\": \"org chart update\"\n }\n}\n```\n\n## CLI 命令\n\n### kg-query\n\n查询特定实体的所有三元组：\n\n```bash\nao kg-query Kai\n```\n\n### kg-timeline\n\n获取实体的完整时间线：\n\n```bash\nao kg-timeline Orion\n```\n\n### kg-stats\n\n查看知识图谱统计信息：\n\n```bash\nao kg-stats\n```\n\n资料来源：[README.md](https://github.com/jmiaie/ompa/blob/main/README.md)\n\n## 版本演进\n\n### v0.3.0 — 自动填充功能\n\n新增 `KnowledgeGraph.populate_from_vault()` 方法，支持从现有笔记中自动提取三元组。\n\n> 资料来源：[CHANGELOG.md](https://github.com/jmiaie/ompa/blob/main/CHANGELOG.md)\n\n### v0.4.0 — 双重 Vault 集成\n\n时序知识图谱支持双重 Vault 架构，可在共享库和个人库之间独立维护知识图谱，并支持库之间的导入导出及数据脱敏。\n\n> 资料来源：[CHANGELOG.md](https://github.com/jmiaie/ompa/blob/main/CHANGELOG.md)\n\n## 最佳实践\n\n### 1. 实体命名规范\n\n- 使用一致的实体命名格式\n- 建议使用 CamelCase 或 snake_case 命名法\n- 避免在实体名中使用特殊字符\n\n### 2. 时间戳管理\n\n- 所有时间戳使用 `YYYY-MM-DD` 格式\n- 建议为关键关系变更添加 valid_from 时间戳\n- 时间线查询可帮助理解实体状态演变\n\n### 3. 来源标注\n\n- 为自动填充的三元组标注来源笔记\n- 为手动添加的三元组添加来源说明\n- 有助于追溯知识来源和验证准确性\n\n### 4. 性能考虑\n\n- 大量插入时使用批量操作\n- 定期执行 `ao rebuild-index` 维护索引\n- 复杂查询可结合 Palace 的组织结构加速\n\n## API 稳定性\n\n时序知识图谱的公共 API 自 v1.0.0 起遵循语义化版本控制。破坏性变更仅在主版本更新时发生，并将在 CHANGELOG.md 中提供迁移指南。\n\n> 资料来源：[STABILITY.md](https://github.com/jmiaie/ompa/blob/main/STABILITY.md)\n\n---\n\n\n\n## 消息分类器\n\n### 相关页面\n\n相关主题：[生命周期钩子](#lifecycle-hooks), [Vault存储层](#vault)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [ompa/classifier.py](https://github.com/jmiaie/ompa/blob/main/ompa/classifier.py)\n- [ompa/core.py](https://github.com/jmiaie/ompa/blob/main/ompa/core.py)\n- [ompa/config.py](https://github.com/jmiaie/ompa/blob/main/ompa/config.py)\n- [CONTRIBUTING.md](https://github.com/jmiaie/ompa/blob/main/CONTRIBUTING.md)\n- [CLAUDE.md](https://github.com/jmiaie/ompa/blob/main/CLAUDE.md)\n- [README.md](https://github.com/jmiaie/ompa/blob/main/README.md)\n \n\n# 消息分类器\n\n## 概述\n\n消息分类器（Message Classifier）是 OMPA 系统的核心组件之一，负责自动识别和分类用户消息的类型，并将每条消息路由到相应的存储位置。该系统基于正则表达式模式匹配和决策树逻辑，实现了 15 种预定义消息类型的自动分类。\n\n消息分类器的主要职责包括：\n\n- **类型识别**：通过正则表达式模式分析消息内容，确定消息属于哪种类型\n- **路由建议**：为每种类型提供存储路径建议和操作提示\n- **双库支持**：在双库模式下，自动判断消息应存储到共享库还是个人库\n- **CLI 集成**：提供命令行工具 `ao classify` 用于手动消息分类\n\n资料来源：[ompa/classifier.py:1-50]()\n\n## 系统架构\n\n消息分类器采用分层架构设计，核心组件包括分类引擎、模式匹配器、路由控制器。\n\n```mermaid\ngraph TD\n A[用户消息] --> B[Classifier 分类器]\n B --> C{模式匹配引擎}\n C -->|正则匹配| D[PATTERNS 模式库]\n C --> E[ClassificationResult 结果]\n E --> F[ROUTING_HINTS 路由提示]\n E --> G[FOLDER_MAP 文件夹映射]\n E --> H[VaultTarget 目标库判定]\n H --> I[SHARED 共享库]\n H --> J[PERSONAL 个人库]\n```\n\n## MessageType 枚举\n\nOMPA 定义了 15 种消息类型，每种类型对应不同的业务场景和存储位置。\n\n| 枚举值 | 中文名称 | 典型关键词 | 存储建议 |\n|--------|----------|------------|----------|\n| `DECISION` | 决策记录 | decided, agreed, ADR | brain/Key Decisions.md |\n| `INCIDENT` | 事故记录 | incident, outage, bug | work/incidents/ |\n| `WIN` | 成果记录 | won, shipped, deployed | perf/Brag Doc.md |\n| `ONE_ON_ONE` | 一对一会议 | 1:1, feedback, check-in | work/1-1/ |\n| `MEETING` | 会议记录 | meeting, agenda, notes | work/meetings/ |\n| `PROJECT_UPDATE` | 项目更新 | project, progress, blocked | work/active/ |\n| `PERSON_INFO` | 人员信息 | joined, role, team update | org/people/ |\n| `QUESTION` | 问题咨询 | how do, what is, why | brain/questions/ |\n| `TASK` | 任务清单 | todo, action item | work/tasks/ |\n| `ARCHITECTURE` | 架构设计 | architecture, design, API | work/architecture/ |\n| `CODE` | 代码相关 | code, function, PR | work/code/ |\n| `BRAIN_DUMP` | 脑暴记录 | dump, random thoughts | brain/dumps/ |\n| `WRAP_UP` | 会议总结 | wrap up, end session | brain/sessions/ |\n| `STANDUP` | 站会记录 | standup, daily | work/standups/ |\n| `RESEARCH` | 调研记录 | researching, exploring | brain/research/ |\n\n资料来源：[ompa/classifier.py:1-100]()\n\n## 分类流程\n\n### 1. 模式匹配阶段\n\n分类器使用预定义的正则表达式模式库 `PATTERNS` 对消息进行匹配。每个消息类型对应多组正则表达式，支持灵活的匹配策略。\n\n```mermaid\ngraph LR\n A[消息文本] --> B[遍历 MessageType]\n B --> C[匹配 PATTERNS]\n C --> D{找到匹配?}\n D -->|是| E[记录类型得分]\n D -->|否| F[继续下一个类型]\n E --> G{还有类型?}\n F --> G\n G -->|是| B\n G -->|否| H[返回最高得分类型]\n```\n\n### 2. 路由决策阶段\n\n基于分类结果，系统生成 `Classification` 对象，包含：\n\n- `message_type`：识别出的消息类型\n- `suggested_folder`：建议存储文件夹\n- `confidence`：匹配置信度（基于匹配到的模式数量）\n- `routing_hints`：操作提示列表\n\n资料来源：[ompa/classifier.py:100-200]()\n\n## 核心实现\n\n### Classifier 类\n\n```python\nclass Classifier:\n def classify(self, message: str) -> Classification:\n \"\"\"核心分类方法\"\"\"\n best_match = None\n best_score = 0\n \n for msg_type in MessageType:\n score = self._calculate_score(message, msg_type)\n if score > best_score:\n best_score = score\n best_match = msg_type\n \n return Classification(\n message_type=best_match,\n suggested_folder=FOLDER_MAP.get(best_match, \"brain/\"),\n confidence=best_score / max_patterns,\n routing_hints=ROUTING_HINTS.get(best_match, [])\n )\n```\n\n### PATTERNS 模式库\n\n每个消息类型定义多组正则表达式模式：\n\n| 消息类型 | 模式示例 |\n|----------|----------|\n| DECISION | `r\"\\b(decided|going with|settled on|agreed to)\\b\"` |\n| INCIDENT | `r\"\\b(incident|outage|bug|crash|failure)\\b\"` |\n| WIN | `r\"\\b(won|praised|success|achieved|shipped)\\b\"` |\n| QUESTION | `r\"\\b(how do|how can|what is|what are|why does)\\b\"` |\n\n资料来源：[ompa/classifier.py:100-150]()\n\n### FOLDER_MAP 文件夹映射\n\n| 消息类型 | 目标文件夹 |\n|----------|------------|\n| DECISION | brain/ |\n| INCIDENT | work/incidents/ |\n| WIN | perf/ |\n| ONE_ON_ONE | work/1-1/ |\n| MEETING | work/meetings/ |\n| PROJECT_UPDATE | work/active/ |\n| PERSON_INFO | org/people/ |\n| QUESTION | brain/questions/ |\n| TASK | work/tasks/ |\n| ARCHITECTURE | work/architecture/ |\n| CODE | work/code/ |\n| BRAIN_DUMP | brain/dumps/ |\n| WRAP_UP | brain/sessions/ |\n| STANDUP | work/standups/ |\n| RESEARCH | brain/research/ |\n\n资料来源：[ompa/classifier.py:150-200]()\n\n## 双库模式集成\n\n消息分类器与双库架构（Dual-Vault）紧密集成，支持自动内容隔离。\n\n### IsolationMode.AUTO 模式\n\n在自动模式下，分类器根据消息类型自动判断存储目标：\n\n```python\n# DualVaultConfig.classify_content() 集成\ntarget = self.dual_config.classify_content(\n content=message,\n tags=tags,\n file_path=file_path\n)\n```\n\n资料来源：[ompa/core.py:50-80]()\n\n### 自动分类规则\n\n| 消息类型 | 默认目标库 | 说明 |\n|----------|------------|------|\n| WIN | PERSONAL | 个人绩效相关 |\n| ONE_ON_ONE | PERSONAL | 私密对话 |\n| BRAIN_DUMP | PERSONAL | 私人脑暴 |\n| DECISION | SHARED | 团队决策 |\n| INCIDENT | SHARED | 事故共享 |\n| PROJECT_UPDATE | SHARED | 项目信息 |\n\n## CLI 接口\n\n### ao classify 命令\n\n```bash\nao classify \"We decided to go with Postgres for the main database\"\n```\n\n输出示例：\n\n```\nType: DECISION\nConfidence: 0.85\nFolder: brain/\nHints:\n - This is a decision. Record it in brain/Key Decisions.md\n - Update relevant project notes with the decision\n - Add to Decision Log if formal ADR needed\n```\n\n资料来源：[ompa/cli.py]()\n\n## MCP 服务器集成\n\n消息分类功能通过 MCP 协议暴露为工具：\n\n```json\n{\n \"name\": \"ao_classify\",\n \"description\": \"Classify a message and get routing hints\"\n}\n```\n\n资料来源：[ompa/mcp_server.py:1-50]()\n\n## 扩展消息类型\n\n要添加新的消息类型，需完成以下步骤：\n\n### 1. 添加枚举值\n\n在 `classifier.py` 的 `MessageType` 枚举中添加新类型。\n\n### 2. 添加正则模式\n\n```python\nPATTERNS[MessageType.NEW_TYPE] = [\n r\"\\b(keyword1|keyword2)\\b\",\n r\"\\b(another pattern)\\b\",\n]\n```\n\n### 3. 添加路由提示\n\n```python\nROUTING_HINTS[MessageType.NEW_TYPE] = [\n \"Store in appropriate location\",\n \"Update relevant notes\",\n]\n```\n\n### 4. 添加文件夹映射\n\n```python\nFOLDER_MAP[MessageType.NEW_TYPE] = \"path/to/folder/\"\n```\n\n### 5. 添加测试用例\n\n在 `tests/test_ompa.py` 的 `TestClassifier` 类中添加测试用例。\n\n资料来源：[CONTRIBUTING.md:40-55]()\n\n## 配置参数\n\n消息分类器本身无需额外配置，但可通过环境变量影响其行为：\n\n| 环境变量 | 说明 | 默认值 |\n|----------|------|--------|\n| `OMPA_VAULT_PATH` | 保险库路径 | `.` |\n| `OMPA_SHARED_VAULT` | 共享库路径 | - |\n| `OMPA_PERSONAL_VAULT` | 个人库路径 | - |\n\n资料来源：[examples/mcp_desktop/README.md:1-30]()\n\n## 最佳实践\n\n### 1. 消息预处理\n\n- 消息应保持原始内容，不要提前摘要\n- 移除敏感信息后再进行分类\n- 包含足够的上下文以提高分类准确率\n\n### 2. 置信度阈值\n\n建议在下游处理中设置置信度阈值：\n\n```python\nresult = classifier.classify(message)\nif result.confidence < 0.5:\n # 人工复核或使用默认分类\n pass\n```\n\n### 3. 自定义模式\n\n可通过继承 `Classifier` 类添加自定义模式：\n\n```python\nclass CustomClassifier(Classifier):\n def _calculate_score(self, message: str, msg_type: MessageType) -> float:\n base_score = super()._calculate_score(message, msg_type)\n # 添加自定义评分逻辑\n return base_score\n```\n\n## 性能特性\n\n| 特性 | 说明 |\n|------|------|\n| 延迟 | O(n*m)，n=消息数，m=每类型模式数 |\n| 内存 | 模式编译后缓存 |\n| 并发 | 线程安全 |\n\n分类器采用延迟模式编译策略，模式在首次使用时编译并缓存，确保高性能。\n\n## 已知限制\n\n- 依赖正则表达式，对语义理解有限\n- 混合类型消息可能分类不准确\n- 不支持多语言消息分类（当前仅英文模式）\n\n## 相关资源\n\n- [CLAUDE.md](./CLAUDE.md) - 架构决策文档\n- [STABILITY.md](./STABILITY.md) - API 稳定性保证\n- [测试文件 tests/test_ompa.py](../tests/test_ompa.py) - 分类器测试用例\n\n---\n\n\n\n## MCP服务器集成\n\n### 相关页面\n\n相关主题：[框架适配器](#adapters)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [ompa/mcp_server.py](https://github.com/jmiaie/ompa/blob/main/ompa/mcp_server.py)\n- [examples/mcp_desktop/README.md](https://github.com/jmiaie/ompa/blob/main/examples/mcp_desktop/README.md)\n- [README.md](https://github.com/jmiaie/ompa/blob/main/README.md)\n- [CLAUDE.md](https://github.com/jmiaie/ompa/blob/main/CLAUDE.md)\n- [CONTRIBUTING.md](https://github.com/jmiaie/ompa/blob/main/CONTRIBUTING.md)\n \n\n# MCP服务器集成\n\n## 概述\n\nOMPA通过MCP（Model Context Protocol）服务器提供与AI代理桌面客户端的深度集成。该服务器以Python模块形式运行，通过标准输入/输出（stdin/stdout）使用JSON-RPC 2.0协议与客户端通信，使AI代理能够直接访问OMPA的核心功能。\n\nMCP服务器暴露了15个工具，涵盖保险库管理、知识图谱查询、语义搜索、宫殿导航等功能。开发者可参考稳定性文档确认这些工具为公开API的一部分。\n\n资料来源：[ompa/mcp_server.py:1-50]()\n\n## 架构设计\n\n### 通信协议\n\nMCP服务器采用JSON-RPC 2.0 over stdin/stdout的标准模式：\n\n```mermaid\ngraph LR\n A[\"Claude/Cursor/Windsurf
MCP Client\"] <-->|\"JSON-RPC
stdin/stdout\"| B[\"ompa.mcp_server
Python Process\"]\n B --> C[\"Ompa Core
Vault + Palace + KG\"]\n```\n\n服务器在初始化时返回协议版本和能力描述：\n\n```python\nresponse = {\n \"jsonrpc\": \"2.0\",\n \"id\": request_id,\n \"result\": {\n \"protocolVersion\": \"2024-11-05\",\n \"capabilities\": {\"tools\": {}},\n \"serverInfo\": {\n \"name\": \"ompa\",\n \"version\": __version__,\n },\n },\n}\n```\n\n资料来源：[ompa/mcp_server.py:160-175]()\n\n### 主循环处理\n\n服务器在`main()`函数中持续监听stdin，每次读取一行JSON-RPC请求：\n\n```python\ndef main():\n request = None\n while True:\n try:\n line = sys.stdin.readline()\n if not line:\n break\n request = json.loads(line.strip())\n # 处理请求...\n except Exception as e:\n return {\"error\": type(e).__name__}\n```\n\n资料来源：[ompa/mcp_server.py:180-195]()\n\n## MCP工具清单\n\n### 工具分类表\n\n| 类别 | 工具名称 | 功能描述 |\n|------|----------|----------|\n| 生命周期 | `ao_init` | 初始化新的OMPA保险库 |\n| 生命周期 | `ao_session_start` | 启动会话并注入记忆上下文 |\n| 生命周期 | `ao_wrap_up` | 会话总结并持久化 |\n| 生命周期 | `ao_status` | 检查保险库健康状态 |\n| 分类 | `ao_classify` | 分类消息并返回路由提示 |\n| 搜索 | `ao_search` | 执行语义搜索 |\n| 知识图谱 | `ao_kg_query` | 查询实体关系 |\n| 知识图谱 | `ao_kg_add` | 添加知识三元组 |\n| 知识图谱 | `ao_kg_stats` | 知识图谱统计 |\n| 知识图谱 | `ao_kg_populate` | 从保险库填充知识图谱 |\n| 宫殿 | `ao_palace_wings` | 列出所有宫殿翅膀 |\n| 宫殿 | `ao_palace_rooms` | 列出指定翅膀中的房间 |\n| 宫殿 | `ao_palace_tunnel` | 创建/穿越跨翅膀隧道 |\n| 工具 | `ao_orphans` | 检测孤立笔记 |\n| 工具 | `ao_validate` | 验证保险库结构 |\n| 同步 | `ao_sync` | 同步保险库 |\n| 文件 | `ao_write` | 写入笔记 |\n| 文件 | `ao_export` | 导出内容 |\n| 文件 | `ao_import` | 导入内容 |\n\n资料来源：[CLAUDE.md:1-15]()\n\n### 知识图谱工具详解\n\n#### ao_kg_add\n\n添加三元组到知识图谱：\n\n```python\nresult = ao_kg_add(\n subject=arguments[\"subject\"],\n predicate=arguments[\"predicate\"],\n object=arguments[\"object\"],\n valid_from=arguments.get(\"valid_from\"),\n source=arguments.get(\"source\"),\n vault_path=vault_path,\n)\n```\n\n参数说明：\n\n| 参数 | 类型 | 必需 | 说明 |\n|------|------|------|------|\n| `subject` | string | 是 | 主语实体 |\n| `predicate` | string | 是 | 关系谓词 |\n| `object` | string | 是 | 宾语实体 |\n| `valid_from` | string | 否 | 有效期起始日期（YYYY-MM-DD） |\n| `source` | string | 否 | 来源文件 |\n\n资料来源：[ompa/mcp_server.py:90-100]()\n\n## 桌面客户端配置\n\n### Claude Desktop\n\n#### 方式一：CLI命令（推荐）\n\n```bash\nclaude mcp add ompa -- python -m ompa.mcp_server\n```\n\n#### 方式二：手动配置\n\n编辑 `~/.claude/claude_desktop_config.json`：\n\n```json\n{\n \"mcpServers\": {\n \"ompa\": {\n \"command\": \"python\",\n \"args\": [\"-m\", \"ompa.mcp_server\"],\n \"env\": {\n \"OMPA_VAULT_PATH\": \"/absolute/path/to/your/vault\"\n }\n }\n }\n}\n```\n\n配置完成后需重启Claude Desktop应用。\n\n资料来源：[examples/mcp_desktop/README.md:1-40]()\n\n### Cursor\n\n在项目根目录创建 `.cursor/mcp.json`：\n\n```json\n{\n \"mcpServers\": {\n \"ompa\": {\n \"command\": \"python\",\n \"args\": [\"-m\", \"ompa.mcp_server\"],\n \"env\": {\n \"OMPA_VAULT_PATH\": \"${workspaceFolder}/.ompa-vault\",\n \"OMPA_ENABLE_SEMANTIC\": \"false\"\n }\n }\n }\n}\n```\n\n资料来源：[examples/mcp_desktop/README.md:50-65]()\n\n### Windsurf\n\n配置方式与Cursor相同，创建 `.windsurf/mcp.json`：\n\n```json\n{\n \"mcpServers\": {\n \"ompa\": {\n \"command\": \"python\",\n \"args\": [\"-m\", \"ompa.mcp_server\"],\n \"env\": {\n \"OMPA_VAULT_PATH\": \"/path/to/vault\"\n }\n }\n }\n}\n```\n\n资料来源：[examples/mcp_desktop/README.md:25-35]()\n\n## 环境变量配置\n\n### 配置项总览\n\n| 变量名 | 默认值 | 说明 |\n|--------|--------|------|\n| `OMPA_VAULT_PATH` | `.` | 保险库绝对路径 |\n| `OMPA_ENABLE_SEMANTIC` | `false` | 启用本地语义搜索 |\n| `OMPA_AGENT_NAME` | `agent` | 代理名称（用于知识图谱条目作用域） |\n| `OMPA_SHARED_VAULT` | — | 共享保险库路径（双保险库模式） |\n| `OMPA_PERSONAL_VAULT` | — | 个人保险库路径（双保险库模式） |\n\n资料来源：[examples/mcp_desktop/README.md:70-85]()\n\n### 语义搜索配置\n\n默认情况下，语义搜索功能关闭。如需启用本地语义搜索（首次运行会下载约500MB的`all-MiniLM-L6-v2`模型）：\n\n```bash\npip install ompa[all]\n```\n\n然后在MCP配置的`env`块中设置：\n\n```json\n{\n \"env\": {\n \"OMPA_ENABLE_SEMANTIC\": \"true\"\n }\n}\n```\n\n后续运行将直接使用缓存模型，无额外下载。\n\n资料来源：[examples/mcp_desktop/README.md:40-50]()\n\n## 双保险库模式集成\n\nMCP服务器支持双保险库架构，可隔离团队/组织内容与个人私密笔记。\n\n### MCP配置示例\n\n```json\n{\n \"mcpServers\": {\n \"ompa\": {\n \"command\": \"python\",\n \"args\": [\"-m\", \"ompa.mcp_server\"],\n \"env\": {\n \"OMPA_SHARED_VAULT\": \"/path/to/shared-vault\",\n \"OMPA_PERSONAL_VAULT\": \"/path/to/personal-vault\",\n \"OMPA_ISOLATION_MODE\": \"auto\"\n }\n }\n }\n}\n```\n\n### 隔离模式\n\n| 模式 | 说明 |\n|------|------|\n| `auto` | 内容根据消息类型自动分类到共享或个人保险库 |\n| `strict` | 严格隔离模式 |\n| `manual` | 每个操作需显式指定`VaultTarget` |\n\n资料来源：[examples/mcp_desktop/README.md:100-120]()\n\n## 连接验证\n\n配置完成后，可通过以下方式验证连接：\n\n1. 在支持MCP的客户端中，询问AI助手：\n > \"Use the ao_status tool to check my OMPA vault health\"\n\n2. 预期响应应包含保险库统计信息。\n\n### 常见问题排查\n\n| 问题 | 解决方案 |\n|------|----------|\n| 工具未出现 | 重启桌面应用 |\n| \"Vault not found\" 错误 | 确认`OMPA_VAULT_PATH`为绝对路径且已通过`ao init`初始化 |\n| 首次运行缓慢 | 若启用语义搜索，首次运行需下载模型（约90MB），后续运行应立即响应 |\n\n资料来源：[examples/mcp_desktop/README.md:120-135]()\n\n## 框架兼容性\n\nOMPA的MCP服务器支持多种AI代理框架：\n\n| 代理框架 | 集成方式 |\n|----------|----------|\n| Claude Code | Python API + MCP服务器 |\n| OpenClaw | Python API + MCP服务器 |\n| Codex | Python API + MCP服务器 |\n| Gemini CLI | Python API + MCP服务器 |\n| LangChain | Python API |\n\nMCP服务器为框架无关的纯Python实现，无代理SDK依赖。\n\n资料来源：[README.md:60-75]()\n\n## 启动方式汇总\n\n### 启动命令对照表\n\n| 环境 | 启动命令 |\n|------|----------|\n| 直接运行 | `python -m ompa.mcp_server` |\n| Claude Desktop | `claude mcp add ompa -- python -m ompa.mcp_server` |\n| 指定保险库 | 设置`OMPA_VAULT_PATH`环境变量 |\n| 启用语义搜索 | 设置`OMPA_ENABLE_SEMANTIC=true` |\n\n所有启动方式均要求目标保险库已通过`ao init`初始化。\n\n资料来源：[examples/mcp_desktop/README.md:1-20]()\n\n## 安全特性\n\nMCP服务器继承OMPA核心的安全设计：\n\n1. **路径遍历防护**：所有保险库文件操作都解析并边界检查路径\n2. **UTF-8编码强制**：所有保险库文件写入显式指定UTF-8编码\n3. **并发安全**：笔记CRUD操作支持并发访问\n\n资料来源：[CHANGELOG.md:30-50]()\n\n## 相关文档\n\n- [CLAUDE.md](https://github.com/jmiaie/ompa/blob/main/CLAUDE.md) — 架构决策与内部API文档\n- [STABILITY.md](https://github.com/jmiaie/ompa/blob/main/STABILITY.md) — API稳定性保证\n- [CONTRIBUTING.md](https://github.com/jmiaie/ompa/blob/main/CONTRIBUTING.md) — 添加新MCP工具的指南\n\n---\n\n\n\n## 框架适配器\n\n### 相关页面\n\n相关主题：[MCP服务器集成](#mcp-server)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [ompa/adapters/langchain.py](https://github.com/jmiaie/ompa/blob/main/ompa/adapters/langchain.py)\n- [ompa/adapters/llamaindex.py](https://github.com/jmiaie/ompa/blob/main/ompa/adapters/llamaindex.py)\n- [ompa/adapters/faiss.py](https://github.com/jmiaie/ompa/blob/main/ompa/adapters/faiss.py)\n- [ompa/adapters/nim.py](https://github.com/jmiaie/ompa/blob/main/ompa/adapters/nim.py)\n- [ompa/adapters/openai_agents.py](https://github.com/jmiaie/ompa/blob/main/ompa/adapters/openai_agents.py)\n- [examples/langchain_agent/ompa_memory.py](https://github.com/jmiaie/ompa/blob/main/examples/langchain_agent/ompa_memory.py)\n \n\n# 框架适配器\n\nOMPA 框架适配器（Framework Adapters）是一组将 OMPA 与主流 AI 开发框架集成的桥接模块。这些适配器位于 `ompa/adapters/` 目录下，提供了与 LangChain、LlamaIndex、OpenAI Agents SDK 等框架的无缝对接能力，使开发者能够在现有 AI 应用架构中直接利用 OMPA 的记忆管理、知识图谱和语义搜索功能。\n\n## 架构概览\n\nOMPA 适配器层采用了适配器模式（Adapter Pattern），将 OMPA 的核心功能封装为各框架所期望的接口形式。这种设计使得 OMPA 可以作为多种 AI 框架的底层存储和检索后端，而无需修改框架本身的代码。\n\n```mermaid\ngraph TB\n subgraph \"AI 应用层\"\n LC[LangChain 应用]\n LI[LlamaIndex 应用]\n OAI[OpenAI Agents]\n CUSTOM[自定义应用]\n end\n \n subgraph \"适配器层\"\n LCM[OmpaMemory
OmpaRetriever]\n LIC[OmpaReader
OmpaVaultRetriever]\n OAIC[OmpaAgentHooks]\n NIM[NIMEmbeddingBackend]\n FAISS[FAISSSemanticIndex]\n end\n \n subgraph \"OMPA 核心\"\n CORE[Ompa Core]\n VAULT[Vault]\n KG[Knowledge Graph]\n SEM[Semantic Index]\n end\n \n LC --> LCM\n LI --> LIC\n OAI --> OAIC\n CUSTOM --> NIM\n CUSTOM --> FAISS\n \n LCM --> CORE\n LIC --> CORE\n OAIC --> CORE\n NIM --> SEM\n FAISS --> SEM\n \n CORE --> VAULT\n CORE --> KG\n```\n\n## 可用适配器列表\n\n| 适配器 | 源文件 | 功能描述 |\n|--------|--------|----------|\n| `OmpaMemory` | `ompa/adapters/langchain.py` | LangChain 聊天记忆组件 |\n| `OmpaRetriever` | `ompa/adapters/langchain.py` | LangChain 检索器，用于 RAG 链 |\n| `OmpaReader` | `ompa/adapters/llamaindex.py` | LlamaIndex 文档读取器 |\n| `OmpaVaultRetriever` | `ompa/adapters/llamaindex.py` | LlamaIndex 保险库检索器 |\n| `OmpaAgentHooks` | `ompa/adapters/openai_agents.py` | OpenAI Agents SDK 生命周期钩子 |\n| `NIMEmbeddingBackend` | `ompa/adapters/nim.py` | NVIDIA NIM 嵌入后端 |\n| `FAISSSemanticIndex` | `ompa/adapters/faiss.py` | FAISS 语义索引实现 |\n\n资料来源：[STABILITY.md]()\n\n## LangChain 适配器\n\nLangChain 适配器提供了与 LangChain 框架的深度集成，支持将 OMPA 作为聊天记忆存储和检索后端使用。\n\n### OmpaMemory\n\n`OmpaMemory` 是实现 LangChain `BaseChatMemory` 接口的记忆组件，它将 OMPA 保险库作为持久化存储层。\n\n**主要方法：**\n\n```python\nload_memory_variables(inputs) -> dict\nsave_context(inputs, outputs) -> None\nclear() -> None\n```\n\n**使用示例：**\n\n```python\nfrom ompa.adapters.langchain import OmpaMemory\nfrom langchain.chains import ConversationChain\nfrom langchain_anthropic import ChatAnthropic\n\n# 初始化记忆组件\nmemory = OmpaMemory(vault_path=\"./workspace\")\n\n# 创建对话链\nchain = ConversationChain(\n llm=ChatAnthropic(model=\"claude-sonnet-4-20250514\"),\n memory=memory\n)\n\n# 对话交互\nresponse = chain.invoke({\"input\": \"用户输入内容\"})\n```\n\n资料来源：[ompa/adapters/langchain.py:51-67]()\n\n### OmpaRetriever\n\n`OmpaRetriever` 包装了 OMPA 的搜索功能，使其可以作为 LangChain RAG 链中的检索器使用。\n\n```python\nfrom ompa.adapters.langchain import OmpaRetriever\n\nretriever = OmpaRetriever(vault_path=\"./workspace\")\n# 在 RAG 链中使用\nrag_chain = create_retrieval_chain(llm, retriever)\n```\n\n## LlamaIndex 适配器\n\nLlamaIndex 适配器提供了文档读取和检索能力，使 OMPA 保险库可以作为 LlamaIndex 的数据源。\n\n### OmpaReader\n\n`OmpaReader` 用于从 OMPA 保险库中读取文档并转换为 LlamaIndex 的文档格式。\n\n```python\nfrom ompa.adapters.llamaindex import OmpaReader\n\nreader = OmpaReader(vault_path=\"./workspace\")\ndocuments = reader.load_data()\n```\n\n### OmpaVaultRetriever\n\n`OmpaVaultRetriever` 提供了对 OMPA 保险库的向量检索能力，可直接集成到 LlamaIndex 的查询引擎中。\n\n```python\nfrom ompa.adapters.llamaindex import OmpaVaultRetriever\n\nretriever = OmpaVaultRetriever(vault_path=\"./workspace\")\n```\n\n## OpenAI Agents SDK 适配器\n\n`OmpaAgentHooks` 为 OpenAI Agents SDK 提供了 OMPA 的生命周期钩子集成。\n\n```python\nfrom ompa.adapters.openai_agents import OmpaAgentHooks\n\nhooks = OmpaAgentHooks(vault_path=\"./workspace\")\n# 在 OpenAI Agents 应用中注册钩子\n```\n\n## 向量存储适配器\n\n### NIMEmbeddingBackend\n\n`NIMEmbeddingBackend` 提供了与 NVIDIA NIM（NVIDIA Inference Management）服务的集成，用于生成嵌入向量。\n\n```python\nfrom ompa.adapters.nim import NIMEmbeddingBackend\n\nbackend = NIMEmbeddingBackend(\n api_key=\"your-api-key\",\n model=\"nvidia/nvolve-4q\"\n)\n```\n\n### FAISSSemanticIndex\n\n`FAISSSemanticIndex` 使用 Facebook AI Similarity Search (FAISS) 库实现高效的向量相似度搜索。\n\n```python\nfrom ompa.adapters.faiss import FAISSSemanticIndex\n\nindex = FAISSSemanticIndex(vault_path=\"./workspace\")\n```\n\n## 安装依赖\n\n不同的适配器需要不同的可选依赖包：\n\n```bash\n# LangChain 适配器\npip install ompa[langchain]\n\n# LlamaIndex 适配器\npip install ompa[llamaindex]\n\n# 所有适配器\npip install ompa[all]\n```\n\n## 稳定性说明\n\n根据项目稳定性策略，适配器接口在以下方面保持稳定：\n\n- 公共方法签名\n- 构造函数参数\n- 返回值类型\n\n适配器的内部实现细节可能在次版本更新中发生变化，但公共 API 将保持向后兼容。 资料来源：[STABILITY.md]()\n\n## 最佳实践\n\n1. **惰性初始化**：适配器支持惰性加载模型和索引，避免在导入时触发大量资源下载。\n2. **会话管理**：在长时间运行的 AI 应用中，确保在应用关闭时正确清理资源。\n3. **并发访问**：多个框架实例可以同时访问同一个 OMPA 保险库，适配器已处理并发读写场景。\n4. **配置分离**：建议将不同框架的适配器配置分离管理，便于独立调试和优化。\n\n## 扩展适配器\n\n开发者可以通过实现相应的协议（Protocol）接口来创建自定义适配器：\n\n```python\nfrom ompa.semantic import EmbeddingBackend\n\nclass CustomEmbeddingBackend(EmbeddingBackend):\n \"\"\"自定义嵌入后端接口\"\"\"\n \n async def embed(self, texts: list[str]) -> list[list[float]]:\n # 实现自定义嵌入逻辑\n pass\n \n async def embed_query(self, query: str) -> list[float]:\n # 实现自定义查询嵌入\n pass\n```\n\n## 与核心模块的关系\n\n```mermaid\ngraph LR\n subgraph \"适配器层\"\n LANG[LangChain]\n LLAMA[LlamaIndex]\n OAI[OpenAI Agents]\n end\n \n subgraph \"OMPA 核心\"\n VAULT[Vault
笔记持久化]\n KG[Knowledge Graph
三元组存储]\n SEM[Semantic Index
向量索引]\n end\n \n LANG --> VAULT\n LANG --> SEM\n LLAMA --> VAULT\n LLAMA --> SEM\n OAI --> VAULT\n OAI --> KG\n```\n\n适配器层负责将框架特定的接口转换为 OMPA 核心模块的标准调用，实现了框架解耦和应用灵活性的平衡。\n\n---\n\n---\n\n## Doramagic 踩坑日志\n\n项目：jmiaie/ompa\n\n摘要：发现 10 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：安装坑 - 来源证据：OMPA v0.2.0 — The Big Rename。\n\n## 1. 安装坑 · 来源证据：OMPA v0.2.0 — The Big Rename\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：OMPA v0.2.0 — The Big Rename\n- 对用户的影响：可能阻塞安装或首次运行。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_ac771ab081be444ab18c5c1963becb64 | https://github.com/jmiaie/ompa/releases/tag/v0.2.0 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 2. 配置坑 · 来源证据：[P0] agent_integration.py race condition — session.memory attribute not available on cold start\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：[P0] agent_integration.py race condition — session.memory attribute not available on cold start\n- 对用户的影响：可能阻塞安装或首次运行。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_db65ef8ac28c41048d74c03c80cbed28 | https://github.com/jmiaie/ompa/issues/6 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 3. 能力坑 · 能力判断依赖假设\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：README/documentation is current enough for a first validation pass.\n- 对用户的影响：假设不成立时，用户拿不到承诺的能力。\n- 建议检查：将假设转成下游验证清单。\n- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。\n- 证据：capability.assumptions | github_repo:1207151629 | https://github.com/jmiaie/ompa | README/documentation is current enough for a first validation pass.\n\n## 4. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | github_repo:1207151629 | https://github.com/jmiaie/ompa | last_activity_observed missing\n\n## 5. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作：下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | github_repo:1207151629 | https://github.com/jmiaie/ompa | no_demo; severity=medium\n\n## 6. 安全/权限坑 · 存在安全注意事项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：No sandbox install has been executed yet; downstream must verify before user use.\n- 对用户的影响：用户安装前需要知道权限边界和敏感操作。\n- 建议检查：转成明确权限清单和安全审查提示。\n- 防护动作：安全注意事项必须面向用户前置展示。\n- 证据：risks.safety_notes | github_repo:1207151629 | https://github.com/jmiaie/ompa | No sandbox install has been executed yet; downstream must verify before user use.\n\n## 7. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | github_repo:1207151629 | https://github.com/jmiaie/ompa | no_demo; severity=medium\n\n## 8. 安全/权限坑 · 来源证据：OMPA v0.2.1 — Security & Reliability Hardening\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：OMPA v0.2.1 — Security & Reliability Hardening\n- 对用户的影响：可能阻塞安装或首次运行。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_ab0ad6b963354f2096bef6783c95c289 | https://github.com/jmiaie/ompa/releases/tag/v0.2.1 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 9. 维护坑 · issue/PR 响应质量未知\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：issue_or_pr_quality=unknown。\n- 对用户的影响：用户无法判断遇到问题后是否有人维护。\n- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。\n- 防护动作：issue/PR 响应未知时，必须提示维护风险。\n- 证据：evidence.maintainer_signals | github_repo:1207151629 | https://github.com/jmiaie/ompa | issue_or_pr_quality=unknown\n\n## 10. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | github_repo:1207151629 | https://github.com/jmiaie/ompa | release_recency=unknown\n\n\n",
"summary": "DeepWiki/Human Wiki 完整输出，末尾追加 Discovery Agent 踩坑日志。",
"title": "Human Manual / 人类版说明书"
},
"pitfall_log": {
"asset_id": "pitfall_log",
"filename": "PITFALL_LOG.md",
"markdown": "# Pitfall Log / 踩坑日志\n\n项目：jmiaie/ompa\n\n摘要：发现 10 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：安装坑 - 来源证据：OMPA v0.2.0 — The Big Rename。\n\n## 1. 安装坑 · 来源证据：OMPA v0.2.0 — The Big Rename\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：OMPA v0.2.0 — The Big Rename\n- 对用户的影响：可能阻塞安装或首次运行。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_ac771ab081be444ab18c5c1963becb64 | https://github.com/jmiaie/ompa/releases/tag/v0.2.0 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 2. 配置坑 · 来源证据：[P0] agent_integration.py race condition — session.memory attribute not available on cold start\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：[P0] agent_integration.py race condition — session.memory attribute not available on cold start\n- 对用户的影响：可能阻塞安装或首次运行。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_db65ef8ac28c41048d74c03c80cbed28 | https://github.com/jmiaie/ompa/issues/6 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 3. 能力坑 · 能力判断依赖假设\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：README/documentation is current enough for a first validation pass.\n- 对用户的影响：假设不成立时，用户拿不到承诺的能力。\n- 建议检查：将假设转成下游验证清单。\n- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。\n- 证据：capability.assumptions | github_repo:1207151629 | https://github.com/jmiaie/ompa | README/documentation is current enough for a first validation pass.\n\n## 4. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | github_repo:1207151629 | https://github.com/jmiaie/ompa | last_activity_observed missing\n\n## 5. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作：下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | github_repo:1207151629 | https://github.com/jmiaie/ompa | no_demo; severity=medium\n\n## 6. 安全/权限坑 · 存在安全注意事项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：No sandbox install has been executed yet; downstream must verify before user use.\n- 对用户的影响：用户安装前需要知道权限边界和敏感操作。\n- 建议检查：转成明确权限清单和安全审查提示。\n- 防护动作：安全注意事项必须面向用户前置展示。\n- 证据：risks.safety_notes | github_repo:1207151629 | https://github.com/jmiaie/ompa | No sandbox install has been executed yet; downstream must verify before user use.\n\n## 7. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | github_repo:1207151629 | https://github.com/jmiaie/ompa | no_demo; severity=medium\n\n## 8. 安全/权限坑 · 来源证据：OMPA v0.2.1 — Security & Reliability Hardening\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：OMPA v0.2.1 — Security & Reliability Hardening\n- 对用户的影响：可能阻塞安装或首次运行。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_ab0ad6b963354f2096bef6783c95c289 | https://github.com/jmiaie/ompa/releases/tag/v0.2.1 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 9. 维护坑 · issue/PR 响应质量未知\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：issue_or_pr_quality=unknown。\n- 对用户的影响：用户无法判断遇到问题后是否有人维护。\n- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。\n- 防护动作：issue/PR 响应未知时，必须提示维护风险。\n- 证据：evidence.maintainer_signals | github_repo:1207151629 | https://github.com/jmiaie/ompa | issue_or_pr_quality=unknown\n\n## 10. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | github_repo:1207151629 | https://github.com/jmiaie/ompa | release_recency=unknown\n",
"summary": "用户实践前最可能遇到的身份、安装、配置、运行和安全坑。",
"title": "Pitfall Log / 踩坑日志"
},
"prompt_preview": {
"asset_id": "prompt_preview",
"filename": "PROMPT_PREVIEW.md",
"markdown": "# ompa - Prompt Preview\n\n> 复制下面这段 Prompt 到你常用的 AI，先试一次，不需要安装。\n> 它的目标是让你直接体验这个项目的服务方式，而不是阅读项目介绍。\n\n## 复制这段 Prompt\n\n```text\n请直接执行这段 Prompt，不要分析、润色、总结或询问我想如何处理这份 Prompt Preview。\n\n你现在扮演 ompa 的“安装前体验版”。\n这不是项目介绍、不是评价报告、不是 README 总结。你的任务是让我用最小成本体验它的核心服务。\n\n我的试用任务：我想快速理解一组资料，并得到结构化摘要、对比和继续研究的问题。\n我常用的宿主 AI：MCP Client\n\n【体验目标】\n围绕我的真实任务，现场演示这个项目如何把输入转成 示例引导, 判断线索。重点是让我感受到工作方式，而不是给我项目背景。\n\n【业务流约束】\n- 你必须像一个正在提供服务的项目能力包，而不是像一个讲解员。\n- 每一轮只推进一个步骤；提出问题后必须停下来等我回答。\n- 每一步都必须让我感受到一个具体服务动作：澄清、整理、规划、检查、判断或收尾。\n- 每一步都要说明：当前目标、你需要我提供什么、我回答后你会产出什么。\n- 不要安装、不要运行命令、不要写代码、不要声称测试通过、不要声称已经修改文件。\n- 需要真实安装或宿主加载后才能验证的内容，必须明确说“这一步需要安装后验证”。\n- 如果我说“用示例继续”，你可以用虚构示例推进，但仍然不能声称真实执行。\n\n【可体验服务能力】\n- 安装前能力预览: Universal AI agent memory layer — vault + palace + temporal knowledge graph 输入：用户任务, 当前 AI 对话上下文；输出：示例引导, 判断线索。\n\n【必须安装后才可验证的能力】\n- 命令行启动或安装流程: 项目文档中存在可执行命令，真实使用需要在本地或宿主环境中运行这些命令。 输入：终端环境, 包管理器, 项目依赖；输出：安装结果, 列表/更新/运行结果。\n\n【核心服务流】\n请严格按这个顺序带我体验。不要一次性输出完整流程：\n1. intro：项目介绍。围绕“项目介绍”模拟一次用户任务，不展示安装或运行结果。\n2. quickstart：快速入门。围绕“快速入门”模拟一次用户任务，不展示安装或运行结果。\n3. three-layer-design：三层架构设计。围绕“三层架构设计”模拟一次用户任务，不展示安装或运行结果。\n4. lifecycle-hooks：生命周期钩子。围绕“生命周期钩子”模拟一次用户任务，不展示安装或运行结果。\n5. vault：Vault存储层。围绕“Vault存储层”模拟一次用户任务，不展示安装或运行结果。\n\n【核心能力体验剧本】\n每一步都必须按“输入 -> 服务动作 -> 中间产物”执行。不要只说流程名：\n1. intro\n输入：用户提供的“项目介绍”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n2. quickstart\n输入：用户提供的“快速入门”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n3. three-layer-design\n输入：用户提供的“三层架构设计”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n4. lifecycle-hooks\n输入：用户提供的“生命周期钩子”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n5. vault\n输入：用户提供的“Vault存储层”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n【项目服务规则】\n这些规则决定你如何服务用户。不要解释规则本身，而要在每一步执行时遵守：\n- 先确认用户任务、输入材料和成功标准，再模拟项目能力。\n- 每一步都必须形成可检查的小产物，并等待用户确认后再继续。\n- 凡是需要安装、调用工具或访问外部服务的能力，都必须标记为安装后验证。\n\n【每一步的服务约束】\n- Step 1 / intro：Step 1 必须围绕“项目介绍”形成一个小中间产物，并等待用户确认。\n- Step 2 / quickstart：Step 2 必须围绕“快速入门”形成一个小中间产物，并等待用户确认。\n- Step 3 / three-layer-design：Step 3 必须围绕“三层架构设计”形成一个小中间产物，并等待用户确认。\n- Step 4 / lifecycle-hooks：Step 4 必须围绕“生命周期钩子”形成一个小中间产物，并等待用户确认。\n- Step 5 / vault：Step 5 必须围绕“Vault存储层”形成一个小中间产物，并等待用户确认。\n\n【边界与风险】\n- 不要声称已经安装、运行、调用 API、读写本地文件或完成真实任务。\n- 安装前预览只能展示工作方式，不能证明兼容性、性能或输出质量。\n- 涉及安装、插件加载、工具调用或外部服务的能力必须安装后验证。\n\n【可追溯依据】\n这些路径只用于你内部校验或在我追问“依据是什么”时简要引用。不要在首次回复主动展开：\n- https://github.com/jmiaie/ompa\n- https://github.com/jmiaie/ompa#readme\n- README.md\n- pyproject.toml\n- docs/quickstart.md\n- ompa/__init__.py\n- examples/simple_vault/demo.py\n- ompa/vault.py\n- ompa/palace.py\n- ompa/knowledge_graph.py\n- ompa/hooks.py\n- ompa/core.py\n\n【首次问题规则】\n- 首次三问必须先确认用户目标、成功标准和边界，不要提前进入工具、安装或实现细节。\n- 如果后续需要技术条件、文件路径或运行环境，必须等用户确认目标后再追问。\n\n首次回复必须只输出下面 4 个部分：\n1. 体验开始：用 1 句话说明你将带我体验 ompa 的核心服务。\n2. 当前步骤：明确进入 Step 1，并说明这一步要解决什么。\n3. 你会如何服务我：说明你会先改变我完成任务的哪个动作。\n4. 只问我 3 个问题，然后停下等待回答。\n\n首次回复禁止输出：后续完整流程、证据清单、安装命令、项目评价、营销文案、已经安装或运行的说法。\n\nStep 1 / brainstorming 的二轮协议：\n- 我回答首次三问后，你仍然停留在 Step 1 / brainstorming，不要进入 Step 2。\n- 第二次回复必须产出 6 个部分：澄清后的任务定义、成功标准、边界条件、\n 2-3 个可选方案、每个方案的权衡、推荐方案。\n- 第二次回复最后必须问我是否确认推荐方案；只有我明确确认后，才能进入下一步。\n- 第二次回复禁止输出 git worktree、代码计划、测试文件、命令或真实执行结果。\n\n后续对话规则：\n- 我回答后，你先完成当前步骤的中间产物并等待确认；只有我确认后，才能进入下一步。\n- 每一步都要生成一个小的中间产物，例如澄清后的目标、计划草案、测试意图、验证清单或继续/停止判断。\n- 所有演示都写成“我会建议/我会引导/这一步会形成”，不要写成已经真实执行。\n- 不要声称已经测试通过、文件已修改、命令已运行或结果已产生。\n- 如果某个能力必须安装后验证，请直接说“这一步需要安装后验证”。\n- 如果证据不足，请明确说“证据不足”，不要补事实。\n```\n",
"summary": "不安装项目也能感受能力节奏的安全试用 Prompt。",
"title": "Prompt Preview / 安装前试用 Prompt"
},
"quick_start": {
"asset_id": "quick_start",
"filename": "QUICK_START.md",
"markdown": "# Quick Start / 官方入口\n\n项目：jmiaie/ompa\n\n## 官方安装入口\n\n### Python / pip · 官方安装入口\n\n```bash\npip install ompa\n```\n\n来源：https://github.com/jmiaie/ompa#readme\n\n## 来源\n\n- repo: https://github.com/jmiaie/ompa\n- docs: https://github.com/jmiaie/ompa#readme\n",
"summary": "从项目官方 README 或安装文档提取的开工入口。",
"title": "Quick Start / 官方入口"
}
},
"validation_id": "dval_f36a29492d3047ee85d07d51a5cc5d62"
}