概述

OMPA（Obsidian-MemPalace-Agnostic）是一个专为 AI Agent 设计的记忆管理系统，旨在为 Claude Code、OpenClaw、Codex 等 Agent 框架提供持久化记忆能力。项目最初从 MemPalace 启发而来，并融合了 obsidian-mind 等社区项目的优秀理念。

资料来源：README.md:1

OMPA 的核心理念是逐字存储（verbatim storage）而非摘要，确保记忆的完整性和可追溯性。根据 MemPalace 的研究验证，逐字存储方案可达到 96.6% 的检索准确率（Recall@5）。

资料来源：CLAUDE.md:1

核心定位

OMPA 解决的核心问题是：AI Agent 在长时间会话中如何有效管理、检索和利用历史信息。

传统 Agent 框架面临以下挑战：

资料来源：README.md:1

技术架构

整体架构图

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<br/>记忆存储)]
        Palace[(Palace<br/>宫殿元数据)]
        KG[(Knowledge Graph<br/>时序知识图谱)]
        Semantic[Semantic Index<br/>语义索引]
    end

    ClaudeCode --> Core
    OpenClaw --> Core
    Codex --> Core
    GeminiCLI --> Core

    Core --> Classifier
    Core --> Hooks
    Core --> Vault
    Core --> Palace
    Core --> KG
    Core --> Semantic

模块说明

资料来源：README.md:1

核心功能特性

1. 双保险库架构（Dual-Vault）

OMPA 支持将团队/组织内容与个人/私密笔记隔离存储：

from ompa import Ompa, DualVaultConfig, IsolationMode

config = DualVaultConfig(
    shared_vault="./team-vault",
    personal_vault="./private-vault",
    mode=IsolationMode.AUTO,
)
ao = Ompa(config=config)

隔离模式（IsolationMode）：

资料来源：README.md:1

2. 消息自动分类

OMPA 内置 15 种消息类型分类器，自动识别并路由消息到对应文件夹：

graph LR
    Input[用户消息] --> Classifier[Classifier]
    Classifier --> DEC[DECISION]
    Classifier --> INC[INCIDENT]
    Classifier --> WIN[WIN]
    Classifier --> O1O[ONE_ON_ONE]
    Classifier --> Q[QUESTION]
    Classifier --> OTHER[...]

消息类型列表：

资料来源：ompa/classifier.py:1

3. 时序知识图谱（Temporal Knowledge Graph）

KG 使用 SQLite 存储三元组，支持时间维度查询：

# 添加带时间窗口的三元组
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 调用即可实现语义搜索：

results = ao.search("authentication decisions", wing="Orion")

特性：

• 延迟加载模型，首次访问时才下载
• 增量索引，仅重新嵌入修改过的文件
• 支持 wing/room 级别的范围搜索

资料来源：README.md:1

5. 生命周期钩子系统

支持 5 个生命周期钩子，允许自定义扩展：

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

安装与使用

安装方式

# 核心功能
pip install ompa

# 含本地语义搜索（首次运行下载约 500MB 模型）
pip install ompa[all]

# 开发模式
pip install ompa[dev]

环境要求：Python 3.10+

资料来源：README.md:1

CLI 命令参考

资料来源：README.md:1

MCP 集成

OMPA 提供 MCP（Model Context Protocol）服务器，可与 Claude Desktop、Cursor、Windsurf 等 IDE 集成：

# 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 基础用法

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

框架兼容性

资料来源：README.md:1

适配器生态

OMPA 提供多种官方适配器，便于与其他生态系统集成：

# 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

版本历史

资料来源：CHANGELOG.md:1

安全特性

资料来源：CHANGELOG.md:1

开发指南

本地开发

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

架构设计决策

资料来源：CLAUDE.md:1

致谢

OMPA 是 AI Agent 记忆社区优秀理念的集大成者：

• MemPalace by Kyle Corbitt — 宫殿隐喻（wings/rooms/drawers/halls/tunnels）
• obsidian-mind — Obsidian 记忆系统
• Claude Code — Agent 框架参考
• OpenClaw — Agent 框架参考

