# https://github.com/jmiaie/ompa 项目说明书 生成时间：2026-05-13 05:17:58 UTC ## 目录 - [项目介绍](#intro) - [快速入门](#quickstart) - [三层架构设计](#three-layer-design) - [生命周期钩子](#lifecycle-hooks) - [Vault存储层](#vault) - [Palace元数据层](#palace) - [时序知识图谱](#knowledge-graph) - [消息分类器](#classifier) - [MCP服务器集成](#mcp-server) - [框架适配器](#adapters) ## 项目介绍 ### 相关页面 相关主题：[快速入门](#quickstart), [三层架构设计](#three-layer-design)
相关源码文件 以下源码文件用于生成本页说明： - [README.md](https://github.com/jmiaie/ompa/blob/main/README.md) - [CLAUDE.md](https://github.com/jmiaie/ompa/blob/main/CLAUDE.md) - [CONTRIBUTING.md](https://github.com/jmiaie/ompa/blob/main/CONTRIBUTING.md) - [CHANGELOG.md](https://github.com/jmiaie/ompa/blob/main/CHANGELOG.md) - [STABILITY.md](https://github.com/jmiaie/ompa/blob/main/STABILITY.md) - [examples/mcp_desktop/README.md](https://github.com/jmiaie/ompa/blob/main/examples/mcp_desktop/README.md) - [ompa/core.py](https://github.com/jmiaie/ompa/blob/main/ompa/core.py) - [ompa/classifier.py](https://github.com/jmiaie/ompa/blob/main/ompa/classifier.py)
# 项目介绍 ## 概述 **OMPA**（Obsidian-MemPalace-Agnostic）是一个专为 AI Agent 设计的记忆管理系统，旨在为 Claude Code、OpenClaw、Codex 等 Agent 框架提供持久化记忆能力。项目最初从 [MemPalace](https://github.com/corbt/mem_palace) 启发而来，并融合了 obsidian-mind 等社区项目的优秀理念。 资料来源：[README.md:1]() OMPA 的核心理念是**逐字存储**（verbatim storage）而非摘要，确保记忆的完整性和可追溯性。根据 MemPalace 的研究验证，逐字存储方案可达到 96.6% 的检索准确率（Recall@5）。 资料来源：[CLAUDE.md:1]() ## 核心定位 OMPA 解决的核心问题是：**AI Agent 在长时间会话中如何有效管理、检索和利用历史信息**。 传统 Agent 框架面临以下挑战： | 挑战 | OMPA 解决方案 | |------|--------------| | 上下文窗口有限 | 分层记忆架构，按需注入相关上下文 | | 记忆检索困难 | 语义搜索 + 知识图谱双引擎 | | 团队/个人内容混淆 | 双保险库（Dual-Vault）隔离机制 | | 框架绑定 | 纯 Python 实现，无 Agent SDK 依赖 | 资料来源：[README.md:1]() ## 技术架构 ### 整体架构图 ```mermaid graph TB subgraph "Agent Layer" ClaudeCode[Claude Code] OpenClaw[OpenClaw] Codex[Codex] GeminiCLI[Gemini CLI] end subgraph "OMPA Core" Core[Ompa 核心类] Classifier[消息分类器] Hooks[生命周期钩子] end subgraph "Storage Layer" Vault[(Vault
记忆存储)] Palace[(Palace
宫殿元数据)] KG[(Knowledge Graph
时序知识图谱)] Semantic[Semantic Index
语义索引] end ClaudeCode --> Core OpenClaw --> Core Codex --> Core GeminiCLI --> Core Core --> Classifier Core --> Hooks Core --> Vault Core --> Palace Core --> KG Core --> Semantic ``` ### 模块说明 | 模块 | 文件路径 | 职责 | |------|---------|------| | **core.py** | `ompa/core.py` | Ompa 主类 — 生命周期管理、消息处理、双保险库 | | **vault.py** | `ompa/vault.py` | 保险库管理 — brain/work/org/perf 文件夹 CRUD | | **palace.py** | `ompa/palace.py` | 宫殿元数据 — wings/rooms/drawers/halls/tunnels | | **knowledge_graph.py** | `ompa/knowledge_graph.py` | 时序知识图谱 — SQLite 三元组 + 有效期窗口 | | **hooks.py** | `ompa/hooks.py` | 5 个生命周期钩子 + HookManager | | **classifier.py** | `ompa/classifier.py` | 15 种消息类型 + 自动路由 | | **semantic.py** | `ompa/semantic.py` | 本地语义搜索（延迟模型加载） | | **mcp_server.py** | `ompa/mcp_server.py` | MCP 协议服务器（15 个工具） | | **config.py** | `ompa/config.py` | 双保险库配置 | | **cli.py** | `ompa/cli.py` | Typer CLI（14 个命令） | 资料来源：[README.md:1]() ## 核心功能特性 ### 1. 双保险库架构（Dual-Vault） OMPA 支持将团队/组织内容与个人/私密笔记隔离存储： ```python from ompa import Ompa, DualVaultConfig, IsolationMode config = DualVaultConfig( shared_vault="./team-vault", personal_vault="./private-vault", mode=IsolationMode.AUTO, ) ao = Ompa(config=config) ``` **隔离模式（IsolationMode）**： | 模式 | 说明 | |------|------| | `AUTO` | 根据消息类型自动分类到共享或个人保险库 | | `MANUAL` | 每个操作显式指定 `VaultTarget` | | `STRICT` | 强制隔离，不允许跨保险库访问 | 资料来源：[README.md:1]() ### 2. 消息自动分类 OMPA 内置 15 种消息类型分类器，自动识别并路由消息到对应文件夹： ```mermaid graph LR Input[用户消息] --> Classifier[Classifier] Classifier --> DEC[DECISION] Classifier --> INC[INCIDENT] Classifier --> WIN[WIN] Classifier --> O1O[ONE_ON_ONE] Classifier --> Q[QUESTION] Classifier --> OTHER[...] ``` **消息类型列表**： | 枚举值 | 触发关键词 | 路由目标 | |--------|-----------|---------| | `DECISION` | decided, agreed, settled | brain/decisions/ | | `INCIDENT` | incident, outage, bug | brain/incidents/ | | `WIN` | won, shipped, launched | brain/wins/ | | `ONE_ON_ONE` | 1:1, feedback, career | org/1on1/ | | `MEETING` | meeting, standup | org/meetings/ | | `PROJECT_UPDATE` | project, blocked, sprint | org/projects/ | | `PERSON_INFO` | teammate, joined, role | org/people/ | | `QUESTION` | how do, what is, why | brain/questions/ | | `TASK` | todo, action item | work/tasks/ | | `ARCHITECTURE` | architecture, design | brain/architecture/ | | `CODE` | code, function, PR | brain/code/ | | `BRAIN_DUMP` | dump, stream | brain/dumps/ | | `WRAP_UP` | wrap up, end session | brain/sessions/ | | `STANDUP` | standup, daily | org/standups/ | 资料来源：[ompa/classifier.py:1]() ### 3. 时序知识图谱（Temporal Knowledge Graph） KG 使用 SQLite 存储三元组，支持时间维度查询： ```python # 添加带时间窗口的三元组 ao.kg.add_triple("Kai", "works_on", "Orion", valid_from="2025-06-01") # 查询实体历史 triples = ao.kg.query_entity("Kai") # 查询时间线 timeline = ao.kg.timeline("Orion") ``` **数据模型**： ``` Triple(subject, predicate, object, valid_from, valid_to, confidence, source_file) ``` 资料来源：[README.md:1]() ### 4. 本地语义搜索 OMPA 提供本地语义索引，无需 API 调用即可实现语义搜索： ```python results = ao.search("authentication decisions", wing="Orion") ``` **特性**： - 延迟加载模型，首次访问时才下载 - 增量索引，仅重新嵌入修改过的文件 - 支持 wing/room 级别的范围搜索 资料来源：[README.md:1]() ### 5. 生命周期钩子系统 支持 5 个生命周期钩子，允许自定义扩展： ```python class MyHook(Hook): def __init__(self): super().__init__("my_hook", token_budget=50) def execute(self, context: HookContext, **kwargs) -> HookResult: return HookResult(hook_name=self.name, success=True, output="...", tokens_hint=50) ao = Ompa("./workspace") ao.hooks.register_hook("my_hook", MyHook()) ``` 资料来源：[CLAUDE.md:1]() ## 安装与使用 ### 安装方式 ```bash # 核心功能 pip install ompa # 含本地语义搜索（首次运行下载约 500MB 模型） pip install ompa[all] # 开发模式 pip install ompa[dev] ``` **环境要求**：Python 3.10+ 资料来源：[README.md:1]() ### CLI 命令参考 | 命令 | 功能 | |------|------| | `ao init` | 初始化新保险库 | | `ao status` | 健康检查和统计 | | `ao session-start` | 注入记忆上下文 | | `ao classify ` | 分类并路由消息 | | `ao search ` | 语义搜索 | | `ao orphans` | 检测孤立笔记 | | `ao wrap-up` | 会话总结并保存 | | `ao wings` | 列出宫殿 wing | | `ao rooms ` | 列出 wing 中的房间 | | `ao tunnel` | 创建/穿越跨 wing 隧道 | | `ao kg-query ` | 查询知识图谱 | | `ao validate` | 验证保险库结构 | | `ao rebuild-index` | 重建语义索引 | 资料来源：[README.md:1]() ### MCP 集成 OMPA 提供 MCP（Model Context Protocol）服务器，可与 Claude Desktop、Cursor、Windsurf 等 IDE 集成： ```bash # Claude Desktop claude mcp add ompa -- python -m ompa.mcp_server # 或手动配置 ~/.claude/claude_desktop_config.json { "mcpServers": { "ompa": { "command": "python", "args": ["-m", "ompa.mcp_server"], "env": { "OMPA_VAULT_PATH": "/absolute/path/to/vault" } } } } ``` **MCP 工具列表**： ``` ao_session_start, ao_classify, ao_search, ao_kg_query, ao_kg_add, ao_kg_stats, ao_palace_wings, ao_palace_rooms, ao_palace_tunnel, ao_validate, ao_wrap_up, ao_status, ao_orphans, ao_init ``` 资料来源：[examples/mcp_desktop/README.md:1]() ## Python API 基础用法 ```python from ompa import Ompa ao = Ompa(vault_path="./workspace") # 会话生命周期 context = ao.session_start() # 返回约 2K token 的上下文字符串 hint = ao.handle_message("We won the enterprise deal!") ao.post_tool("write", {"file_path": "work/active/auth.md"}) ao.stop() # 语义搜索 results = ao.search("authentication decisions", wing="Orion") # 知识图谱 ao.kg.add_triple("Kai", "works_on", "Orion", valid_from="2025-06-01") triples = ao.kg.query_entity("Kai") timeline = ao.kg.timeline("Orion") ``` 资料来源：[README.md:1]() ## 框架兼容性 | Agent 框架 | 集成方式 | |-----------|---------| | Claude Code | Python API + MCP 服务器 | | OpenClaw | Python API + MCP 服务器 | | Codex | Python API + MCP 服务器 | | Gemini CLI | Python API + MCP 服务器 | | LangChain | Python API | 资料来源：[README.md:1]() ## 适配器生态 OMPA 提供多种官方适配器，便于与其他生态系统集成： ```python # LangChain 适配器 from ompa.adapters.langchain import OmpaMemory, OmpaRetriever # LlamaIndex 适配器 from ompa.adapters.llamaindex import OmpaReader, OmpaVaultRetriever # OpenAI Agents SDK 适配器 from ompa.adapters.openai_agents import OmpaAgentHooks # FAISS 向量索引 from ompa.adapters.faiss import FAISSSemanticIndex ``` 资料来源：[STABILITY.md:1]() ## 版本历史 | 版本 | 日期 | 主要变更 | |------|------|---------| | 0.4.x | 2026-04 | 双保险库架构、路径遍历加固、语义延迟初始化 | | 0.3.x | 2026-04 | KG 自动填充、增量语义索引、脑图同步 | | 0.2.x | 2026-04 | 项目重命名 AgnosticObsidian → Ompa | | 0.1.x | 2026-04 | 初始版本发布 | 资料来源：[CHANGELOG.md:1]() ## 安全特性 | 特性 | 说明 | |------|------| | 路径遍历防护 | 所有保险库文件操作解析并边界检查路径 | | UTF-8 编码强制 | 所有文件写入显式指定 UTF-8 编码 | | 敏感信息过滤 | 导出时自动清除个人标识符 | 资料来源：[CHANGELOG.md:1]() ## 开发指南 ### 本地开发 ```bash git clone https://github.com/jmiaie/ompa cd ompa pip install -e ".[dev,all]" # 运行测试 pytest tests/ -v # 代码检查 ruff check ompa/ ruff format ompa/ ``` 资料来源：[CONTRIBUTING.md:1]() ### 添加新消息类型 1. 在 `classifier.py` 中添加 `MessageType` 枚举值 2. 添加正则模式到 `PATTERNS[MessageType]` 3. 添加路由提示到 `ROUTING_HINTS[MessageType]` 4. 添加文件夹映射到 `FOLDER_MAP[MessageType]` 5. 在 `tests/test_ompa.py` 中添加测试用例 资料来源：[CONTRIBUTING.md:1]() ## 架构设计决策 | 决策 | 说明 | |------|------| | 延迟语义加载 | `SemanticIndex._model` 在首次访问时加载 | | 框架无关性 | 纯 Python，无 Agent SDK 依赖 | | 保险库 + 宫殿双层 | 保险库为数据源，宫殿为检索加速层 | | 逐字存储 | 不做摘要，MemPalace 验证 96.6% R@5 | | 时序知识图谱 | SQLite 三元组 + 有效期窗口 | | 路径遍历守卫 | 所有文件操作解析 + 边界检查 | | 上下文管理器 | SQLite 连接使用 `with` 确保无泄漏 | 资料来源：[CLAUDE.md:1]() ## 致谢 OMPA 是 AI Agent 记忆社区优秀理念的集大成者： - **[MemPalace](https://github.com/corbt/mem_palace)** by Kyle Corbitt — 宫殿隐喻（wings/rooms/drawers/halls/tunnels） - **obsidian-mind** — Obsidian 记忆系统 - **Claude Code** — Agent 框架参考 - **OpenClaw** — Agent 框架参考 资料来源：[README.md:1]() --- ## 快速入门 ### 相关页面 相关主题：[项目介绍](#intro)
相关源码文件 以下源码文件用于生成本页说明： - [README.md](https://github.com/jmiaie/ompa/blob/main/README.md) - [examples/mcp_desktop/README.md](https://github.com/jmiaie/ompa/blob/main/examples/mcp_desktop/README.md) - [CONTRIBUTING.md](https://github.com/jmiaie/ompa/blob/main/CONTRIBUTING.md) - [STABILITY.md](https://github.com/jmiaie/ompa/blob/main/STABILITY.md) - [CLAUDE.md](https://github.com/jmiaie/ompa/blob/main/CLAUDE.md) - [ompa/core.py](https://github.com/jmiaie/ompa/blob/main/ompa/core.py) - [ompa/mcp_server.py](https://github.com/jmiaie/ompa/blob/main/ompa/mcp_server.py)
# 快速入门 本文档面向希望快速上手 OMPA（Obsidian-MemPalace-Agnostic）的开发者。OMPA 是一个与框架无关的 AI Agent 记忆系统，提供 Vault 存储、Palace 记忆加速和 Temporal Knowledge Graph 功能。 ## 环境要求 | 要求 | 版本/说明 | |------|----------| | Python | 3.10+ | | pip | 最新版 | > 资料来源：[README.md:1]() ## 安装 OMPA 提供多种安装方式，可根据需求选择： ```bash # 仅核心功能（vault + palace + KG + CLI + MCP server） pip install ompa # 包含本地语义搜索（首次运行需下载约 500MB 模型） pip install ompa[all] # 开发版本 pip install ompa[dev] # 从源码安装 git clone https://github.com/jmiaie/ompa && cd ompa pip install -e ".[all]" ``` > 资料来源：[README.md:50-60]() ## 核心概念 在开始之前，了解 OMPA 的三个核心组件： ```mermaid graph TD A[Ompa 核心类] --> B[Vault 存储层] A --> C[Palace 检索加速] A --> D[Knowledge Graph 时序图谱] B --> B1[Brain Notes] B --> B2[Work Notes] B --> B3[Org Notes] B --> B4[Perf Notes] C --> C1[Wings 区域] C --> C2[Rooms 房间] C --> C3[Drawers 抽屉] D --> D1[Triples 三元组] D --> D2[Validity Windows 有效期] ``` > 资料来源：[CLAUDE.md:1]() | 组件 | 功能 | 数据存储 | |------|------|---------| | **Vault** | 笔记源文件管理 | Markdown 文件 + frontmatter | | **Palace** | 记忆结构化加速 | `.palace/` 元数据 | | **Knowledge Graph** | 时序关系图谱 | SQLite 数据库 | > 资料来源：[README.md:65-80]() ## 初始化 Vault Vault 是 OMPA 的源数据存储目录，包含 Brain、Work、Org、Perf 四个笔记分区。 ```bash # 初始化新的 vault ao init # 检查 vault 健康状态 ao status ``` 初始化后，将创建以下目录结构： ``` . ├── .ompa/ │ └── config.yaml ├── brain/ ├── work/ ├── org/ └── perf/ ``` > 资料来源：[examples/mcp_desktop/README.md:1-10]() ## CLI 快速命令 OMPA 提供完整的命令行工具： ```bash # 会话管理 ao session-start # 启动会话，注入约 2K token 上下文 ao wrap-up # 会话总结并保存 # 笔记操作 ao classify # 分类并路由消息 ao search # 语义搜索 # 知识图谱 ao kg-query # 查询实体 ao kg-timeline # 实体时间线 ao kg-stats # 图谱统计 # Palace 导航 ao wings # 列出所有区域 ao rooms # 列出区域中的房间 ao tunnel # 创建/遍历跨区域通道 # 工具 ao orphans # 检测孤立笔记 ao validate # 验证 vault 结构 ao rebuild-index # 重建语义索引 ``` > 资料来源：[README.md:25-45]() ## Python API 使用 ### 基本使用流程 ```python from ompa import Ompa # 初始化 ao = Ompa(vault_path="./workspace") # 会话生命周期 context = ao.session_start() # 获取上下文（约 2K tokens） hint = ao.handle_message("消息内容") # 处理消息 ao.stop() # 停止会话 # 语义搜索 results = ao.search("认证决策", wing="Orion") # 知识图谱 ao.kg.add_triple("Kai", "works_on", "Orion", valid_from="2025-06-01") triples = ao.kg.query_entity("Kai") timeline = ao.kg.timeline("Orion") ``` > 资料来源：[README.md:70-90]() ### Ompa 核心类初始化参数 ```python from ompa import Ompa ao = Ompa( vault_path="./workspace", # Vault 路径 agent_name="agent", # Agent 名称（用于 KG 实体限定） enable_semantic=True, # 启用语义搜索 embedding_backend=None, # 嵌入后端 ) ``` | 参数 | 类型 | 默认值 | 说明 | |------|------|--------|------| | `vault_path` | `str` | 必需 | Vault 根目录路径 | | `agent_name` | `str` | `"agent"` | Agent 标识符 | | `enable_semantic` | `bool` | `False` | 启用本地语义搜索 | | `embedding_backend` | `EmbeddingBackend` | `None` | 自定义嵌入后端 | > 资料来源：[STABILITY.md:10-25]() ## 双 Vault 模式 OMPA 支持双 Vault 架构，用于隔离团队/组织内容与个人/私密笔记。 ```python from ompa import Ompa, DualVaultConfig, IsolationMode config = DualVaultConfig( shared_vault="./team-vault", # 共享 vault personal_vault="./private-vault", # 个人 vault mode=IsolationMode.AUTO, # 自动分类模式 ) ao = Ompa(config=config) ``` ### 隔离模式 | 模式 | 说明 | |------|------| | `AUTO` | 根据消息类型自动分类到共享或个人 vault | | `MANUAL` | 显式指定 `VaultTarget` 进行路由 | | `STRICT` | 严格分离，仅允许指定 vault 操作 | > 资料来源：[README.md:55-65]() ### 环境变量配置 | 变量 | 默认值 | 说明 | |------|--------|------| | `OMPA_VAULT_PATH` | `.` | Vault 绝对路径 | | `OMPA_ENABLE_SEMANTIC` | `false` | 启用本地语义搜索 | | `OMPA_AGENT_NAME` | `agent` | Agent 名称 | | `OMPA_SHARED_VAULT` | — | 双 Vault 模式下共享 vault 路径 | | `OMPA_PERSONAL_VAULT` | — | 双 Vault 模式下个人 vault 路径 | > 资料来源：[examples/mcp_desktop/README.md:50-60]() ## MCP 服务器集成 OMPA 提供 MCP（Model Context Protocol）服务器，可与 Claude Desktop、Cursor、Windsurf 等工具集成。 ### Claude Desktop 配置 **方式一：CLI（推荐）** ```bash claude mcp add ompa -- python -m ompa.mcp_server ``` **方式二：手动配置** 编辑 `~/.claude/claude_desktop_config.json`： ```json { "mcpServers": { "ompa": { "command": "python", "args": ["-m", "ompa.mcp_server"], "env": { "OMPA_VAULT_PATH": "/absolute/path/to/your/vault" } } } } ``` ### Cursor / Windsurf 配置 创建 `.cursor/mcp.json` 或 `.windsurf/mcp.json`： ```json { "mcpServers": { "ompa": { "command": "python", "args": ["-m", "ompa.mcp_server"], "env": { "OMPA_VAULT_PATH": "${workspaceFolder}/.ompa-vault", "OMPA_ENABLE_SEMANTIC": "false" } } } } ``` ### MCP 可用工具 | 工具 | 功能 | |------|------| | `ao_session_start` | 启动会话并注入记忆上下文 | | `ao_classify` | 分类消息并返回路由建议 | | `ao_search` | 语义搜索笔记 | | `ao_kg_query` | 查询知识图谱实体 | | `ao_kg_add` | 添加三元组到知识图谱 | | `ao_kg_stats` | 知识图谱统计 | | `ao_palace_wings` | 列出所有 Palace 区域 | | `ao_palace_rooms` | 列出区域中的房间 | | `ao_palace_tunnel` | 创建跨区域通道 | | `ao_validate` | 验证笔记结构 | | `ao_wrap_up` | 会话总结 | | `ao_status` | Vault 健康状态 | | `ao_orphans` | 检测孤立笔记 | | `ao_init` | 初始化 vault | | `ao_sync` | 同步 vault | | `ao_write` | 写入笔记 | | `ao_export` / `ao_import` | 导入导出笔记 | > 资料来源：[ompa/mcp_server.py:1-50]() ## 消息分类系统 OMPA 内置 15 种消息类型分类器，可自动将消息路由到正确的 vault 文件夹： ```bash ao classify "We decided to go with Postgres" ``` 分类系统基于正则模式、路由提示和文件夹映射自动工作： 1. 添加枚举值到 `MessageType` 2. 添加正则模式到 `PATTERNS` 3. 添加路由提示到 `ROUTING_HINTS` 4. 添加文件夹映射到 `FOLDER_MAP` > 资料来源：[CONTRIBUTING.md:25-35]() ## 项目结构 ``` ompa/ ├── core.py # Ompa 主类 — 生命周期、钩子、双 Vault ├── vault.py # Vault CRUD 操作 ├── palace.py # Palace 元数据（区域/房间/抽屉/大厅/通道） ├── knowledge_graph.py # 时序知识图谱（SQLite 三元组） ├── hooks.py # 5 个生命周期钩子 + HookManager ├── classifier.py # 15 种消息类型自动路由 ├── semantic.py # 本地语义搜索（惰性模型加载） ├── mcp_server.py # MCP 协议服务器（15 个工具） ├── config.py # 双 Vault 配置 └── cli.py # Typer CLI（14 个命令） ``` > 资料来源：[README.md:65-80]() ## 下一步 - 阅读 [CLAUDE.md](https://github.com/jmiaie/ompa/blob/main/CLAUDE.md) 了解架构决策 - 查看 [STABILITY.md](https://github.com/jmiaie/ompa/blob/main/STABILITY.md) 了解 API 稳定性承诺 - 参考 [CONTRIBUTING.md](https://github.com/jmiaie/ompa/blob/main/CONTRIBUTING.md) 参与贡献 --- ## 三层架构设计 ### 相关页面 相关主题：[生命周期钩子](#lifecycle-hooks), [Vault存储层](#vault), [Palace元数据层](#palace), [时序知识图谱](#knowledge-graph)
相关源码文件 以下源码文件用于生成本页说明： - [ompa/vault.py](https://github.com/jmiaie/ompa/blob/main/ompa/vault.py) - [ompa/palace.py](https://github.com/jmiaie/ompa/blob/main/ompa/palace.py) - [ompa/knowledge_graph.py](https://github.com/jmiaie/ompa/blob/main/ompa/knowledge_graph.py) - [ompa/core.py](https://github.com/jmiaie/ompa/blob/main/ompa/core.py) - [ompa/semantic.py](https://github.com/jmiaie/ompa/blob/main/ompa/semantic.py)
# 三层架构设计 OMPA（Obsidian-MemPalace-Agnostic）采用**三层架构设计**，将AI Agent的记忆系统分解为三个职责明确的层次：数据持久层（Vault）、元数据加速层（Palace）和时序推理层（Knowledge Graph）。这种设计遵循"Vault是事实来源，Palace是检索加速"的核心原则，实现了数据存储与高效检索的分离。 ## 架构概览 ```mermaid graph TB subgraph 数据层 "第一层：Vault（数据持久层）" VAULT["Vault Manager
brain/work/org/perf"] FILES["文件系统
Markdown + Frontmatter"] end subgraph 加速层 "第二层：Palace（元数据加速层）" PALACE["Palace Manager
wings/rooms/drawers"] INDEX["语义索引
sentence-transformers"] end subgraph 推理层 "第三层：Knowledge Graph（时序推理层）" KG["Knowledge Graph
SQLite Triples"] TEMPORAL["时序窗口
valid_from/valid_to"] end USER["> 用户/Agent"] USER --> VAULT USER --> PALACE USER --> KG VAULT --> FILES PALACE --> INDEX KG --> TEMPORAL FILES -.->|"populate"| KG INDEX -.->|"辅助"| PALACE ``` ### 三层职责对照表 | 层次 | 组件 | 职责 | 存储介质 | 数据格式 | |------|------|------|----------|----------| | 第一层 | Vault | 源数据持久化 | 文件系统 | Markdown + Frontmatter | | 第二层 | Palace | 元数据抽象 + 快速检索 | 内存 + 磁盘索引 | wings/rooms/drawers 结构 | | 第三层 | Knowledge Graph | 时序关系推理 | SQLite | 三元组 + 时效窗口 | 资料来源：[CLAUDE.md:1-15](https://github.com/jmiaie/ompa/blob/main/CLAUDE.md) ## 第一层：Vault（数据持久层） ### 设计目标 Vault层作为整个记忆系统的**事实来源（Source of Truth）**，负责持久化存储所有笔记、文档和元数据。采用原文存储策略（Verbatim Storage），不进行摘要或压缩，以保证最高的信息保真度。MemPalace的研究表明，verbatim存储在LongMemEval基准上达到了96.6%的R@5召回率。 ### 目录结构 Vault采用四象限组织结构，与obsidian-mind项目的设计保持一致： ```mermaid graph TD VAULT["Vault Root"] BRAIN["brain/
个人思考"] WORK["work/
工作项目"] ORG["org/
组织信息"] PERF["perf/
性能数据"] VAULT --> BRAIN VAULT --> WORK VAULT --> ORG VAULT --> PERF WORK --> ACTIVE["active/
活跃项目"] WORK --> ARCHIVE["archive/
归档项目"] PERF --> METRICS["metrics/
指标"] PERF --> SESSIONS["sessions/
会话记录"] ``` ### 核心功能 Vault Manager提供以下核心操作： | 操作 | 方法 | 说明 | |------|------|------| | 初始化 | `Vault(vault_path)` | 创建目录结构 | | 统计 | `get_stats()` | 返回笔记数量、文件大小等 | | 笔记列表 | `list_notes()` | 遍历所有.md文件 | | 查找孤立笔记 | `find_orphans()` | 检测broken wikilinks | 资料来源：[ompa/vault.py](https://github.com/jmiaie/ompa/blob/main/ompa/vault.py) ### Frontmatter规范 每条笔记都包含标准化的Frontmatter元数据： ```yaml --- date: "2025-06-01" tags: [authentication, postgres, enterprise] vault: shared --- ``` - `date`：创建或修改日期 - `tags`：主题标签列表 - `vault`：所属保险库（shared/personal，用于双库模式） ### 安全机制 Vault层实现了完整的路径遍历防护： ```python def _safe_resolve(base: Path, path: str) -> Path: """解析并边界检查路径""" full_path = (base / path).resolve() if not full_path.is_relative_to(base): raise ValueError("Path traversal detected") return full_path ``` 所有文件操作都必须经过路径解析和边界检查，防止恶意路径注入。 资料来源：[CHANGELOG.md:20-25](https://github.com/jmiaie/ompa/blob/main/CHANGELOG.md) ## 第二层：Palace（元数据加速层） ### 设计目标 Palace层在Vault之上构建元数据抽象，提供高效的导航和检索能力。采用宫殿隐喻（Palace Metaphor），将记忆空间组织为wings（翼）、rooms（房间）、drawers（抽屉）的层级结构，模拟人类记忆宫殿的空间记忆技巧。 ### 组织结构 ```mermaid graph LR WING["Wing（翼）
顶级分类"] ROOM["Room（房间）
次级分类"] DRAWER["Drawer（抽屉）
具体主题"] HALL["Hall（大厅）
全局连接"] TUNNEL["Tunnel（隧道）
跨翼连接"] WING --> ROOM ROOM --> DRAWER HALL -.->|"全局"| WING TUNNEL -.->|"跨域"| WING ``` ### 层级说明 | 层级 | 概念 | 用途 | 示例 | |------|------|------|------| | Wing | 翼 | 主知识领域 | Orion（猎户座命名） | | Room | 房间 | 子主题 | auth、database | | Drawer | 抽屉 | 最小单元 | postgres-config | | Hall | 大厅 | 全局索引 | 跨wing搜索 | | Tunnel | 隧道 | 跨域连接 | auth ↔ billing | 资料来源：[ompa/palace.py](https://github.com/jmiaie/ompa/blob/main/ompa/palace.py) ### Palace Manager API ```python # 创建宫殿结构 ao.palace.create_wing("Orion") # 创建翼 ao.palace.create_room("Orion", "auth") # 在翼下创建房间 ao.palace.create_tunnel("Orion", "Gemini", room="shared") # 跨翼隧道 # 导航查询 wings = ao.palace.list_wings() # 列出所有翼 rooms = ao.palace.rooms("Orion") # 列出翼下房间 stats = ao.palace.stats() # 统计信息 ``` ### 语义搜索集成 Palace层与Semantic Index深度集成，提供零API成本的本地语义搜索： ```python # Semantic Index延迟加载机制 class SemanticIndex: _model = None # 首次访问时加载 @property def model(self): if self._model is None: # 首次使用时下载并加载 all-MiniLM-L6-v2 模型 self._model = load_model() return self._model ``` 首次启用语义搜索时自动下载约90MB的句子transformer模型（约500MB包含所有依赖）。 资料来源：[ompa/semantic.py](https://github.com/jmiaie/ompa/blob/main/ompa/semantic.py) ### 增量索引 Semantic Index实现了增量更新机制，只重新索引修改过的文件： ```python # 跟踪文件修改时间 index_state = { "path/to/note.md": { "mtime": 1709234567.123, "embedding": [...] } } def needs_reindex(file_path, index_state) -> bool: """检查文件是否需要重新索引""" if file_path not in index_state: return True return getmtime(file_path) > index_state[file_path]["mtime"] ``` 资料来源：[CHANGELOG.md:45-50](https://github.com/jmiaie/ompa/blob/main/CHANGELOG.md) ## 第三层：Knowledge Graph（时序推理层） ### 设计目标 Knowledge Graph层在Vault和Palace之上构建时序知识图谱，存储实体间的三元组关系，并支持时间窗口查询。这使得系统能够回答"某个决策在特定时间点的状态"等时序相关问题。 ### 数据模型 ```mermaid graph LR subgraph 三元组结构 SUBJ["Subject
主体实体"] PRED["Predicate
关系谓词"] OBJ["Object
客体实体"] end subgraph 时序窗口 VF["valid_from
生效时间"] VT["valid_to
失效时间"] end SUBJ --> PRED PRED --> OBJ SUBJ --> VF SUBJ --> VT ``` ### SQLite存储 所有三元组存储在SQLite数据库中： ```sql CREATE TABLE triples ( id INTEGER PRIMARY KEY, subject TEXT NOT NULL, predicate TEXT NOT NULL, object TEXT NOT NULL, valid_from TEXT, valid_to TEXT, source TEXT, created_at TEXT DEFAULT CURRENT_TIMESTAMP ); CREATE INDEX idx_subject ON triples(subject); CREATE INDEX idx_valid_from ON triples(valid_from); ``` 资料来源：[ompa/knowledge_graph.py](https://github.com/jmiaie/ompa/blob/main/ompa/knowledge_graph.py) ### 核心操作 | 操作 | 方法 | 说明 | |------|------|------| | 添加三元组 | `add_triple(subject, predicate, object, valid_from, source)` | 插入新关系 | | 查询实体 | `query_entity(entity, as_of)` | 获取实体所有关系 | | 时间线 | `timeline(entity)` | 实体历史变更 | | 统计 | `stats()` | 图谱统计信息 | ### 时序查询示例 ```python # 添加带时效的三元组 ao.kg.add_triple( subject="Kai", predicate="works_on", object="Orion", valid_from="2025-06-01" # 2025年6月1日起生效 ) # 查询特定时间点的实体状态 triples = ao.kg.query_entity("Kai", as_of="2025-06-15") # 获取完整时间线 timeline = ao.kg.timeline("Kai") # 返回: [{"from": "2025-01-01", "to": "2025-05-31", "role": "lead"}, # {"from": "2025-06-01", "to": None, "role": "architect"}] ``` ### Vault自动填充 Knowledge Graph支持从Vault自动抽取知识： ```python # populate_from_vault() 扫描现有笔记 # 抽取来源包括： # 1. Frontmatter tags（如 tags: [auth, postgres]） # 2. 文件夹路径结构（如 work/active/auth/ → works_on:auth） # 3. Wikilinks（[[Note Name]] → references:Note_Name） ``` 资料来源：[CHANGELOG.md:40-45](https://github.com/jmiaie/ompa/blob/main/CHANGELOG.md) ## 三层协作机制 ### 数据流向 ```mermaid sequenceDiagram participant User as 用户/Agent participant Core as Ompa Core participant Vault as Vault Layer participant Palace as Palace Layer participant KG as KG Layer User->>Core: handle_message("决策内容") Core->>Vault: 持久化存储 Vault-->>Core: 保存成功 Core->>Palace: 分类 + 路由 Palace-->>Core: 建议文件夹 Core->>KG: 抽取实体 + 关系 KG-->>Core: 三元组已添加 User->>Core: search("认证决策") Core->>Palace: 语义搜索 Palace-->>Core: Top-K 结果 User->>Core: kg_query("Kai") Core->>KG: 时序查询 KG-->>Core: 历史状态 ``` ### 分类路由流程 消息分类器（Classifier）根据内容类型自动路由到对应文件夹： | 消息类型 | 正则模式 | 目标文件夹 | 示例 | |----------|----------|------------|------| | DECISION | `决定\|决策\|选择\|go with` | brain/decisions/ | "We decided to go with Postgres" | | CODE_CHANGE | `代码变更\|commit\|PR` | work/changes/ | "Added auth middleware" | | BLOCKER | `阻塞\|卡住\|blocked` | work/blockers/ | "Stuck on the API design" | 资料来源：[ompa/classifier.py](https://github.com/jmiaie/ompa/blob/main/ompa/classifier.py) ### 双库模式协作 在Dual-Vault模式下，三层架构扩展为六层协作： ```mermaid graph TB subgraph 共享库 "Shared Vault" SV["Shared Vault"] SP["Shared Palace"] SK["Shared KG"] end subgraph 个人库 "Personal Vault" PV["Personal Vault"] PP["Personal Palace"] PK["Personal KG"] end subgraph 隔离层 "Isolation Layer" CONFIG["DualVaultConfig"] MODE["IsolationMode"] end CONFIG --> MODE MODE -->|"AUTO"| SV MODE -->|"AUTO"| PV ``` 隔离模式说明： | 模式 | 行为 | |------|------| | `IsolationMode.AUTO` | 根据消息类型自动分类到shared或personal | | `IsolationMode.MANUAL` | 显式指定`VaultTarget`路由 | 资料来源：[ompa/core.py:30-50](https://github.com/jmiaie/ompa/blob/main/ompa/core.py) ## 生命周期钩子 三层架构通过Hooks机制与Agent生命周期集成： ```mermaid stateDiagram-v2 [*] --> session_start: 钩子1 session_start --> handle_message: 钩子2 handle_message --> post_tool: 钩子3 post_tool --> pre_compact: 钩子4 pre_compact --> stop: 钩子5 stop --> [*] ``` ### 钩子列表 | 钩子名称 | 时机 | 典型用途 | |----------|------|----------| | `on_session_start` | 会话开始 | 注入记忆上下文（~2K tokens） | | `on_message` | 消息处理 | 分类 + 持久化 | | `on_tool_call` | 工具调用 | 记录工具使用历史 | | `on_pre_compact` | 压缩前 | 准备会话摘要 | | `on_stop` | 会话结束 | 保存状态 + 更新索引 | 资料来源：[ompa/hooks.py](https://github.com/jmiaie/ompa/blob/main/ompa/hooks.py) ## 性能优化策略 ### 懒加载模式 | 组件 | 懒加载策略 | 触发条件 | |------|------------|----------| | Semantic Model | `_model = None` | 首次search调用 | | KG Connection | `with sqlite3.connect()` | 每次查询 | | Palace Index | `incremental_reindex()` | 文件修改检测 | ### 并发安全 Vault层在v0.3.1版本后支持并发访问： - SQLite连接使用context manager自动释放 - 文件操作使用原子写入（write + rename） - UTF-8编码显式指定 ### 缓存策略 ```python # 内存缓存层 class Ompa: _wings_cache: list | None = None _stats_cache: dict | None = None def list_wings(self, use_cache=True): if use_cache and self._wings_cache: return self._wings_cache self._wings_cache = self.palace.list_wings() return self._wings_cache ``` ## 总结 OMPA的三层架构设计体现了现代AI Agent记忆系统的核心设计原则： 1. **分层职责分离**：每层专注于特定职责，便于独立演进 2. **原文优先**：Vault层不压缩、不摘要，保证信息完整性 3. **时序感知**：KG层支持时间窗口查询，实现状态回溯 4. **本地优先**：语义搜索完全在本地运行，零API成本 5. **安全加固**：路径遍历防护、UTF-8显式编码、原子写入 这种架构使得OMPA能够同时满足个人知识管理和团队协作的需求，通过双库模式实现隐私隔离与知识共享的平衡。 --- ## 生命周期钩子 ### 相关页面 相关主题：[三层架构设计](#three-layer-design), [消息分类器](#classifier)
相关源码文件 以下源码文件用于生成本页说明： - [ompa/hooks.py](https://github.com/jmiaie/ompa/blob/main/ompa/hooks.py) - [ompa/core.py](https://github.com/jmiaie/ompa/blob/main/ompa/core.py) - [CONTRIBUTING.md](https://github.com/jmiaie/ompa/blob/main/CONTRIBUTING.md) - [STABILITY.md](https://github.com/jmiaie/ompa/blob/main/STABILITY.md) - [CLAUDE.md](https://github.com/jmiaie/ompa/blob/main/CLAUDE.md)
# 生命周期钩子 OMPA 的生命周期钩子系统允许开发者在会话关键节点插入自定义逻辑，实现消息处理、工具调用和会话收尾等流程的扩展与定制。 ## 核心概念 OMPA 定义了 5 个生命周期钩子点，分别对应会话的不同阶段： | 钩子名称 | 触发时机 | 返回类型 | |---------|---------|---------| | `session_start` | 会话初始化时 | `HookResult` | | `handle_message` | 每条消息处理时 | `HookResult` | | `post_tool` | 工具调用完成后 | `HookResult` | | `pre_compact` | 上下文压缩前 | `HookResult` | | `stop` / `wrap_up` | 会话结束时 | `HookResult` | ## 系统架构 ```mermaid graph TD A[Ompa 实例] --> B[HookManager] B --> C[Hook 1] B --> D[Hook 2] B --> E[Hook N] F[触发时机] --> G[session_start] F --> H[handle_message] F --> I[post_tool] F --> J[pre_compact] F --> K[stop] G --> B H --> B I --> B J --> B K --> B ``` ## 核心类 ### Hook 基类 所有自定义钩子需继承 `Hook` 基类： ```python from ompa.hooks import Hook, HookContext, HookResult class MyHook(Hook): def __init__(self): super().__init__("my_hook", token_budget=50) def execute(self, context: HookContext, **kwargs) -> HookResult: return HookResult( hook_name=self.name, success=True, output="...", tokens_hint=50 ) ``` 构造函数参数： | 参数 | 类型 | 说明 | |-----|------|-----| | `name` | `str` | 钩子唯一标识名 | | `token_budget` | `int` | 该钩子预计消耗的 token 上限 | ### HookContext 传递给钩子执行器的上下文对象，包含当前会话状态信息。 ### HookResult 钩子执行结果的返回结构： | 字段 | 类型 | 说明 | |-----|------|-----| | `hook_name` | `str` | 执行钩子的名称 | | `success` | `bool` | 执行是否成功 | | `output` | `str` | 钩子输出内容 | | `tokens_hint` | `int` | 预估 token 消耗 | | `error` | `str` | 错误信息（可选） | ## HookManager `HookManager` 负责管理所有已注册的钩子实例，提供注册和执行接口。 ```python from ompa.hooks import HookManager # 获取 HookManager 实例 hook_manager = ao.hooks hook_manager.register_hook("my_hook", MyHook()) ``` ## 注册自定义钩子 ```python from ompa import Ompa from ompa.hooks import Hook, HookContext, HookResult class LoggingHook(Hook): def __init__(self): super().__init__("logging_hook", token_budget=10) def execute(self, context: HookContext, **kwargs) -> HookResult: message = kwargs.get("message", "") print(f"[LOG] Processing: {message[:50]}") return HookResult( hook_name=self.name, success=True, output="Logged successfully", tokens_hint=10 ) # 创建实例并注册钩子 ao = Ompa("./workspace") ao.hooks.register_hook("logging", LoggingHook()) ``` ## 钩子执行流程 ```mermaid sequenceDiagram participant User as 用户代码 participant Ompa as Ompa 实例 participant HM as HookManager participant Hook as 自定义钩子 User->>Ompa: session_start() / handle_message() Ompa->>HM: 执行钩子链 HM->>Hook: execute(context, **kwargs) Hook-->>HM: HookResult HM-->>Ompa: 聚合结果 Ompa-->>User: HookResult ``` ## 与 Ompa 核心集成 `Ompa` 类的公共 API 均返回 `HookResult`： ```python from ompa import Ompa ao = Ompa(vault_path="./workspace") # 所有方法返回 HookResult context = ao.session_start() # HookResult result = ao.handle_message("msg") # HookResult result = ao.post_tool("write", {"file_path": "test.md"}) # HookResult result = ao.pre_compact(transcript) # HookResult ao.stop() # HookResult ao.wrap_up() # HookResult (stop 的别名) ao.standup() # HookResult (session_start 的别名) ``` ## 完整示例 ```python from ompa import Ompa from ompa.hooks import Hook, HookContext, HookResult import time class TimingHook(Hook): def __init__(self): super().__init__("timing", token_budget=5) self.start_time = None def execute(self, context: HookContext, **kwargs) -> HookResult: if self.start_time is None: self.start_time = time.time() msg = "Timer started" else: elapsed = time.time() - self.start_time msg = f"Session duration: {elapsed:.1f}s" return HookResult( hook_name=self.name, success=True, output=msg, tokens_hint=5 ) # 使用 ao = Ompa("./workspace") ao.hooks.register_hook("timing", TimingHook()) ao.session_start() # ... 会话操作 ... ao.wrap_up() ``` ## 注意事项 1. **token_budget 建议值**：每个钩子的 `token_budget` 用于上下文管理规划，建议设置实际消耗的近似值 2. **异常处理**：钩子执行失败时返回 `success=False`，但不会中断主流程 3. **返回值聚合**：`HookManager` 会聚合多个钩子的结果 4. **注册时机**：建议在 `Ompa` 实例创建后立即注册钩子 ## 稳定性说明 > `ompa.hooks.*Hook` 类为内部实现类，可能在次版本中变更。建议使用 `HookManager.register_hook()` 接口进行注册 资料来源：[STABILITY.md]() ## 相关文件 | 文件 | 说明 | |-----|------| | `ompa/hooks.py` | 钩子系统核心实现 | | `ompa/core.py` | `Ompa` 主类与钩子集成 | | `CONTRIBUTING.md` | 自定义钩子开发指南 | --- ## Vault存储层 ### 相关页面 相关主题：[三层架构设计](#three-layer-design), [消息分类器](#classifier)
相关源码文件 以下源码文件用于生成本页说明： - [ompa/vault.py](https://github.com/jmiaie/ompa/blob/main/ompa/vault.py) - [ompa/core.py](https://github.com/jmiaie/ompa/blob/main/ompa/core.py) - [ompa/config.py](https://github.com/jmiaie/ompa/blob/main/ompa/config.py) - [ompa/knowledge_graph.py](https://github.com/jmiaie/ompa/blob/main/ompa/knowledge_graph.py) - [ompa/semantic.py](https://github.com/jmiaie/ompa/blob/main/ompa/semantic.py) - [CLAUDE.md](https://github.com/jmiaie/ompa/blob/main/CLAUDE.md) - [SECURITY_AUDIT.md](https://github.com/jmiaie/ompa/blob/main/SECURITY_AUDIT.md) - [CHANGELOG.md](https://github.com/jmiaie/ompa/blob/main/CHANGELOG.md)
# Vault存储层 Vault存储层是OMPA系统的核心数据持久化组件，负责管理所有笔记、文件、元数据和知识图谱的本地存储。作为系统的"事实来源（Source of Truth）"，Vault层采用了严格的安全防护机制和双保险库架构，为AI Agent提供可靠、可隔离的长期记忆存储。 ## 核心职责 Vault存储层承担以下核心职责： | 职责类别 | 具体功能 | |---------|---------| | 文件管理 | 笔记的创建、读取、更新、删除（CRUD操作） | | 结构组织 | 按消息类型分类笔记（brain/work/org/perf等） | | 安全防护 | 路径遍历攻击防护、UTF-8编码强制 | | 双保险库 | 共享库与个人库的隔离管理 | | 语义索引 | 文件修改时间跟踪与增量嵌入 | | 元数据管理 | Frontmatter解析与存储 | > 资料来源：[CLAUDE.md:7]() ## 架构设计 ### 双层存储架构 OMPA采用Vault + Palace的双层存储架构： - **Vault层**：数据的唯一事实来源，负责原始笔记和文件的持久化存储 - **Palace层**：作为检索加速层，提供宫殿式记忆结构（wings/rooms/drawers/halls/tunnels）来优化信息检索效率 ```mermaid graph TD A[用户/Agent] --> B[Ompa Core API] B --> C{Mode选择} C -->|单库模式| D[Vault单实例] C -->|双库模式| E[Shared Vault] C -->|双库模式| F[Personal Vault] D --> G[文件系统] E --> H[文件系统 - 共享区域] F --> I[文件系统 - 个人区域] G --> J[.palace/ 目录结构] H --> J I --> J J --> K[Knowledge Graph SQLite] J --> L[Semantic Index] ``` > 资料来源：[CLAUDE.md:7](), [README.md:Package Structure]() ### 双保险库架构（Dual-Vault） 从v0.4.0开始，OMPA支持双保险库架构，允许在共享保险库和个人保险库之间隔离数据： ```python from ompa import Ompa, DualVaultConfig, IsolationMode config = DualVaultConfig( shared_vault="./team-vault", personal_vault="./private-vault", mode=IsolationMode.AUTO, # 或 IsolationMode.MANUAL ) ao = Ompa(config=config) ``` #### 隔离模式 | 模式 | 行为描述 | |------|---------| | `IsolationMode.AUTO` | 根据消息类型自动分类，团队消息进入共享库，个人消息进入个人库 | | `IsolationMode.MANUAL` | 通过显式`VaultTarget`参数路由每个操作 | | `IsolationMode.STRICT` | 严格模式，阻止跨库操作 | > 资料来源：[STABILITY.md:30-35](), [CHANGELOG.md:0.4.0](), [README.md:Dual-Vault Mode]() #### 导出时的敏感信息清理 在将个人保险库笔记导出到共享库时，`Ompa._sanitize_content()`方法会自动清理以下敏感信息： - `sk-*`（OpenAI风格API密钥） - `AKIA*`（AWS访问密钥ID） - `token:`、`password:`、`secret:`、`api_key:`、`api-key:`等敏感字段 > 资料来源：[SECURITY_AUDIT.md:credential-sanitization]() ## 安全机制 ### 路径遍历防护 Vault层实现了严格的路径遍历攻击防护，所有文件操作都通过`_safe_resolve`函数进行路径解析和边界检查： ```mermaid graph TD A[用户请求路径] --> B[_safe_resolve调用] B --> C[Path.resolve 规范化] C --> D{路径是否在vault_root内?} D -->|是| E[允许访问] D -->|否| F[Raise ValueError] E --> G[执行文件操作] ``` 路径遍历防护的关键实现： - 使用`Path.resolve()`将所有路径规范化为绝对路径 - 在操作前检查路径是否在保险库根目录内 - 任何尝试逃逸保险库根目录的操作都会被拒绝并抛出异常 - Brain note名称中包含路径分隔符的请求在API边界处被拒绝 > 资料来源：[SECURITY_AUDIT.md:path-traversal-protection](), [CHANGELOG.md:0.4.1-path-traversal]() ### UTF-8编码强制 从v0.4.0开始，所有vault文件写入操作都强制使用UTF-8编码： > 资料来源：[CHANGELOG.md:0.4.0](), [README.md:utf-8-enforcement]() ### 并发访问支持 Vault层的笔记CRUD操作支持并发访问，通过以下机制确保数据一致性： - 原子文件写入操作 - 修改时间跟踪用于增量更新 - SemanticIndex使用文件修改时间判断是否需要重新嵌入 > 资料来源：[CHANGELOG.md:0.4.0-concurrent-access]() ## 目录结构 ### 标准Vault布局 ``` vault-root/ ├── brain/ # Brain笔记（个人想法、反思） │ ├── reflections/ │ └── insights/ ├── work/ # 工作相关笔记 ├── org/ # 组织/团队知识 ├── perf/ # 性能相关记录 ├── .palace/ # Palace元数据目录 │ ├── wings.json │ ├── rooms.json │ ├── kg.db # Knowledge Graph数据库 │ └── index/ # 语义索引目录 └── .ompa/ # OMPA内部配置 ``` ### Frontmatter格式 每篇笔记都包含YAML frontmatter元数据： ```yaml --- date: 2025-06-01 tags: [authentication, postgres, decision] vault: shared # 或 personal --- ``` > 资料来源：[core.py:frontmatter-示例](), [SECURITY_AUDIT.md:export-sanitization]() ## 笔记分类与路由 ### 消息类型分类 Vault层根据消息类型将笔记路由到对应文件夹： | 消息类型 | 目标文件夹 | 说明 | |---------|----------|------| | DECISION | work/decisions/ | 决策记录 | | INCIDENT | brain/incidents/ | 事件记录 | | WIN | brain/wins/ | 成功案例 | | CONCERN | brain/concerns/ | 问题关注 | | REFLECTION | brain/reflections/ | 个人反思 | | WORK | work/ | 工作相关 | | ORG | org/ | 组织知识 | | ... | ... | 其他类型 | > 资料来源：[core.py:classification-routing](), [CONTRIBUTING.md:adding-message-type]() ### 分类流程 ```mermaid graph TD A[输入消息] --> B[Classifier.classify] B --> C[确定消息类型] C --> D[获取routing_hint] D --> E[确定目标文件夹] E --> F{IsolationMode} F -->|AUTO| G[根据消息类型自动选择vault] F -->|MANUAL| H[使用显式VaultTarget] G --> I[生成安全文件名] H --> I I --> J[构建完整路径] J --> K[_safe_resolve验证] K --> L[写入Note] ``` > 资料来源：[core.py:dual-vault-routing](), [classifier.py:classification-logic]() ## 与其他模块的交互 ### 与Knowledge Graph的集成 Vault层扫描笔记中的以下内容来填充知识图谱： - Frontmatter中的tags - 文件夹路径结构 - Wikilink引用（`[[Note Name]]`） ```python # 通过KnowledgeGraph.populate_from_vault()实现 kg = KnowledgeGraph(db_path) kg.populate_from_vault(vault_path) ``` > 资料来源：[CHANGELOG.md:0.3.0-auto-populate-kg]() ### 与SemanticIndex的集成 SemanticIndex组件跟踪文件修改时间，仅对更改过的文件重新生成嵌入向量： - 首次运行时生成完整索引 - 后续运行仅处理修改时间变更的文件 - 索引存储在`.palace/index/`目录 > 资料来源：[CHANGELOG.md:0.3.0-incremental-semantic]() ### 与MCP Server的集成 MCP Server通过以下工具暴露Vault功能： | MCP工具 | 功能 | |--------|------| | `ao_init` | 初始化新vault | | `ao_status` | 健康检查与统计 | | `ao_write` | 写入笔记 | | `ao_export` | 导出笔记 | | `ao_import` | 导入笔记 | | `ao_orphans` | 检测孤儿笔记 | > 资料来源：[mcp_server.py:tool-handlers](), [CLAUDE.md:mcp-tools]() ## 配置选项 ### 环境变量 | 变量名 | 默认值 | 说明 | |-------|-------|------| | `OMPA_VAULT_PATH` | `.` | Vault根目录绝对路径 | | `OMPA_SHARED_VAULT` | — | 共享vault路径（双库模式） | | `OMPA_PERSONAL_VAULT` | — | 个人vault路径（双库模式） | | `OMPA_ISOLATION_MODE` | `strict` | 隔离模式 | | `OMPA_ENABLE_SEMANTIC` | `false` | 启用本地语义搜索 | > 资料来源：[examples/mcp_desktop/README.md:environment-variables]() ### DualVaultConfig配置 ```python @dataclass class DualVaultConfig: shared_vault: str # 共享vault路径 personal_vault: str # 个人vault路径 isolation_mode: IsolationMode # AUTO | STRICT | MANUAL default_vault: VaultTarget # MANUAL模式的默认目标 ``` > 资料来源：[config.py:DualVaultConfig](), [STABILITY.md:core-class-config]() ## 版本历史关键变更 | 版本 | 日期 | 关键变更 | |-----|------|---------| | 0.4.1 | 2026-04-11 | 路径遍历加固、语义索引延迟加载、brain note名称验证 | | 0.4.0 | 2026-04-10 | 双保险库架构、并发CRUD、UTF-8强制编码 | | 0.3.1 | 2026-04-09 | 孤儿笔记检测修复、wikilink大小写不敏感解析 | | 0.3.0 | 2026-04-08 | 自动从vault填充KG、增量语义索引 | > 资料来源：[CHANGELOG.md:完整历史]() ## 使用示例 ### Python API基本用法 ```python from ompa import Ompa # 单库模式 ao = Ompa(vault_path="./workspace") # 双库模式 from ompa import DualVaultConfig, IsolationMode config = DualVaultConfig( shared_vault="./team-vault", personal_vault="./private-vault", mode=IsolationMode.AUTO, ) ao = Ompa(config=config) # 创建笔记 result = ao.handle_message("We decided to go with Postgres for the auth service") ``` ### CLI命令 ```bash ao init # 初始化新vault ao status # 健康检查 ao orphans # 检测孤儿笔记 ao validate # 验证vault结构 ``` > 资料来源：[README.md:CLI-Reference](), [README.md:Python-API]() ## 内部实现注意事项 以下为内部实现细节，可能会在次要版本中变更： - `ompa.vault.DEFAULT_EXCLUDE_PATTERNS` - `ompa.vault._safe_resolve` - 内部vault文件布局（`.palace/`结构） > 资料来源：[STABILITY.md:not-stable-items]() ## 安全审计结果 Vault存储层已完成全面安全审计，评级为8/10（满分10分）： - **通过项**：路径遍历防护、SQL注入预防、凭证清理、UTF-8编码强制 - **可接受项**：2个低严重性bandit发现（git子进程使用，已接受） > 资料来源：[SECURITY_AUDIT.md:full-audit](), [CHANGELOG.md:0.4.1-security](), [CHANGELOG.md:0.4.1-tests]() --- ## Palace元数据层 ### 相关页面 相关主题：[三层架构设计](#three-layer-design), [Vault存储层](#vault)
相关源码文件 以下源码文件用于生成本页说明： - [ompa/palace.py](https://github.com/jmiaie/ompa/blob/main/ompa/palace.py) - [ompa/core.py](https://github.com/jmiaie/ompa/blob/main/ompa/core.py) - [ompa/mcp_server.py](https://github.com/jmiaie/ompa/blob/main/ompa/mcp_server.py) - [ompa/classifier.py](https://github.com/jmiaie/ompa/blob/main/ompa/classifier.py) - [CLAUDE.md](https://github.com/jmiaie/ompa/blob/main/CLAUDE.md) - [README.md](https://github.com/jmiaie/ompa/blob/main/README.md)
# Palace元数据层 ## 概述 Palace（宫殿）是 OMPA 项目中的**元数据加速层**，与 Vault（存储层）共同构成双层检索架构的核心组成部分。Vault 作为事实来源（source of truth）存储所有笔记内容，而 Palace 则提供结构化的元数据组织和高效的路径导航能力。 资料来源：[CLAUDE.md]() ### 设计理念 Palace 借鉴了"记忆宫殿"（Method of Loci）的隐喻，将笔记组织为层级化的空间结构： - **Wing（翼）**：顶级分类，对应组织或项目维度 - **Room（房间）**：二级分类，对应具体主题或功能领域 - **Drawer（抽屉）**：三级分类，可选，用于更细粒度的组织 - **Hall（大厅）**：跨房间的聚合视图 - **Tunnel（隧道）**：跨翼的连接路径，用于关联不同领域的笔记 这种设计使得 AI Agent 能够通过空间化的方式"导航"和"穿越"记忆结构，而非简单的关键词搜索。 资料来源：[README.md]() ## 架构设计 ### 双层架构 OMPA 采用 **Vault + Palace** 双层架构： ```mermaid graph TD A[用户消息] --> B[Classifier 分类器] B --> C{Vault 或 Palace?} C -->|检索加速| D[Palace 元数据层] C -->|原始内容| E[Vault 存储层] D --> F[Wings / Rooms / Tunnels] E --> G[Markdown 文件 / 语义索引] ``` 资料来源：[CLAUDE.md]() ### Palace 核心职责 | 职责 | 描述 | |------|------| | 元数据管理 | 维护 Wing/Room/Drawer/Hall/Tunnel 的索引结构 | | 路径导航 | 提供笔记的层级路径解析和关联查询 | | 跨域连接 | 创建 Tunnel 实现跨 Wing 的语义关联 | | 统计信息 | 提供 Palace 内各层级元素的数量和状态 | 资料来源：[ompa/core.py]() ## 核心概念 ### Wing（翼） Wing 是 Palace 的顶级组织单元，通常对应一个大的主题领域或组织单元。 **特性**： - 每个 Wing 拥有唯一的名称标识 - Wing 下可包含多个 Room - 支持创建 Tunnel 连接不同 Wing ```python # 通过 Python API 创建 Wing ao.palace.create_wing("Orion") ``` **MCP 工具**：`ao_palace_wings` — 列出所有 palace wings 资料来源：[ompa/mcp_server.py](), [README.md]() ### Room（房间） Room 是 Wing 下的二级组织单元，用于更精细的主题划分。 **特性**： - 必须隶属于某个 Wing - 可通过 Tunnel 与其他 Wing 的 Room 建立连接 - 支持统计该 Wing 下的所有 Room ```python # 通过 Python API 列出房间 rooms = ao.palace.list_rooms("Orion") ``` **MCP 工具**：`ao_palace_rooms` — 列出指定 Wing 下的所有房间 资料来源：[ompa/mcp_server.py](), [README.md]() ### Tunnel（隧道） Tunnel 用于建立跨 Wing 的语义连接，实现不同领域知识之间的关联。 **使用场景**： - 跨项目依赖关系的可视化 - 相关但分属不同领域的笔记关联 - 迁移路径的追踪（如身份认证迁移） ```python # 创建跨 Wing 隧道 ao.palace.create_tunnel("Kai", "Orion", "auth-migration") ``` **返回结果示例**： ```json {"success": true, "tunnel": "Kai <-> Orion via auth-migration"} ``` **MCP 工具**：`ao_palace_tunnel` — 在两个 Wing 之间创建隧道 资料来源：[ompa/mcp_server.py](), [README.md]() ### Hall（大厅） Hall 提供跨房间的聚合视图，允许用户在不限定特定 Room 的情况下进行检索。 ```mermaid graph LR A[Hall] -->|聚合| B[Room A] A -->|聚合| C[Room B] A -->|聚合| D[Room C] ``` ### Drawer（抽屉） Drawer 是可选的三级组织单元，提供更细粒度的分类能力。 ## API 参考 ### Python API ```python from ompa import Ompa ao = Ompa(vault_path="./workspace") # 列出所有 Wings wings = ao.palace.list_wings() # 列出指定 Wing 下的 Rooms rooms = ao.palace.list_rooms("Orion") # 创建 Tunnel ao.palace.create_tunnel("Wing-A", "Wing-B", "room-name") # 获取 Palace 统计信息 stats = ao.palace.stats() ``` 资料来源：[README.md](), [ompa/core.py]() ### MCP Server 工具 | 工具名 | 功能 | 参数 | |--------|------|------| | `ao_palace_wings` | 列出所有 Palace Wings | `vault_path` | | `ao_palace_rooms` | 列出指定 Wing 下的 Rooms | `wing`, `vault_path` | | `ao_palace_tunnel` | 创建跨 Wing 隧道 | `wing_a`, `wing_b`, `room`, `vault_path` | 资料来源：[ompa/mcp_server.py](), [CLAUDE.md]() ### CLI 命令 | 命令 | 功能 | |------|------| | `ao wings` | 列出 Palace Wings | | `ao rooms ` | 列出指定 Wing 下的 Rooms | | `ao tunnel` | 创建或遍历跨 Wing 隧道 | 资料来源：[README.md]() ## Palace 与 Vault 的协同 ### 消息类型路由 Classifier 根据消息内容自动分类，并将笔记路由到合适的 Vault 文件夹。Palace 则维护这些笔记的元数据索引。 ```mermaid sequenceDiagram participant User as 用户 participant Core as Ompa Core participant Classifier as Classifier participant Palace as Palace participant Vault as Vault User->>Core: handle_message(msg) Core->>Classifier: classify(msg) Classifier-->>Core: MessageType + Folder Core->>Vault: write_note(folder, content) Core->>Palace: update_metadata(path, type) ``` 资料来源：[ompa/core.py](), [ompa/classifier.py]() ### 双重隔离模式 在 Dual-Vault 架构下，Palace 支持按 Vault Target（shared/personal）进行元数据隔离： ```python from ompa import Ompa, DualVaultConfig, IsolationMode config = DualVaultConfig( shared_vault="./team-vault", personal_vault="./private-vault", mode=IsolationMode.AUTO, ) ao = Ompa(config=config) ``` Palace 会根据 `IsolationMode` 自动将元数据写入对应的 Palace 实例。 资料来源：[ompa/core.py](), [README.md]() ## 配置与初始化 ### 环境变量 | 变量 | 默认值 | 说明 | |------|--------|------| | `OMPA_VAULT_PATH` | `.` | Vault 根路径 | | `OMPA_ENABLE_SEMANTIC` | `false` | 启用本地语义搜索 | Palace 本身不直接使用环境变量配置，其结构由 Vault 内容动态构建。 ### Vault 初始化 ```bash # 初始化 Vault 结构（Palace 随之创建） ao init # 检查状态 ao status ``` 初始化后，Palace 将扫描 Vault 内容并建立初始元数据索引。 资料来源：[README.md](), [CLAUDE.md]() ## 使用示例 ### 场景：组织身份认证笔记 ```python from ompa import Ompa ao = Ompa(vault_path="./workspace") # 1. 创建组织 Wing ao.palace.create_wing("Orion") # 2. 在 Wing 下创建房间 # （通过 Tunnel 连接不同领域的认证笔记） # 3. 创建跨域 Tunnel ao.palace.create_tunnel("Kai", "Orion", "auth-migration") # 4. 查询 Palace 统计 stats = ao.palace.stats() print(f"Wings: {stats['wings']}") ``` ### 场景：通过 MCP 进行跨域检索 ```bash # 列出所有 Wings claude mcp run ompa ao_palace_wings # 列出 Orion Wing 下的所有 Rooms claude mcp run ompa ao_palace_rooms wing=Orion # 创建 Tunnel claude mcp run ompa ao_palace_tunnel wing_a=Kai wing_b=Orion room=shared ``` 资料来源：[README.md](), [examples/mcp_desktop/README.md]() ## 扩展 Palace ### 添加新概念 如需扩展 Palace 的组织层级（如添加 Floor/Building），需要在以下位置进行修改： 1. `ompa/palace.py` — 添加新的数据结构和操作方法 2. `ompa/mcp_server.py` — 添加对应的 MCP 工具 3. `ompa/cli.py` — 添加 CLI 命令 4. 更新文档和测试 ### 自定义 Hook Palace 支持通过 Hook 系统进行扩展： ```python from ompa.hooks import Hook, HookContext, HookResult class PalaceMetadataHook(Hook): def on_note_create(self, ctx: HookContext) -> HookResult: # 自定义元数据更新逻辑 return HookResult(success=True) ``` 资料来源：[CLAUDE.md]() ## 总结 Palace 元数据层是 OMPA 项目中实现"空间化记忆"的核心组件。它通过层级化的组织结构（Wing → Room → Drawer）和跨域连接机制（Tunnel），为 AI Agent 提供了结构化的知识导航能力。与 Vault 的双层架构设计，使得 OMPA 能够在保持内容完整性的同时，提供高效的可检索性。 **关键特性**： - ✅ 层级化的元数据组织（Wing/Room/Drawer/Hall/Tunnel） - ✅ 跨域 Tunnel 连接不同知识领域 - ✅ 与 Vault 双层协同，Vault 为事实来源，Palace 为检索加速 - ✅ 支持 Dual-Vault 隔离模式 - ✅ 提供 Python API、MCP 工具和 CLI 三种交互方式 --- ## 时序知识图谱 ### 相关页面 相关主题：[三层架构设计](#three-layer-design), [Palace元数据层](#palace)
相关源码文件 以下源码文件用于生成本页说明： - [ompa/knowledge_graph.py](https://github.com/jmiaie/ompa/blob/main/ompa/knowledge_graph.py) - [ompa/mcp_server.py](https://github.com/jmiaie/ompa/blob/main/ompa/mcp_server.py) - [ompa/core.py](https://github.com/jmiaie/ompa/blob/main/ompa/core.py) - [CHANGELOG.md](https://github.com/jmiaie/ompa/blob/main/CHANGELOG.md) - [README.md](https://github.com/jmiaie/ompa/blob/main/README.md) - [STABILITY.md](https://github.com/jmiaie/ompa/blob/main/STABILITY.md)
# 时序知识图谱 ## 概述 时序知识图谱（Temporal Knowledge Graph）是 OMPA 项目的核心组件之一，用于存储和管理具有时间维度的事实三元组。与传统知识图谱不同，时序知识图谱为每个三元组关联了有效性时间窗口，使系统能够查询任意时间点的实体状态变化历史。 时序知识图谱基于 SQLite 实现，采用三重存储（Triple Store）模式，支持以下核心功能： - 三元组（Subject-Predicate-Object）的增删改查 - 实体历史时间线查询 - 从 Vault 自动填充知识图谱 - 基于时间窗口的有效性过滤 资料来源：[README.md](https://github.com/jmiaie/ompa/blob/main/README.md) ## 架构设计 ### 核心概念 | 概念 | 描述 | |------|------| | 三元组（Triple） | 表示 (主体, 谓词, 客体) 的知识单元 | | 主体（Subject） | 实体的标识符，如 "Kai" | | 谓词（Predicate） | 关系类型，如 "works_on"、"knows" | | 客体（Object） | 关系的目标实体或值 | | 有效起始时间（valid_from） | 三元组开始生效的时间点 | | 有效结束时间（valid_to） | 三元组失效的时间点（可选） | | 来源（source） | 三元组的来源标注 | ### 数据模型 时序知识图谱使用 SQLite 数据库存储三重数据，每个三元组包含以下字段： ```mermaid erDiagram TRIPLES { int id PK text subject text predicate text object text valid_from text valid_to text source text vault_path } ``` 资料来源：[ompa/knowledge_graph.py](https://github.com/jmiaie/ompa/blob/main/ompa/knowledge_graph.py) ### 双重 Vault 与知识图谱的关系 ```mermaid graph TD A[Ompa 主类] --> B[时序知识图谱] A --> C[Shared Vault] A --> D[Personal Vault] B -.-> E[Shared KG 查询] B -.-> F[Personal KG 查询] C --> G[brain/ 组织笔记] D --> H[个人笔记] G -.-> B H -.-> B ``` 知识图谱的数据来源可以是共享 Vault 或个人 Vault，具体取决于隔离模式配置。 资料来源：[ompa/core.py](https://github.com/jmiaie/ompa/blob/main/ompa/core.py) ## 功能模块 ### 1. 三元组管理 #### 添加三元组 ```python ao.kg_add(subject, predicate, object_, valid_from=None, source=None) ``` **参数说明：** | 参数 | 类型 | 必需 | 描述 | |------|------|------|------| | subject | str | 是 | 主体实体名称 | | predicate | str | 是 | 谓词/关系类型 | | object_ | str | 是 | 客体实体或值 | | valid_from | str | 否 | 生效时间，格式 YYYY-MM-DD | | source | str | 否 | 三元组来源标注 | **示例：** ```python from ompa import Ompa ao = Ompa(vault_path="./workspace") # 添加基础三元组 ao.kg_add("Kai", "works_on", "Orion") # 添加带时间戳的三元组 ao.kg_add("Kai", "works_on", "Phoenix", valid_from="2025-06-01") # 添加带来源标注的三元组 ao.kg_add("决策", "approved_by", "Team", source="2025-04-15 meeting") ``` 资料来源：[STABILITY.md](https://github.com/jmiaie/ompa/blob/main/STABILITY.md) #### 查询三元组 ```python ao.kg_query(entity, as_of=None) -> list[Triple] ``` **参数说明：** | 参数 | 类型 | 必需 | 描述 | |------|------|------|------| | entity | str | 是 | 要查询的实体名称 | | as_of | str | 否 | 查询时间点，返回该时间点的有效状态 | **返回类型：** `list[Triple]`，每个 Triple 包含 subject、predicate、object_、valid_from、valid_to、source 属性。 **示例：** ```python # 查询实体所有历史记录 triples = ao.kg_query("Kai") # 查询特定时间点的状态 triples = ao.kg_query("Kai", as_of="2025-06-01") ``` 资料来源：[STABILITY.md](https://github.com/jmiaie/ompa/blob/main/STABILITY.md) ### 2. 时间线查询 ```python ao.kg_timeline(entity) -> list[dict] ``` 该方法返回指定实体的完整时间线，展示实体的所有关系变化历史。 **返回格式：** ```python [ { "subject": "Kai", "predicate": "works_on", "object": "Orion", "valid_from": "2025-01-01", "valid_to": "2025-05-31", "source": "manual" }, { "subject": "Kai", "predicate": "works_on", "object": "Phoenix", "valid_from": "2025-06-01", "valid_to": None, "source": "manual" } ] ``` **示例：** ```python # 获取实体的完整时间线 timeline = ao.kg_timeline("Kai") # 分析项目变更历史 for entry in timeline: print(f"{entry['valid_from']}: {entry['subject']} {entry['predicate']} {entry['object']}") ``` 资料来源：[ompa/mcp_server.py](https://github.com/jmiaie/ompa/blob/main/ompa/mcp_server.py) ### 3. 统计信息 ```python ao.kg_stats() -> dict ``` 返回知识图谱的统计信息，包括三元组总数、按谓词分组统计等。 **示例：** ```python stats = ao.kg_stats() print(f"Total triples: {stats['total']}") print(f"By predicate: {stats['by_predicate']}") ``` 资料来源：[ompa/mcp_server.py](https://github.com/jmiaie/ompa/blob/main/ompa/mcp_server.py) ### 4. 自动填充 时序知识图谱支持从 Vault 自动提取三元组，包括： - 从 frontmatter 标签提取实体 - 从文件夹路径提取组织结构 - 从 `[[wikilinks]]` 提取关系 ```python # 自动从 Vault 填充知识图谱 ao.kg.populate_from_vault() ``` **工作流程：** ```mermaid graph LR A[扫描 Vault] --> B[解析笔记] B --> C[提取 frontmatter 标签] B --> D[解析 wikilinks] B --> E[分析文件夹路径] C --> F[生成三元组] D --> F E --> F F --> G[写入知识图谱] ``` 资料来源：[CHANGELOG.md](https://github.com/jmiaie/ompa/blob/main/CHANGELOG.md) ## MCP 工具接口 OMPA 通过 MCP（Model Context Protocol）服务器暴露知识图谱功能，可在 Claude Desktop、Cursor、Windsurf 等工具中使用。 ### 可用工具列表 | 工具名称 | 功能 | 必需参数 | |----------|------|----------| | `ao_kg_query` | 查询实体的三元组 | entity | | `ao_kg_add` | 添加三元组 | subject, predicate, object_ | | `ao_kg_stats` | 获取统计信息 | - | | `ao_kg_timeline` | 获取实体时间线 | entity | | `ao_kg_populate` | 从 Vault 填充 KG | - | 资料来源：[CLAUDE.md](https://github.com/jmiaie/ompa/blob/main/CLAUDE.md) ### MCP 使用示例 ```json { "tool": "ao_kg_add", "arguments": { "subject": "Alice", "predicate": "reports_to", "object_": "Bob", "valid_from": "2025-01-15", "source": "org chart update" } } ``` ## CLI 命令 ### kg-query 查询特定实体的所有三元组： ```bash ao kg-query Kai ``` ### kg-timeline 获取实体的完整时间线： ```bash ao kg-timeline Orion ``` ### kg-stats 查看知识图谱统计信息： ```bash ao kg-stats ``` 资料来源：[README.md](https://github.com/jmiaie/ompa/blob/main/README.md) ## 版本演进 ### v0.3.0 — 自动填充功能 新增 `KnowledgeGraph.populate_from_vault()` 方法，支持从现有笔记中自动提取三元组。 > 资料来源：[CHANGELOG.md](https://github.com/jmiaie/ompa/blob/main/CHANGELOG.md) ### v0.4.0 — 双重 Vault 集成 时序知识图谱支持双重 Vault 架构，可在共享库和个人库之间独立维护知识图谱，并支持库之间的导入导出及数据脱敏。 > 资料来源：[CHANGELOG.md](https://github.com/jmiaie/ompa/blob/main/CHANGELOG.md) ## 最佳实践 ### 1. 实体命名规范 - 使用一致的实体命名格式 - 建议使用 CamelCase 或 snake_case 命名法 - 避免在实体名中使用特殊字符 ### 2. 时间戳管理 - 所有时间戳使用 `YYYY-MM-DD` 格式 - 建议为关键关系变更添加 valid_from 时间戳 - 时间线查询可帮助理解实体状态演变 ### 3. 来源标注 - 为自动填充的三元组标注来源笔记 - 为手动添加的三元组添加来源说明 - 有助于追溯知识来源和验证准确性 ### 4. 性能考虑 - 大量插入时使用批量操作 - 定期执行 `ao rebuild-index` 维护索引 - 复杂查询可结合 Palace 的组织结构加速 ## API 稳定性 时序知识图谱的公共 API 自 v1.0.0 起遵循语义化版本控制。破坏性变更仅在主版本更新时发生，并将在 CHANGELOG.md 中提供迁移指南。 > 资料来源：[STABILITY.md](https://github.com/jmiaie/ompa/blob/main/STABILITY.md) --- ## 消息分类器 ### 相关页面 相关主题：[生命周期钩子](#lifecycle-hooks), [Vault存储层](#vault)
相关源码文件 以下源码文件用于生成本页说明： - [ompa/classifier.py](https://github.com/jmiaie/ompa/blob/main/ompa/classifier.py) - [ompa/core.py](https://github.com/jmiaie/ompa/blob/main/ompa/core.py) - [ompa/config.py](https://github.com/jmiaie/ompa/blob/main/ompa/config.py) - [CONTRIBUTING.md](https://github.com/jmiaie/ompa/blob/main/CONTRIBUTING.md) - [CLAUDE.md](https://github.com/jmiaie/ompa/blob/main/CLAUDE.md) - [README.md](https://github.com/jmiaie/ompa/blob/main/README.md)
# 消息分类器 ## 概述 消息分类器（Message Classifier）是 OMPA 系统的核心组件之一，负责自动识别和分类用户消息的类型，并将每条消息路由到相应的存储位置。该系统基于正则表达式模式匹配和决策树逻辑，实现了 15 种预定义消息类型的自动分类。 消息分类器的主要职责包括： - **类型识别**：通过正则表达式模式分析消息内容，确定消息属于哪种类型 - **路由建议**：为每种类型提供存储路径建议和操作提示 - **双库支持**：在双库模式下，自动判断消息应存储到共享库还是个人库 - **CLI 集成**：提供命令行工具 `ao classify` 用于手动消息分类 资料来源：[ompa/classifier.py:1-50]() ## 系统架构 消息分类器采用分层架构设计，核心组件包括分类引擎、模式匹配器、路由控制器。 ```mermaid graph TD A[用户消息] --> B[Classifier 分类器] B --> C{模式匹配引擎} C -->|正则匹配| D[PATTERNS 模式库] C --> E[ClassificationResult 结果] E --> F[ROUTING_HINTS 路由提示] E --> G[FOLDER_MAP 文件夹映射] E --> H[VaultTarget 目标库判定] H --> I[SHARED 共享库] H --> J[PERSONAL 个人库] ``` ## MessageType 枚举 OMPA 定义了 15 种消息类型，每种类型对应不同的业务场景和存储位置。 | 枚举值 | 中文名称 | 典型关键词 | 存储建议 | |--------|----------|------------|----------| | `DECISION` | 决策记录 | decided, agreed, ADR | brain/Key Decisions.md | | `INCIDENT` | 事故记录 | incident, outage, bug | work/incidents/ | | `WIN` | 成果记录 | won, shipped, deployed | perf/Brag Doc.md | | `ONE_ON_ONE` | 一对一会议 | 1:1, feedback, check-in | work/1-1/ | | `MEETING` | 会议记录 | meeting, agenda, notes | work/meetings/ | | `PROJECT_UPDATE` | 项目更新 | project, progress, blocked | work/active/ | | `PERSON_INFO` | 人员信息 | joined, role, team update | org/people/ | | `QUESTION` | 问题咨询 | how do, what is, why | brain/questions/ | | `TASK` | 任务清单 | todo, action item | work/tasks/ | | `ARCHITECTURE` | 架构设计 | architecture, design, API | work/architecture/ | | `CODE` | 代码相关 | code, function, PR | work/code/ | | `BRAIN_DUMP` | 脑暴记录 | dump, random thoughts | brain/dumps/ | | `WRAP_UP` | 会议总结 | wrap up, end session | brain/sessions/ | | `STANDUP` | 站会记录 | standup, daily | work/standups/ | | `RESEARCH` | 调研记录 | researching, exploring | brain/research/ | 资料来源：[ompa/classifier.py:1-100]() ## 分类流程 ### 1. 模式匹配阶段 分类器使用预定义的正则表达式模式库 `PATTERNS` 对消息进行匹配。每个消息类型对应多组正则表达式，支持灵活的匹配策略。 ```mermaid graph LR A[消息文本] --> B[遍历 MessageType] B --> C[匹配 PATTERNS] C --> D{找到匹配?} D -->|是| E[记录类型得分] D -->|否| F[继续下一个类型] E --> G{还有类型?} F --> G G -->|是| B G -->|否| H[返回最高得分类型] ``` ### 2. 路由决策阶段 基于分类结果，系统生成 `Classification` 对象，包含： - `message_type`：识别出的消息类型 - `suggested_folder`：建议存储文件夹 - `confidence`：匹配置信度（基于匹配到的模式数量） - `routing_hints`：操作提示列表 资料来源：[ompa/classifier.py:100-200]() ## 核心实现 ### Classifier 类 ```python class Classifier: def classify(self, message: str) -> Classification: """核心分类方法""" best_match = None best_score = 0 for msg_type in MessageType: score = self._calculate_score(message, msg_type) if score > best_score: best_score = score best_match = msg_type return Classification( message_type=best_match, suggested_folder=FOLDER_MAP.get(best_match, "brain/"), confidence=best_score / max_patterns, routing_hints=ROUTING_HINTS.get(best_match, []) ) ``` ### PATTERNS 模式库 每个消息类型定义多组正则表达式模式： | 消息类型 | 模式示例 | |----------|----------| | DECISION | `r"\b(decided|going with|settled on|agreed to)\b"` | | INCIDENT | `r"\b(incident|outage|bug|crash|failure)\b"` | | WIN | `r"\b(won|praised|success|achieved|shipped)\b"` | | QUESTION | `r"\b(how do|how can|what is|what are|why does)\b"` | 资料来源：[ompa/classifier.py:100-150]() ### FOLDER_MAP 文件夹映射 | 消息类型 | 目标文件夹 | |----------|------------| | DECISION | brain/ | | INCIDENT | work/incidents/ | | WIN | perf/ | | ONE_ON_ONE | work/1-1/ | | MEETING | work/meetings/ | | PROJECT_UPDATE | work/active/ | | PERSON_INFO | org/people/ | | QUESTION | brain/questions/ | | TASK | work/tasks/ | | ARCHITECTURE | work/architecture/ | | CODE | work/code/ | | BRAIN_DUMP | brain/dumps/ | | WRAP_UP | brain/sessions/ | | STANDUP | work/standups/ | | RESEARCH | brain/research/ | 资料来源：[ompa/classifier.py:150-200]() ## 双库模式集成 消息分类器与双库架构（Dual-Vault）紧密集成，支持自动内容隔离。 ### IsolationMode.AUTO 模式 在自动模式下，分类器根据消息类型自动判断存储目标： ```python # DualVaultConfig.classify_content() 集成 target = self.dual_config.classify_content( content=message, tags=tags, file_path=file_path ) ``` 资料来源：[ompa/core.py:50-80]() ### 自动分类规则 | 消息类型 | 默认目标库 | 说明 | |----------|------------|------| | WIN | PERSONAL | 个人绩效相关 | | ONE_ON_ONE | PERSONAL | 私密对话 | | BRAIN_DUMP | PERSONAL | 私人脑暴 | | DECISION | SHARED | 团队决策 | | INCIDENT | SHARED | 事故共享 | | PROJECT_UPDATE | SHARED | 项目信息 | ## CLI 接口 ### ao classify 命令 ```bash ao classify "We decided to go with Postgres for the main database" ``` 输出示例： ``` Type: DECISION Confidence: 0.85 Folder: brain/ Hints: - This is a decision. Record it in brain/Key Decisions.md - Update relevant project notes with the decision - Add to Decision Log if formal ADR needed ``` 资料来源：[ompa/cli.py]() ## MCP 服务器集成 消息分类功能通过 MCP 协议暴露为工具： ```json { "name": "ao_classify", "description": "Classify a message and get routing hints" } ``` 资料来源：[ompa/mcp_server.py:1-50]() ## 扩展消息类型 要添加新的消息类型，需完成以下步骤： ### 1. 添加枚举值 在 `classifier.py` 的 `MessageType` 枚举中添加新类型。 ### 2. 添加正则模式 ```python PATTERNS[MessageType.NEW_TYPE] = [ r"\b(keyword1|keyword2)\b", r"\b(another pattern)\b", ] ``` ### 3. 添加路由提示 ```python ROUTING_HINTS[MessageType.NEW_TYPE] = [ "Store in appropriate location", "Update relevant notes", ] ``` ### 4. 添加文件夹映射 ```python FOLDER_MAP[MessageType.NEW_TYPE] = "path/to/folder/" ``` ### 5. 添加测试用例 在 `tests/test_ompa.py` 的 `TestClassifier` 类中添加测试用例。 资料来源：[CONTRIBUTING.md:40-55]() ## 配置参数 消息分类器本身无需额外配置，但可通过环境变量影响其行为： | 环境变量 | 说明 | 默认值 | |----------|------|--------| | `OMPA_VAULT_PATH` | 保险库路径 | `.` | | `OMPA_SHARED_VAULT` | 共享库路径 | - | | `OMPA_PERSONAL_VAULT` | 个人库路径 | - | 资料来源：[examples/mcp_desktop/README.md:1-30]() ## 最佳实践 ### 1. 消息预处理 - 消息应保持原始内容，不要提前摘要 - 移除敏感信息后再进行分类 - 包含足够的上下文以提高分类准确率 ### 2. 置信度阈值 建议在下游处理中设置置信度阈值： ```python result = classifier.classify(message) if result.confidence < 0.5: # 人工复核或使用默认分类 pass ``` ### 3. 自定义模式 可通过继承 `Classifier` 类添加自定义模式： ```python class CustomClassifier(Classifier): def _calculate_score(self, message: str, msg_type: MessageType) -> float: base_score = super()._calculate_score(message, msg_type) # 添加自定义评分逻辑 return base_score ``` ## 性能特性 | 特性 | 说明 | |------|------| | 延迟 | O(n*m)，n=消息数，m=每类型模式数 | | 内存 | 模式编译后缓存 | | 并发 | 线程安全 | 分类器采用延迟模式编译策略，模式在首次使用时编译并缓存，确保高性能。 ## 已知限制 - 依赖正则表达式，对语义理解有限 - 混合类型消息可能分类不准确 - 不支持多语言消息分类（当前仅英文模式） ## 相关资源 - [CLAUDE.md](./CLAUDE.md) - 架构决策文档 - [STABILITY.md](./STABILITY.md) - API 稳定性保证 - [测试文件 tests/test_ompa.py](../tests/test_ompa.py) - 分类器测试用例 --- ## MCP服务器集成 ### 相关页面 相关主题：[框架适配器](#adapters)
相关源码文件 以下源码文件用于生成本页说明： - [ompa/mcp_server.py](https://github.com/jmiaie/ompa/blob/main/ompa/mcp_server.py) - [examples/mcp_desktop/README.md](https://github.com/jmiaie/ompa/blob/main/examples/mcp_desktop/README.md) - [README.md](https://github.com/jmiaie/ompa/blob/main/README.md) - [CLAUDE.md](https://github.com/jmiaie/ompa/blob/main/CLAUDE.md) - [CONTRIBUTING.md](https://github.com/jmiaie/ompa/blob/main/CONTRIBUTING.md)
# MCP服务器集成 ## 概述 OMPA通过MCP（Model Context Protocol）服务器提供与AI代理桌面客户端的深度集成。该服务器以Python模块形式运行，通过标准输入/输出（stdin/stdout）使用JSON-RPC 2.0协议与客户端通信，使AI代理能够直接访问OMPA的核心功能。 MCP服务器暴露了15个工具，涵盖保险库管理、知识图谱查询、语义搜索、宫殿导航等功能。开发者可参考稳定性文档确认这些工具为公开API的一部分。 资料来源：[ompa/mcp_server.py:1-50]() ## 架构设计 ### 通信协议 MCP服务器采用JSON-RPC 2.0 over stdin/stdout的标准模式： ```mermaid graph LR A["Claude/Cursor/Windsurf
MCP Client"] <-->|"JSON-RPC
stdin/stdout"| B["ompa.mcp_server
Python Process"] B --> C["Ompa Core
Vault + Palace + KG"] ``` 服务器在初始化时返回协议版本和能力描述： ```python response = { "jsonrpc": "2.0", "id": request_id, "result": { "protocolVersion": "2024-11-05", "capabilities": {"tools": {}}, "serverInfo": { "name": "ompa", "version": __version__, }, }, } ``` 资料来源：[ompa/mcp_server.py:160-175]() ### 主循环处理 服务器在`main()`函数中持续监听stdin，每次读取一行JSON-RPC请求： ```python def main(): request = None while True: try: line = sys.stdin.readline() if not line: break request = json.loads(line.strip()) # 处理请求... except Exception as e: return {"error": type(e).__name__} ``` 资料来源：[ompa/mcp_server.py:180-195]() ## MCP工具清单 ### 工具分类表 | 类别 | 工具名称 | 功能描述 | |------|----------|----------| | 生命周期 | `ao_init` | 初始化新的OMPA保险库 | | 生命周期 | `ao_session_start` | 启动会话并注入记忆上下文 | | 生命周期 | `ao_wrap_up` | 会话总结并持久化 | | 生命周期 | `ao_status` | 检查保险库健康状态 | | 分类 | `ao_classify` | 分类消息并返回路由提示 | | 搜索 | `ao_search` | 执行语义搜索 | | 知识图谱 | `ao_kg_query` | 查询实体关系 | | 知识图谱 | `ao_kg_add` | 添加知识三元组 | | 知识图谱 | `ao_kg_stats` | 知识图谱统计 | | 知识图谱 | `ao_kg_populate` | 从保险库填充知识图谱 | | 宫殿 | `ao_palace_wings` | 列出所有宫殿翅膀 | | 宫殿 | `ao_palace_rooms` | 列出指定翅膀中的房间 | | 宫殿 | `ao_palace_tunnel` | 创建/穿越跨翅膀隧道 | | 工具 | `ao_orphans` | 检测孤立笔记 | | 工具 | `ao_validate` | 验证保险库结构 | | 同步 | `ao_sync` | 同步保险库 | | 文件 | `ao_write` | 写入笔记 | | 文件 | `ao_export` | 导出内容 | | 文件 | `ao_import` | 导入内容 | 资料来源：[CLAUDE.md:1-15]() ### 知识图谱工具详解 #### ao_kg_add 添加三元组到知识图谱： ```python result = ao_kg_add( subject=arguments["subject"], predicate=arguments["predicate"], object=arguments["object"], valid_from=arguments.get("valid_from"), source=arguments.get("source"), vault_path=vault_path, ) ``` 参数说明： | 参数 | 类型 | 必需 | 说明 | |------|------|------|------| | `subject` | string | 是 | 主语实体 | | `predicate` | string | 是 | 关系谓词 | | `object` | string | 是 | 宾语实体 | | `valid_from` | string | 否 | 有效期起始日期（YYYY-MM-DD） | | `source` | string | 否 | 来源文件 | 资料来源：[ompa/mcp_server.py:90-100]() ## 桌面客户端配置 ### Claude Desktop #### 方式一：CLI命令（推荐） ```bash claude mcp add ompa -- python -m ompa.mcp_server ``` #### 方式二：手动配置 编辑 `~/.claude/claude_desktop_config.json`： ```json { "mcpServers": { "ompa": { "command": "python", "args": ["-m", "ompa.mcp_server"], "env": { "OMPA_VAULT_PATH": "/absolute/path/to/your/vault" } } } } ``` 配置完成后需重启Claude Desktop应用。 资料来源：[examples/mcp_desktop/README.md:1-40]() ### Cursor 在项目根目录创建 `.cursor/mcp.json`： ```json { "mcpServers": { "ompa": { "command": "python", "args": ["-m", "ompa.mcp_server"], "env": { "OMPA_VAULT_PATH": "${workspaceFolder}/.ompa-vault", "OMPA_ENABLE_SEMANTIC": "false" } } } } ``` 资料来源：[examples/mcp_desktop/README.md:50-65]() ### Windsurf 配置方式与Cursor相同，创建 `.windsurf/mcp.json`： ```json { "mcpServers": { "ompa": { "command": "python", "args": ["-m", "ompa.mcp_server"], "env": { "OMPA_VAULT_PATH": "/path/to/vault" } } } } ``` 资料来源：[examples/mcp_desktop/README.md:25-35]() ## 环境变量配置 ### 配置项总览 | 变量名 | 默认值 | 说明 | |--------|--------|------| | `OMPA_VAULT_PATH` | `.` | 保险库绝对路径 | | `OMPA_ENABLE_SEMANTIC` | `false` | 启用本地语义搜索 | | `OMPA_AGENT_NAME` | `agent` | 代理名称（用于知识图谱条目作用域） | | `OMPA_SHARED_VAULT` | — | 共享保险库路径（双保险库模式） | | `OMPA_PERSONAL_VAULT` | — | 个人保险库路径（双保险库模式） | 资料来源：[examples/mcp_desktop/README.md:70-85]() ### 语义搜索配置 默认情况下，语义搜索功能关闭。如需启用本地语义搜索（首次运行会下载约500MB的`all-MiniLM-L6-v2`模型）： ```bash pip install ompa[all] ``` 然后在MCP配置的`env`块中设置： ```json { "env": { "OMPA_ENABLE_SEMANTIC": "true" } } ``` 后续运行将直接使用缓存模型，无额外下载。 资料来源：[examples/mcp_desktop/README.md:40-50]() ## 双保险库模式集成 MCP服务器支持双保险库架构，可隔离团队/组织内容与个人私密笔记。 ### MCP配置示例 ```json { "mcpServers": { "ompa": { "command": "python", "args": ["-m", "ompa.mcp_server"], "env": { "OMPA_SHARED_VAULT": "/path/to/shared-vault", "OMPA_PERSONAL_VAULT": "/path/to/personal-vault", "OMPA_ISOLATION_MODE": "auto" } } } } ``` ### 隔离模式 | 模式 | 说明 | |------|------| | `auto` | 内容根据消息类型自动分类到共享或个人保险库 | | `strict` | 严格隔离模式 | | `manual` | 每个操作需显式指定`VaultTarget` | 资料来源：[examples/mcp_desktop/README.md:100-120]() ## 连接验证 配置完成后，可通过以下方式验证连接： 1. 在支持MCP的客户端中，询问AI助手： > "Use the ao_status tool to check my OMPA vault health" 2. 预期响应应包含保险库统计信息。 ### 常见问题排查 | 问题 | 解决方案 | |------|----------| | 工具未出现 | 重启桌面应用 | | "Vault not found" 错误 | 确认`OMPA_VAULT_PATH`为绝对路径且已通过`ao init`初始化 | | 首次运行缓慢 | 若启用语义搜索，首次运行需下载模型（约90MB），后续运行应立即响应 | 资料来源：[examples/mcp_desktop/README.md:120-135]() ## 框架兼容性 OMPA的MCP服务器支持多种AI代理框架： | 代理框架 | 集成方式 | |----------|----------| | Claude Code | Python API + MCP服务器 | | OpenClaw | Python API + MCP服务器 | | Codex | Python API + MCP服务器 | | Gemini CLI | Python API + MCP服务器 | | LangChain | Python API | MCP服务器为框架无关的纯Python实现，无代理SDK依赖。 资料来源：[README.md:60-75]() ## 启动方式汇总 ### 启动命令对照表 | 环境 | 启动命令 | |------|----------| | 直接运行 | `python -m ompa.mcp_server` | | Claude Desktop | `claude mcp add ompa -- python -m ompa.mcp_server` | | 指定保险库 | 设置`OMPA_VAULT_PATH`环境变量 | | 启用语义搜索 | 设置`OMPA_ENABLE_SEMANTIC=true` | 所有启动方式均要求目标保险库已通过`ao init`初始化。 资料来源：[examples/mcp_desktop/README.md:1-20]() ## 安全特性 MCP服务器继承OMPA核心的安全设计： 1. **路径遍历防护**：所有保险库文件操作都解析并边界检查路径 2. **UTF-8编码强制**：所有保险库文件写入显式指定UTF-8编码 3. **并发安全**：笔记CRUD操作支持并发访问 资料来源：[CHANGELOG.md:30-50]() ## 相关文档 - [CLAUDE.md](https://github.com/jmiaie/ompa/blob/main/CLAUDE.md) — 架构决策与内部API文档 - [STABILITY.md](https://github.com/jmiaie/ompa/blob/main/STABILITY.md) — API稳定性保证 - [CONTRIBUTING.md](https://github.com/jmiaie/ompa/blob/main/CONTRIBUTING.md) — 添加新MCP工具的指南 --- ## 框架适配器 ### 相关页面 相关主题：[MCP服务器集成](#mcp-server)
相关源码文件 以下源码文件用于生成本页说明： - [ompa/adapters/langchain.py](https://github.com/jmiaie/ompa/blob/main/ompa/adapters/langchain.py) - [ompa/adapters/llamaindex.py](https://github.com/jmiaie/ompa/blob/main/ompa/adapters/llamaindex.py) - [ompa/adapters/faiss.py](https://github.com/jmiaie/ompa/blob/main/ompa/adapters/faiss.py) - [ompa/adapters/nim.py](https://github.com/jmiaie/ompa/blob/main/ompa/adapters/nim.py) - [ompa/adapters/openai_agents.py](https://github.com/jmiaie/ompa/blob/main/ompa/adapters/openai_agents.py) - [examples/langchain_agent/ompa_memory.py](https://github.com/jmiaie/ompa/blob/main/examples/langchain_agent/ompa_memory.py)
# 框架适配器 OMPA 框架适配器（Framework Adapters）是一组将 OMPA 与主流 AI 开发框架集成的桥接模块。这些适配器位于 `ompa/adapters/` 目录下，提供了与 LangChain、LlamaIndex、OpenAI Agents SDK 等框架的无缝对接能力，使开发者能够在现有 AI 应用架构中直接利用 OMPA 的记忆管理、知识图谱和语义搜索功能。 ## 架构概览 OMPA 适配器层采用了适配器模式（Adapter Pattern），将 OMPA 的核心功能封装为各框架所期望的接口形式。这种设计使得 OMPA 可以作为多种 AI 框架的底层存储和检索后端，而无需修改框架本身的代码。 ```mermaid graph TB subgraph "AI 应用层" LC[LangChain 应用] LI[LlamaIndex 应用] OAI[OpenAI Agents] CUSTOM[自定义应用] end subgraph "适配器层" LCM[OmpaMemory
OmpaRetriever] LIC[OmpaReader
OmpaVaultRetriever] OAIC[OmpaAgentHooks] NIM[NIMEmbeddingBackend] FAISS[FAISSSemanticIndex] end subgraph "OMPA 核心" CORE[Ompa Core] VAULT[Vault] KG[Knowledge Graph] SEM[Semantic Index] end LC --> LCM LI --> LIC OAI --> OAIC CUSTOM --> NIM CUSTOM --> FAISS LCM --> CORE LIC --> CORE OAIC --> CORE NIM --> SEM FAISS --> SEM CORE --> VAULT CORE --> KG ``` ## 可用适配器列表 | 适配器 | 源文件 | 功能描述 | |--------|--------|----------| | `OmpaMemory` | `ompa/adapters/langchain.py` | LangChain 聊天记忆组件 | | `OmpaRetriever` | `ompa/adapters/langchain.py` | LangChain 检索器，用于 RAG 链 | | `OmpaReader` | `ompa/adapters/llamaindex.py` | LlamaIndex 文档读取器 | | `OmpaVaultRetriever` | `ompa/adapters/llamaindex.py` | LlamaIndex 保险库检索器 | | `OmpaAgentHooks` | `ompa/adapters/openai_agents.py` | OpenAI Agents SDK 生命周期钩子 | | `NIMEmbeddingBackend` | `ompa/adapters/nim.py` | NVIDIA NIM 嵌入后端 | | `FAISSSemanticIndex` | `ompa/adapters/faiss.py` | FAISS 语义索引实现 | 资料来源：[STABILITY.md]() ## LangChain 适配器 LangChain 适配器提供了与 LangChain 框架的深度集成，支持将 OMPA 作为聊天记忆存储和检索后端使用。 ### OmpaMemory `OmpaMemory` 是实现 LangChain `BaseChatMemory` 接口的记忆组件，它将 OMPA 保险库作为持久化存储层。 **主要方法：** ```python load_memory_variables(inputs) -> dict save_context(inputs, outputs) -> None clear() -> None ``` **使用示例：** ```python from ompa.adapters.langchain import OmpaMemory from langchain.chains import ConversationChain from langchain_anthropic import ChatAnthropic # 初始化记忆组件 memory = OmpaMemory(vault_path="./workspace") # 创建对话链 chain = ConversationChain( llm=ChatAnthropic(model="claude-sonnet-4-20250514"), memory=memory ) # 对话交互 response = chain.invoke({"input": "用户输入内容"}) ``` 资料来源：[ompa/adapters/langchain.py:51-67]() ### OmpaRetriever `OmpaRetriever` 包装了 OMPA 的搜索功能，使其可以作为 LangChain RAG 链中的检索器使用。 ```python from ompa.adapters.langchain import OmpaRetriever retriever = OmpaRetriever(vault_path="./workspace") # 在 RAG 链中使用 rag_chain = create_retrieval_chain(llm, retriever) ``` ## LlamaIndex 适配器 LlamaIndex 适配器提供了文档读取和检索能力，使 OMPA 保险库可以作为 LlamaIndex 的数据源。 ### OmpaReader `OmpaReader` 用于从 OMPA 保险库中读取文档并转换为 LlamaIndex 的文档格式。 ```python from ompa.adapters.llamaindex import OmpaReader reader = OmpaReader(vault_path="./workspace") documents = reader.load_data() ``` ### OmpaVaultRetriever `OmpaVaultRetriever` 提供了对 OMPA 保险库的向量检索能力，可直接集成到 LlamaIndex 的查询引擎中。 ```python from ompa.adapters.llamaindex import OmpaVaultRetriever retriever = OmpaVaultRetriever(vault_path="./workspace") ``` ## OpenAI Agents SDK 适配器 `OmpaAgentHooks` 为 OpenAI Agents SDK 提供了 OMPA 的生命周期钩子集成。 ```python from ompa.adapters.openai_agents import OmpaAgentHooks hooks = OmpaAgentHooks(vault_path="./workspace") # 在 OpenAI Agents 应用中注册钩子 ``` ## 向量存储适配器 ### NIMEmbeddingBackend `NIMEmbeddingBackend` 提供了与 NVIDIA NIM（NVIDIA Inference Management）服务的集成，用于生成嵌入向量。 ```python from ompa.adapters.nim import NIMEmbeddingBackend backend = NIMEmbeddingBackend( api_key="your-api-key", model="nvidia/nvolve-4q" ) ``` ### FAISSSemanticIndex `FAISSSemanticIndex` 使用 Facebook AI Similarity Search (FAISS) 库实现高效的向量相似度搜索。 ```python from ompa.adapters.faiss import FAISSSemanticIndex index = FAISSSemanticIndex(vault_path="./workspace") ``` ## 安装依赖 不同的适配器需要不同的可选依赖包： ```bash # LangChain 适配器 pip install ompa[langchain] # LlamaIndex 适配器 pip install ompa[llamaindex] # 所有适配器 pip install ompa[all] ``` ## 稳定性说明 根据项目稳定性策略，适配器接口在以下方面保持稳定： - 公共方法签名 - 构造函数参数 - 返回值类型 适配器的内部实现细节可能在次版本更新中发生变化，但公共 API 将保持向后兼容。 资料来源：[STABILITY.md]() ## 最佳实践 1. **惰性初始化**：适配器支持惰性加载模型和索引，避免在导入时触发大量资源下载。 2. **会话管理**：在长时间运行的 AI 应用中，确保在应用关闭时正确清理资源。 3. **并发访问**：多个框架实例可以同时访问同一个 OMPA 保险库，适配器已处理并发读写场景。 4. **配置分离**：建议将不同框架的适配器配置分离管理，便于独立调试和优化。 ## 扩展适配器 开发者可以通过实现相应的协议（Protocol）接口来创建自定义适配器： ```python from ompa.semantic import EmbeddingBackend class CustomEmbeddingBackend(EmbeddingBackend): """自定义嵌入后端接口""" async def embed(self, texts: list[str]) -> list[list[float]]: # 实现自定义嵌入逻辑 pass async def embed_query(self, query: str) -> list[float]: # 实现自定义查询嵌入 pass ``` ## 与核心模块的关系 ```mermaid graph LR subgraph "适配器层" LANG[LangChain] LLAMA[LlamaIndex] OAI[OpenAI Agents] end subgraph "OMPA 核心" VAULT[Vault
笔记持久化] KG[Knowledge Graph
三元组存储] SEM[Semantic Index
向量索引] end LANG --> VAULT LANG --> SEM LLAMA --> VAULT LLAMA --> SEM OAI --> VAULT OAI --> KG ``` 适配器层负责将框架特定的接口转换为 OMPA 核心模块的标准调用，实现了框架解耦和应用灵活性的平衡。 --- --- ## Doramagic 踩坑日志 项目：jmiaie/ompa 摘要：发现 10 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：安装坑 - 来源证据：OMPA v0.2.0 — The Big Rename。 ## 1. 安装坑 · 来源证据：OMPA v0.2.0 — The Big Rename - 严重度：medium - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：OMPA v0.2.0 — The Big Rename - 对用户的影响：可能阻塞安装或首次运行。 - 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。 - 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。 - 证据：community_evidence:github | cevd_ac771ab081be444ab18c5c1963becb64 | https://github.com/jmiaie/ompa/releases/tag/v0.2.0 | 来源讨论提到 python 相关条件，需在安装/试用前复核。 ## 2. 配置坑 · 来源证据：[P0] agent_integration.py race condition — session.memory attribute not available on cold start - 严重度：medium - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：[P0] agent_integration.py race condition — session.memory attribute not available on cold start - 对用户的影响：可能阻塞安装或首次运行。 - 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。 - 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。 - 证据：community_evidence:github | cevd_db65ef8ac28c41048d74c03c80cbed28 | https://github.com/jmiaie/ompa/issues/6 | 来源讨论提到 python 相关条件，需在安装/试用前复核。 ## 3. 能力坑 · 能力判断依赖假设 - 严重度：medium - 证据强度：source_linked - 发现：README/documentation is current enough for a first validation pass. - 对用户的影响：假设不成立时，用户拿不到承诺的能力。 - 建议检查：将假设转成下游验证清单。 - 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。 - 证据：capability.assumptions | github_repo:1207151629 | https://github.com/jmiaie/ompa | README/documentation is current enough for a first validation pass. ## 4. 维护坑 · 维护活跃度未知 - 严重度：medium - 证据强度：source_linked - 发现：未记录 last_activity_observed。 - 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。 - 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。 - 防护动作：维护活跃度未知时，推荐强度不能标为高信任。 - 证据：evidence.maintainer_signals | github_repo:1207151629 | https://github.com/jmiaie/ompa | last_activity_observed missing ## 5. 安全/权限坑 · 下游验证发现风险项 - 严重度：medium - 证据强度：source_linked - 发现：no_demo - 对用户的影响：下游已经要求复核，不能在页面中弱化。 - 建议检查：进入安全/权限治理复核队列。 - 防护动作：下游风险存在时必须保持 review/recommendation 降级。 - 证据：downstream_validation.risk_items | github_repo:1207151629 | https://github.com/jmiaie/ompa | no_demo; severity=medium ## 6. 安全/权限坑 · 存在安全注意事项 - 严重度：medium - 证据强度：source_linked - 发现：No sandbox install has been executed yet; downstream must verify before user use. - 对用户的影响：用户安装前需要知道权限边界和敏感操作。 - 建议检查：转成明确权限清单和安全审查提示。 - 防护动作：安全注意事项必须面向用户前置展示。 - 证据：risks.safety_notes | github_repo:1207151629 | https://github.com/jmiaie/ompa | No sandbox install has been executed yet; downstream must verify before user use. ## 7. 安全/权限坑 · 存在评分风险 - 严重度：medium - 证据强度：source_linked - 发现：no_demo - 对用户的影响：风险会影响是否适合普通用户安装。 - 建议检查：把风险写入边界卡，并确认是否需要人工复核。 - 防护动作：评分风险必须进入边界卡，不能只作为内部分数。 - 证据：risks.scoring_risks | github_repo:1207151629 | https://github.com/jmiaie/ompa | no_demo; severity=medium ## 8. 安全/权限坑 · 来源证据：OMPA v0.2.1 — Security & Reliability Hardening - 严重度：medium - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：OMPA v0.2.1 — Security & Reliability Hardening - 对用户的影响：可能阻塞安装或首次运行。 - 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。 - 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。 - 证据：community_evidence:github | cevd_ab0ad6b963354f2096bef6783c95c289 | https://github.com/jmiaie/ompa/releases/tag/v0.2.1 | 来源讨论提到 python 相关条件，需在安装/试用前复核。 ## 9. 维护坑 · issue/PR 响应质量未知 - 严重度：low - 证据强度：source_linked - 发现：issue_or_pr_quality=unknown。 - 对用户的影响：用户无法判断遇到问题后是否有人维护。 - 建议检查：抽样最近 issue/PR，判断是否长期无人处理。 - 防护动作：issue/PR 响应未知时，必须提示维护风险。 - 证据：evidence.maintainer_signals | github_repo:1207151629 | https://github.com/jmiaie/ompa | issue_or_pr_quality=unknown ## 10. 维护坑 · 发布节奏不明确 - 严重度：low - 证据强度：source_linked - 发现：release_recency=unknown。 - 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。 - 建议检查：确认最近 release/tag 和 README 安装命令是否一致。 - 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。 - 证据：evidence.maintainer_signals | github_repo:1207151629 | https://github.com/jmiaie/ompa | release_recency=unknown