资料来源：README.md:1

环境要求

资料来源：README.md:1

安装

OMPA 提供多种安装方式，可根据需求选择：

# 仅核心功能（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 的三个核心组件：

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

资料来源：README.md:65-80

初始化 Vault

Vault 是 OMPA 的源数据存储目录，包含 Brain、Work、Org、Perf 四个笔记分区。

# 初始化新的 vault
ao init

# 检查 vault 健康状态
ao status

初始化后，将创建以下目录结构：

.
├── .ompa/
│   └── config.yaml
├── brain/
├── work/
├── org/
└── perf/

资料来源：examples/mcp_desktop/README.md:1-10

CLI 快速命令

OMPA 提供完整的命令行工具：

# 会话管理
ao session-start     # 启动会话，注入约 2K token 上下文
ao wrap-up           # 会话总结并保存

# 笔记操作
ao classify <msg>    # 分类并路由消息
ao search <query>    # 语义搜索

# 知识图谱
ao kg-query <entity>      # 查询实体
ao kg-timeline <entity>   # 实体时间线
ao kg-stats               # 图谱统计

# Palace 导航
ao wings                  # 列出所有区域
ao rooms <wing>           # 列出区域中的房间
ao tunnel                 # 创建/遍历跨区域通道

# 工具
ao orphans                # 检测孤立笔记
ao validate               # 验证 vault 结构
ao rebuild-index          # 重建语义索引

资料来源：README.md:25-45

Python API 使用

基本使用流程

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 核心类初始化参数

from ompa import Ompa

ao = Ompa(
    vault_path="./workspace",      # Vault 路径
    agent_name="agent",            # Agent 名称（用于 KG 实体限定）
    enable_semantic=True,          # 启用语义搜索
    embedding_backend=None,        # 嵌入后端
)

资料来源：STABILITY.md:10-25

双 Vault 模式

OMPA 支持双 Vault 架构，用于隔离团队/组织内容与个人/私密笔记。

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)

隔离模式

资料来源：README.md:55-65

环境变量配置

资料来源：examples/mcp_desktop/README.md:50-60

MCP 服务器集成

OMPA 提供 MCP（Model Context Protocol）服务器，可与 Claude Desktop、Cursor、Windsurf 等工具集成。

Claude Desktop 配置

方式一：CLI（推荐）

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/your/vault"
      }
    }
  }
}

Cursor / Windsurf 配置

创建 .cursor/mcp.json 或 .windsurf/mcp.json：

{
  "mcpServers": {
    "ompa": {
      "command": "python",
      "args": ["-m", "ompa.mcp_server"],
      "env": {
        "OMPA_VAULT_PATH": "${workspaceFolder}/.ompa-vault",
        "OMPA_ENABLE_SEMANTIC": "false"
      }
    }
  }
}

MCP 可用工具

资料来源：ompa/mcp_server.py:1-50

消息分类系统

OMPA 内置 15 种消息类型分类器，可自动将消息路由到正确的 vault 文件夹：

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 了解架构决策
• 查看 STABILITY.md 了解 API 稳定性承诺
• 参考 CONTRIBUTING.md 参与贡献

架构概览

graph TB
    subgraph 数据层 "第一层：Vault（数据持久层）"
        VAULT["Vault Manager<br/>brain/work/org/perf"]
        FILES["文件系统<br/>Markdown + Frontmatter"]
    end
    
    subgraph 加速层 "第二层：Palace（元数据加速层）"
        PALACE["Palace Manager<br/>wings/rooms/drawers"]
        INDEX["语义索引<br/>sentence-transformers"]
    end
    
    subgraph 推理层 "第三层：Knowledge Graph（时序推理层）"
        KG["Knowledge Graph<br/>SQLite Triples"]
        TEMPORAL["时序窗口<br/>valid_from/valid_to"]
    end
    
    USER["> 用户/Agent"]
    
    USER --> VAULT
    USER --> PALACE
    USER --> KG
    
    VAULT --> FILES
    PALACE --> INDEX
    KG --> TEMPORAL
    
    FILES -.->|"populate"| KG
    INDEX -.->|"辅助"| PALACE

三层职责对照表

资料来源：CLAUDE.md:1-15

第一层：Vault（数据持久层）

设计目标

Vault层作为整个记忆系统的事实来源（Source of Truth），负责持久化存储所有笔记、文档和元数据。采用原文存储策略（Verbatim Storage），不进行摘要或压缩，以保证最高的信息保真度。MemPalace的研究表明，verbatim存储在LongMemEval基准上达到了96.6%的R@5召回率。

目录结构

Vault采用四象限组织结构，与obsidian-mind项目的设计保持一致：

graph TD
    VAULT["Vault Root"]
    BRAIN["brain/<br/>个人思考"]
    WORK["work/<br/>工作项目"]
    ORG["org/<br/>组织信息"]
    PERF["perf/<br/>性能数据"]
    
    VAULT --> BRAIN
    VAULT --> WORK
    VAULT --> ORG
    VAULT --> PERF
    
    WORK --> ACTIVE["active/<br/>活跃项目"]
    WORK --> ARCHIVE["archive/<br/>归档项目"]
    PERF --> METRICS["metrics/<br/>指标"]
    PERF --> SESSIONS["sessions/<br/>会话记录"]

核心功能

Vault Manager提供以下核心操作：

资料来源：ompa/vault.py

Frontmatter规范

每条笔记都包含标准化的Frontmatter元数据：

核心概念

OMPA 定义了 5 个生命周期钩子点，分别对应会话的不同阶段：

系统架构

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 基类：

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
        )

构造函数参数：

HookContext

传递给钩子执行器的上下文对象，包含当前会话状态信息。

HookResult

钩子执行结果的返回结构：

HookManager

HookManager 负责管理所有已注册的钩子实例，提供注册和执行接口。

from ompa.hooks import HookManager

# 获取 HookManager 实例
hook_manager = ao.hooks
hook_manager.register_hook("my_hook", MyHook())

注册自定义钩子

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())

钩子执行流程

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：

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 的别名)

完整示例

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

相关文件

核心职责

Vault存储层承担以下核心职责：

资料来源：CLAUDE.md:7

架构设计

双层存储架构

OMPA采用Vault + Palace的双层存储架构：

• Vault层：数据的唯一事实来源，负责原始笔记和文件的持久化存储
• Palace层：作为检索加速层，提供宫殿式记忆结构（wings/rooms/drawers/halls/tunnels）来优化信息检索效率

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支持双保险库架构，允许在共享保险库和个人保险库之间隔离数据：

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)

#### 隔离模式

资料来源：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函数进行路径解析和边界检查：

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元数据：

概述

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 双层架构：

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 核心职责

资料来源：ompa/core.py

核心概念

Wing（翼）

Wing 是 Palace 的顶级组织单元，通常对应一个大的主题领域或组织单元。

特性：

• 每个 Wing 拥有唯一的名称标识
• Wing 下可包含多个 Room
• 支持创建 Tunnel 连接不同 Wing

# 通过 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 API 列出房间
rooms = ao.palace.list_rooms("Orion")

MCP 工具：ao_palace_rooms — 列出指定 Wing 下的所有房间

资料来源：ompa/mcp_server.py, README.md

Tunnel（隧道）

Tunnel 用于建立跨 Wing 的语义连接，实现不同领域知识之间的关联。

使用场景：

• 跨项目依赖关系的可视化
• 相关但分属不同领域的笔记关联
• 迁移路径的追踪（如身份认证迁移）

# 创建跨 Wing 隧道
ao.palace.create_tunnel("Kai", "Orion", "auth-migration")

返回结果示例：

{"success": true, "tunnel": "Kai <-> Orion via auth-migration"}

MCP 工具：ao_palace_tunnel — 在两个 Wing 之间创建隧道

资料来源：ompa/mcp_server.py, README.md

Hall（大厅）

Hall 提供跨房间的聚合视图，允许用户在不限定特定 Room 的情况下进行检索。

graph LR
    A[Hall] -->|聚合| B[Room A]
    A -->|聚合| C[Room B]
    A -->|聚合| D[Room C]

Drawer（抽屉）

Drawer 是可选的三级组织单元，提供更细粒度的分类能力。

API 参考

Python API

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 工具

资料来源：ompa/mcp_server.py, CLAUDE.md

CLI 命令

资料来源：README.md

Palace 与 Vault 的协同

消息类型路由

Classifier 根据消息内容自动分类，并将笔记路由到合适的 Vault 文件夹。Palace 则维护这些笔记的元数据索引。

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）进行元数据隔离：

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

配置与初始化

环境变量

Palace 本身不直接使用环境变量配置，其结构由 Vault 内容动态构建。

Vault 初始化

# 初始化 Vault 结构（Palace 随之创建）
ao init

# 检查状态
ao status

初始化后，Palace 将扫描 Vault 内容并建立初始元数据索引。

资料来源：README.md, CLAUDE.md

使用示例

场景：组织身份认证笔记

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 进行跨域检索

# 列出所有 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 系统进行扩展：

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 三种交互方式

概述

时序知识图谱（Temporal Knowledge Graph）是 OMPA 项目的核心组件之一，用于存储和管理具有时间维度的事实三元组。与传统知识图谱不同，时序知识图谱为每个三元组关联了有效性时间窗口，使系统能够查询任意时间点的实体状态变化历史。

时序知识图谱基于 SQLite 实现，采用三重存储（Triple Store）模式，支持以下核心功能：

• 三元组（Subject-Predicate-Object）的增删改查
• 实体历史时间线查询
• 从 Vault 自动填充知识图谱
• 基于时间窗口的有效性过滤

资料来源：README.md

架构设计

核心概念

数据模型

时序知识图谱使用 SQLite 数据库存储三重数据，每个三元组包含以下字段：

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

双重 Vault 与知识图谱的关系

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

功能模块

1. 三元组管理

#### 添加三元组

ao.kg_add(subject, predicate, object_, valid_from=None, source=None)

参数说明：

示例：

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

#### 查询三元组

ao.kg_query(entity, as_of=None) -> list[Triple]

参数说明：

返回类型： list[Triple]，每个 Triple 包含 subject、predicate、object_、valid_from、valid_to、source 属性。

示例：

# 查询实体所有历史记录
triples = ao.kg_query("Kai")

# 查询特定时间点的状态
triples = ao.kg_query("Kai", as_of="2025-06-01")

资料来源：STABILITY.md

2. 时间线查询

ao.kg_timeline(entity) -> list[dict]

该方法返回指定实体的完整时间线，展示实体的所有关系变化历史。

返回格式：

[
    {
        "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"
    }
]

示例：

# 获取实体的完整时间线
timeline = ao.kg_timeline("Kai")

# 分析项目变更历史
for entry in timeline:
    print(f"{entry['valid_from']}: {entry['subject']} {entry['predicate']} {entry['object']}")

资料来源：ompa/mcp_server.py

3. 统计信息

ao.kg_stats() -> dict

返回知识图谱的统计信息，包括三元组总数、按谓词分组统计等。

示例：

stats = ao.kg_stats()
print(f"Total triples: {stats['total']}")
print(f"By predicate: {stats['by_predicate']}")

资料来源：ompa/mcp_server.py

4. 自动填充

时序知识图谱支持从 Vault 自动提取三元组，包括：

• 从 frontmatter 标签提取实体
• 从文件夹路径提取组织结构
• 从 [[wikilinks]] 提取关系

# 自动从 Vault 填充知识图谱
ao.kg.populate_from_vault()

工作流程：

graph LR
    A[扫描 Vault] --> B[解析笔记]
    B --> C[提取 frontmatter 标签]
    B --> D[解析 wikilinks]
    B --> E[分析文件夹路径]
    C --> F[生成三元组]
    D --> F
    E --> F
    F --> G[写入知识图谱]

资料来源：CHANGELOG.md

MCP 工具接口

OMPA 通过 MCP（Model Context Protocol）服务器暴露知识图谱功能，可在 Claude Desktop、Cursor、Windsurf 等工具中使用。

可用工具列表

资料来源：CLAUDE.md

MCP 使用示例

{
  "tool": "ao_kg_add",
  "arguments": {
    "subject": "Alice",
    "predicate": "reports_to",
    "object_": "Bob",
    "valid_from": "2025-01-15",
    "source": "org chart update"
  }
}

CLI 命令

kg-query

查询特定实体的所有三元组：

ao kg-query Kai

kg-timeline

获取实体的完整时间线：

ao kg-timeline Orion

kg-stats

查看知识图谱统计信息：

ao kg-stats

资料来源：README.md

版本演进

v0.3.0 — 自动填充功能

新增 KnowledgeGraph.populate_from_vault() 方法，支持从现有笔记中自动提取三元组。

资料来源：CHANGELOG.md

v0.4.0 — 双重 Vault 集成

时序知识图谱支持双重 Vault 架构，可在共享库和个人库之间独立维护知识图谱，并支持库之间的导入导出及数据脱敏。

资料来源：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

概述

消息分类器（Message Classifier）是 OMPA 系统的核心组件之一，负责自动识别和分类用户消息的类型，并将每条消息路由到相应的存储位置。该系统基于正则表达式模式匹配和决策树逻辑，实现了 15 种预定义消息类型的自动分类。

消息分类器的主要职责包括：

• 类型识别：通过正则表达式模式分析消息内容，确定消息属于哪种类型
• 路由建议：为每种类型提供存储路径建议和操作提示
• 双库支持：在双库模式下，自动判断消息应存储到共享库还是个人库
• CLI 集成：提供命令行工具 ao classify 用于手动消息分类

资料来源：ompa/classifier.py:1-50

系统架构

消息分类器采用分层架构设计，核心组件包括分类引擎、模式匹配器、路由控制器。

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 种消息类型，每种类型对应不同的业务场景和存储位置。

资料来源：ompa/classifier.py:1-100

分类流程

1. 模式匹配阶段

分类器使用预定义的正则表达式模式库 PATTERNS 对消息进行匹配。每个消息类型对应多组正则表达式，支持灵活的匹配策略。

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 类

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 模式库

每个消息类型定义多组正则表达式模式：

资料来源：ompa/classifier.py:100-150

FOLDER_MAP 文件夹映射

资料来源：ompa/classifier.py:150-200

双库模式集成

消息分类器与双库架构（Dual-Vault）紧密集成，支持自动内容隔离。

IsolationMode.AUTO 模式

在自动模式下，分类器根据消息类型自动判断存储目标：

# DualVaultConfig.classify_content() 集成
target = self.dual_config.classify_content(
    content=message,
    tags=tags,
    file_path=file_path
)

资料来源：ompa/core.py:50-80

自动分类规则

CLI 接口

ao classify 命令

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 协议暴露为工具：

{
  "name": "ao_classify",
  "description": "Classify a message and get routing hints"
}

资料来源：ompa/mcp_server.py:1-50

扩展消息类型

要添加新的消息类型，需完成以下步骤：

1. 添加枚举值

在 classifier.py 的 MessageType 枚举中添加新类型。

2. 添加正则模式

PATTERNS[MessageType.NEW_TYPE] = [
    r"\b(keyword1|keyword2)\b",
    r"\b(another pattern)\b",
]

3. 添加路由提示

ROUTING_HINTS[MessageType.NEW_TYPE] = [
    "Store in appropriate location",
    "Update relevant notes",
]

4. 添加文件夹映射

FOLDER_MAP[MessageType.NEW_TYPE] = "path/to/folder/"

5. 添加测试用例

在 tests/test_ompa.py 的 TestClassifier 类中添加测试用例。

资料来源：CONTRIBUTING.md:40-55

配置参数

消息分类器本身无需额外配置，但可通过环境变量影响其行为：

资料来源：examples/mcp_desktop/README.md:1-30

最佳实践

1. 消息预处理

• 消息应保持原始内容，不要提前摘要
• 移除敏感信息后再进行分类
• 包含足够的上下文以提高分类准确率

2. 置信度阈值

建议在下游处理中设置置信度阈值：

result = classifier.classify(message)
if result.confidence < 0.5:
    # 人工复核或使用默认分类
    pass

3. 自定义模式

可通过继承 Classifier 类添加自定义模式：

class CustomClassifier(Classifier):
    def _calculate_score(self, message: str, msg_type: MessageType) -> float:
        base_score = super()._calculate_score(message, msg_type)
        # 添加自定义评分逻辑
        return base_score

性能特性

分类器采用延迟模式编译策略，模式在首次使用时编译并缓存，确保高性能。

已知限制

• 依赖正则表达式，对语义理解有限
• 混合类型消息可能分类不准确
• 不支持多语言消息分类（当前仅英文模式）

相关资源

• CLAUDE.md - 架构决策文档
• STABILITY.md - API 稳定性保证
• 测试文件 tests/test_ompa.py - 分类器测试用例

概述

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的标准模式：

graph LR
    A["Claude/Cursor/Windsurf<br/>MCP Client"] <-->|"JSON-RPC<br/>stdin/stdout"| B["ompa.mcp_server<br/>Python Process"]
    B --> C["Ompa Core<br/>Vault + Palace + KG"]

服务器在初始化时返回协议版本和能力描述：

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请求：

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工具清单

工具分类表

资料来源：CLAUDE.md:1-15

知识图谱工具详解

#### ao_kg_add

添加三元组到知识图谱：

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,
)

参数说明：

资料来源：ompa/mcp_server.py:90-100

桌面客户端配置

Claude Desktop

#### 方式一：CLI命令（推荐）

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/your/vault"
      }
    }
  }
}

配置完成后需重启Claude Desktop应用。

资料来源：examples/mcp_desktop/README.md:1-40

Cursor

在项目根目录创建 .cursor/mcp.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：

{
  "mcpServers": {
    "ompa": {
      "command": "python",
      "args": ["-m", "ompa.mcp_server"],
      "env": {
        "OMPA_VAULT_PATH": "/path/to/vault"
      }
    }
  }
}

资料来源：examples/mcp_desktop/README.md:25-35

环境变量配置

配置项总览

资料来源：examples/mcp_desktop/README.md:70-85

语义搜索配置

默认情况下，语义搜索功能关闭。如需启用本地语义搜索（首次运行会下载约500MB的all-MiniLM-L6-v2模型）：

pip install ompa[all]

然后在MCP配置的env块中设置：

{
  "env": {
    "OMPA_ENABLE_SEMANTIC": "true"
  }
}

后续运行将直接使用缓存模型，无额外下载。

资料来源：examples/mcp_desktop/README.md:40-50

双保险库模式集成

MCP服务器支持双保险库架构，可隔离团队/组织内容与个人私密笔记。

MCP配置示例

{
  "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"
      }
    }
  }
}

隔离模式

资料来源：examples/mcp_desktop/README.md:100-120

连接验证

配置完成后，可通过以下方式验证连接：

1. 在支持MCP的客户端中，询问AI助手：

"Use the ao_status tool to check my OMPA vault health"

1. 预期响应应包含保险库统计信息。

常见问题排查

资料来源：examples/mcp_desktop/README.md:120-135

框架兼容性

OMPA的MCP服务器支持多种AI代理框架：

MCP服务器为框架无关的纯Python实现，无代理SDK依赖。

资料来源：README.md:60-75

启动方式汇总

启动命令对照表

所有启动方式均要求目标保险库已通过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 — 架构决策与内部API文档
• STABILITY.md — API稳定性保证
• CONTRIBUTING.md — 添加新MCP工具的指南

架构概览

OMPA 适配器层采用了适配器模式（Adapter Pattern），将 OMPA 的核心功能封装为各框架所期望的接口形式。这种设计使得 OMPA 可以作为多种 AI 框架的底层存储和检索后端，而无需修改框架本身的代码。

graph TB
    subgraph "AI 应用层"
        LC[LangChain 应用]
        LI[LlamaIndex 应用]
        OAI[OpenAI Agents]
        CUSTOM[自定义应用]
    end
    
    subgraph "适配器层"
        LCM[OmpaMemory<br/>OmpaRetriever]
        LIC[OmpaReader<br/>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

可用适配器列表

资料来源：STABILITY.md

LangChain 适配器

LangChain 适配器提供了与 LangChain 框架的深度集成，支持将 OMPA 作为聊天记忆存储和检索后端使用。

OmpaMemory

OmpaMemory 是实现 LangChain BaseChatMemory 接口的记忆组件，它将 OMPA 保险库作为持久化存储层。

主要方法：

load_memory_variables(inputs) -> dict
save_context(inputs, outputs) -> None
clear() -> None

使用示例：

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 链中的检索器使用。

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 的文档格式。

from ompa.adapters.llamaindex import OmpaReader

reader = OmpaReader(vault_path="./workspace")
documents = reader.load_data()

OmpaVaultRetriever

OmpaVaultRetriever 提供了对 OMPA 保险库的向量检索能力，可直接集成到 LlamaIndex 的查询引擎中。

from ompa.adapters.llamaindex import OmpaVaultRetriever

retriever = OmpaVaultRetriever(vault_path="./workspace")

OpenAI Agents SDK 适配器

OmpaAgentHooks 为 OpenAI Agents SDK 提供了 OMPA 的生命周期钩子集成。

from ompa.adapters.openai_agents import OmpaAgentHooks

hooks = OmpaAgentHooks(vault_path="./workspace")
# 在 OpenAI Agents 应用中注册钩子

向量存储适配器

NIMEmbeddingBackend

NIMEmbeddingBackend 提供了与 NVIDIA NIM（NVIDIA Inference Management）服务的集成，用于生成嵌入向量。

from ompa.adapters.nim import NIMEmbeddingBackend

backend = NIMEmbeddingBackend(
    api_key="your-api-key",
    model="nvidia/nvolve-4q"
)

FAISSSemanticIndex

FAISSSemanticIndex 使用 Facebook AI Similarity Search (FAISS) 库实现高效的向量相似度搜索。

from ompa.adapters.faiss import FAISSSemanticIndex

index = FAISSSemanticIndex(vault_path="./workspace")

安装依赖

不同的适配器需要不同的可选依赖包：

# LangChain 适配器
pip install ompa[langchain]

# LlamaIndex 适配器
pip install ompa[llamaindex]

# 所有适配器
pip install ompa[all]

稳定性说明

根据项目稳定性策略，适配器接口在以下方面保持稳定：

• 公共方法签名
• 构造函数参数
• 返回值类型

适配器的内部实现细节可能在次版本更新中发生变化，但公共 API 将保持向后兼容。 资料来源：STABILITY.md

最佳实践

1. 惰性初始化：适配器支持惰性加载模型和索引，避免在导入时触发大量资源下载。
2. 会话管理：在长时间运行的 AI 应用中，确保在应用关闭时正确清理资源。
3. 并发访问：多个框架实例可以同时访问同一个 OMPA 保险库，适配器已处理并发读写场景。
4. 配置分离：建议将不同框架的适配器配置分离管理，便于独立调试和优化。

扩展适配器

开发者可以通过实现相应的协议（Protocol）接口来创建自定义适配器：

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

与核心模块的关系

graph LR
    subgraph "适配器层"
        LANG[LangChain]
        LLAMA[LlamaIndex]
        OAI[OpenAI Agents]
    end
    
    subgraph "OMPA 核心"
        VAULT[Vault<br/>笔记持久化]
        KG[Knowledge Graph<br/>三元组存储]
        SEM[Semantic Index<br/>向量索引]
    end
    
    LANG --> VAULT
    LANG --> SEM
    LLAMA --> VAULT
    LLAMA --> SEM
    OAI --> VAULT
    OAI --> KG

适配器层负责将框架特定的接口转换为 OMPA 核心模块的标准调用，实现了框架解耦和应用灵活性的平衡。

Pitfall Log / 踩坑日志

项目：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