Ogham Mcp

手动设置

如果你更愿意自行配置，而不是使用向导：

# Supabase
export SUPABASE_URL=https://your-project.supabase.co
export SUPABASE_KEY=your-service-role-key
export EMBEDDING_PROVIDER=openai  # or ollama, mistral, voyage
export OPENAI_API_KEY=sk-...      # for your chosen provider

# Or Postgres (Neon, self-hosted)
export DATABASE_BACKEND=postgres
export DATABASE_URL=postgresql://user:pass@host/db
export EMBEDDING_PROVIDER=openai
export OPENAI_API_KEY=sk-...

运行架构迁移（Supabase 使用 sql/schema.sql，Neon/自托管环境使用 sql/schema_postgres.sql），然后将 MCP 服务添加到你的客户端。

安装方式

Claude Code

claude mcp add ogham -- uvx ogham-mcp

OpenCode ——添加到 ~/.config/opencode/opencode.json：

{
  "mcp": {
    "ogham": {
      "type": "local",
      "command": ["uvx", "ogham-mcp"],
      "environment": {
        "SUPABASE_URL": "https://your-project.supabase.co",
        "SUPABASE_KEY": "{env:SUPABASE_KEY}",
        "EMBEDDING_PROVIDER": "openai",
        "OPENAI_API_KEY": "{env:OPENAI_API_KEY}"
      }
    }
  }
}

Docker

docker run --rm \
  -e SUPABASE_URL=https://your-project.supabase.co \
  -e SUPABASE_KEY=your-key \
  -e EMBEDDING_PROVIDER=openai \
  -e OPENAI_API_KEY=sk-... \
  ghcr.io/ogham-mcp/ogham-mcp

从源代码安装

git clone https://github.com/ogham-mcp/ogham-mcp.git
cd ogham-mcp
uv sync
uv run ogham --help

HTTP 传输（多 Agent）

默认情况下，Ogham 以 stdio 模式运行——每个 MCP 客户端都会启动自己的服务进程。若要让多个 Agent 共享一个服务，可通过 HTTP 运行：

ogham serve --transport streamable-http --port 8742

服务会作为持久后台进程运行。所有客户端都连接到同一个实例——共用一个数据库连接池、一个嵌入缓存和一份共享记忆。

客户端配置（适用于任何 MCP 客户端）：

{
  "mcpServers": {
    "ogham": {
      "url": "http://127.0.0.1:8742/mcp"
    }
  }
}

可通过 http://127.0.0.1:8742/health 进行健康检查（结果会缓存，耗时不到 10 毫秒）。可通过环境变量（OGHAM_TRANSPORT=streamable-http、OGHAM_HOST、OGHAM_PORT）或 CLI 标志进行配置。http 可用作 streamable-http 的别名。

在 Docker 中，请绑定到所有网络接口。 默认主机是 127.0.0.1，在容器内这意味着容器自身——发布端口也无法访问该服务：

docker run -p 8742:8742 ghcr.io/ogham-mcp/ogham-mcp:latest \
  serve --transport streamable-http --host 0.0.0.0 --port 8742

在 AMB 基准测试框架上，QA 准确率达到 85.8%（500 个问题，2026 年 4 月）——使用带推理能力的 GPT-5-mini 正确回答了 429/500 个问题，并由 Gemini 2.5 Flash Lite 作为严格判定器进行评估。检索 R@10：99.5%。AMB 是由 Vectorize 团队（Hindsight 的创建者）构建的标准化评估框架。感谢 Nicolo 和 Vectorize 团队开放该框架。

此前：在我们的内部 LongMemEval 基准测试流程中达到 91.8%（gpt-5.4-mini 阅读器，评分标准判定器）。AMB 的结果较低，是因为它采用了更严格的子串匹配判定器——方法差异请参阅完整说明。

在 BEAM 100K 上获得 0.554 nugget 分数（ICLR 2026，涵盖 10 种记忆能力的 400 个问题），使用论文附录 G 中完全相同的判定提示词。已发表的基线为 0.358（Llama-4-Maverick + LIGHT）。检索 R@10：0.737。九个类别中有七个优于论文结果。完整说明。

LongMemEval 上的端到端 QA 准确率（检索 + 大模型读取并回答）：

仅检索（R@10 —— 搜索循环中不使用 LLM）：

其他报告类似 R@10 数值的检索系统通常会使用交叉编码器重排序、NLI 验证、知识图谱增强以及 LLM 评判流水线。Ogham 仅用一条 Postgres 查询就达到 97.2%。可选的 FlashRank 重排序适用于希望进一步提高排序精度的自托管用户。

这些表格衡量的是不同的指标。QA 准确率用于测试完整系统（检索 + LLM）能否给出正确答案。R@10 用于测试仅靠检索能否找到正确记忆。Ogham 是一款检索引擎——它负责找到记忆，再由你的 LLM 阅读。

完整细分：ogham-mcp.dev/features

Ogham 的检索流程结合了成熟的信息检索与认知科学技术：

• 混合搜索——倒数排名融合（Cormack、Clarke 和 Butt，SIGIR 2009），将稠密向量相似度（pgvector）与 BM25 风格的关键词匹配（PostgreSQL tsvector）结合。两个独立的检索系统进行排名融合，不进行分数归一化。

• 实体重合度加权——与查询共享命名实体的记忆会获得有限的相关性加权（最高 1.4x），灵感来自实体链接研究（Kolitsas 等人，CoNLL 2018）。实体提取通过基于 YAML 的词表覆盖 18 种语言，不在写入流程中调用大模型。

ogham init                      # Interactive setup wizard
ogham health                    # Check database + embedding provider
ogham config                    # Show runtime configuration (secrets masked)
ogham store "some fact"         # Store a memory
ogham search "query"            # Search memories (hybrid: semantic + keyword)
ogham search "q" --json         # JSON output for scripting
ogham search "q" --tags "a,b"   # Filter by comma-separated tags
ogham list                      # List recent memories
ogham list --json               # JSON output
ogham delete <id>               # Delete a memory by ID
ogham use <profile>             # Switch default profile
ogham profiles                  # List profiles and counts
ogham stats                     # Profile statistics
ogham export -o backup.json     # Export memories (JSON)
ogham export --format markdown  # Export as Obsidian-compatible markdown
ogham export --format okf       # Export as Open Knowledge Format v0.1 bundle
ogham import backup.json        # Import a JSON export
ogham import <okf-bundle-dir>   # Import an OKF bundle directory (auto-detected)
ogham import <dir> --with-graph # ...including its entities/ graph layer (opt-in)
ogham cleanup                   # Remove expired memories
ogham hooks install             # Auto-detect client + configure hooks
ogham hooks recall              # Read from the stone (load project context)
ogham hooks inscribe            # Carve into the stone (capture activity)
ogham hooks inscribe --dry-run  # Preview hook memory without storing
ogham serve                     # Start MCP server (stdio, default)
ogham serve --transport http    # Start HTTP server on port 8742
ogham openapi                   # Generate OpenAPI spec

多配置文件搜索 —— 在单个查询中跨多个配置文件搜索（v0.8.5+）：

# MCP tool
hybrid_search(query="architecture decisions", profiles=["work", "shared"])

# Python library
from ogham.service import search_memories_enriched
results = search_memories_enriched(
    query="architecture decisions",
    profile="work",
    profiles=["work", "shared", "project-alpha"],
)

设置 profiles 后，结果会包含所有列出的配置文件中的记忆，并附带 profile 字段，指明每条结果来自哪个配置文件。

嵌入提供方

EMBEDDING_DIM 必须与数据库架构中的 vector(N) 列匹配。默认架构使用 vector(512)。如果使用 Mistral，必须先将该列改为 vector(1024)，然后才能存储任何内容。 每个提供商对向量的聚类方式都不同，因此相似度阈值很重要。请从推荐值开始，并根据结果进行调整。

时间搜索——包含“上周”或“三个月前”等时间表达的查询会通过 parsedatetime 自动解析，无需配置。这种方式可以零成本处理大约 80% 的时间查询。对于 parsedatetime 无法解析的表达（“上上个季度”“感恩节前后”），请设置 TEMPORAL_LLM_MODEL，以便在无法解析时调用大模型：

# Self-hosted with Ollama (free, local)
TEMPORAL_LLM_MODEL=ollama/llama3.2

# Cloud API
TEMPORAL_LLM_MODEL=gpt-4o-mini

任何兼容 litellm 的模型字符串都可以使用——deepseek/deepseek-chat、moonshot/moonshot-v1-8k 等。只有当 parsedatetime 解析失败且查询包含时间意图时，才会调用大模型，因此成本几乎为零。如果 TEMPORAL_LLM_MODEL 为空（默认值），则由 parsedatetime 独立处理所有内容。需要安装 litellm 包。

Ogham 钩子会在会话开始时注入记忆上下文，并在压缩后保留记忆。请为你的客户端安装：

ogham hooks install

这两个命令以 Ogham 石碑命名：

• recall——从石碑中读取。在 Ogham 中搜索与你的项目相关的记忆，并将其作为上下文注入。在会话开始和压缩后触发。
• inscribe——将内容刻入石碑。将有意义的工具活动保存为记忆。跳过无关内容（ls、cat、git status），只保存有价值的信息（提交、部署、错误、配置更改）。在使用工具后和压缩前触发。保存前会屏蔽密钥。

如果你希望 Agent 连接到 Ogham，但不让它将记忆提取到上下文中或写入新记忆，可以禁用任一流程：

OGHAM_RECALL_ENABLED=false ogham serve       # no context injection / memory search
OGHAM_INSCRIBE_ENABLED=false ogham serve     # no memory capture / content writes
ogham hooks recall --no-recall               # one-off hook recall skip
ogham hooks inscribe --no-inscribe           # one-off hook capture skip
ogham search "query" --no-recall             # one-off CLI search skip
ogham store "some fact" --no-inscribe        # one-off CLI store skip

对于 MCP 客户端，请将环境变量放入该客户端的 Ogham 服务配置中：

{
  "mcpServers": {
    "ogham": {
      "command": "ogham-serve",
      "env": {
        "OGHAM_RECALL_ENABLED": "false",
        "OGHAM_INSCRIBE_ENABLED": "false"
      }
    }
  }
}

即使 recall 或 inscribe 已禁用，配置、健康状态、统计、审计、导出、删除和清理等管理操作仍可使用，因此你仍然可以检查或清理记忆。

**智能筛选：**钩子不会捕获所有内容。常规命令（ls、pwd、git add）会被跳过。只保存有价值的事件（错误、部署、提交、配置更改）——每个会话通常保存 20-30 条记忆，而不是数百条。

**密钥屏蔽：**API 密钥、令牌、密码和 JWT 会在保存前自动替换为 ***MASKED***。事件会被捕获（“配置了 Stripe API 密钥”），但实际密钥绝不会进入数据库。

记忆操作

搜索

知识图谱

带类型边的图谱（v0.16） -- 用于双事实联接查询的结构化类型关系。详情见 /docs/typed-edges/。

引用实体（v0.19）。 实体以 (canonical_name, entity_type) 为键，因此仅凭名称并不总能确定实体。 同一个词可能合理地属于两种类型 -- ValueError 既是 entity:（内部含大写字母），也是 error:（以 Error 为后缀）。请传递 限定引用以明确指定：

store_triple(subject="error:ValueError", ...)   # exactly the error node
store_triple(subject="ValueError", ...)         # lowest-id match, and logs the collision

未限定的引用仍会确定性地解析，并在必须进行选择时发出警告。v0.19 之前，解析时不会发出警告。

证据类别（v0.19）。 现在每个实体都会记录它是如何确定的：

它有意不作为置信度分数。校准是估计概率的一项属性（Guo、Pleiss、Sun 和 Weinberger，ICML 2017）； 每条规则对应一个固定类别，并不进行任何估计，因此此处使用浮点数会诱使使用方将其乘入相关性分数，仿佛它代表某种含义。它是一个带有 CHECK 约束的枚举值。

升级时会根据现有实体的类型为其分类。目前检索过程尚未读取该值 -- 保留它是为了在增强流程开始写入实体时，能够区分机器建议的实体和由适配器得出的事实。

导入器

配置档案

导入 / 导出

--format okf 会写入符合 Open Knowledge Format v0.1 规范的捆绑文件：目录中每条记忆对应一个 Markdown 文件，并带有 YAML frontmatter；捆绑根目录下的 index.md 声明 okf_version: "0.1"；还有一个独立的 viewer.html（Cytoscape.js 图谱，可通过 file:// 打开，无需服务器或 CDN）。往返导入导出会保留 UUID、内容、标签、来源和元数据；导入时会重新生成嵌入。传入 include_viewer=false 可跳过 HTML 图谱。背景信息请参见 OKF 往返导入导出说明。

维护

Wiki 层可将一组相关记忆标签整理为综合 Markdown 页面。对某个标签运行 compile_wiki，即可获得主题摘要；底层记忆发生变化时，缓存会自动失效。四个 MCP 工具涵盖整个生命周期：

Wiki 层需要大模型。 综合整理这一步由大模型完成，它会将记忆列表转化为连贯的页面；仅靠嵌入还不够。你可以在本地运行大模型（Ollama 搭配 llama3.2、vLLM，或任何兼容 OpenAI 的本地服务），也可以在云端运行（Gemini、OpenAI、Anthropic、Mistral、Groq、OpenRouter）。本地运行可确保内容私密且免费；云端通常能生成更精炼的文字，但每次编译需要花费几分钱。

将 Wiki 层快照导出到一个包含 Obsidian 兼容 Markdown 文件的文件夹。每个主题对应一个 .md 文件，包含完整的 YAML frontmatter，另附一个 README.md 索引。系统会自动检测主题之间的 Wikilink，并将其括在 [[brackets]] 中，以便在 Obsidian 的关系图视图中显示。

ogham export-obsidian /path/to/vault
ogham export-obsidian /path/to/vault --profile work --force

导出为只读操作——它会写入文件，但不会读取文件。你在 Obsidian 中所做的编辑只会保留在 Obsidian 中；重新运行导出即可刷新快照。按照设计，导出器不会写入已包含非其创建文件的目录；传入 --force 可覆盖此安全限制。

完整指南（含 frontmatter 参考、故障排查和截图）：Obsidian 导出文档。

让记忆数据可往返移植。Ogham 支持读写 开放知识格式（OKF）v0.1，这是一种基于 Markdown 的交换格式，由 Google Cloud 于 2026 年 6 月发布。同一数据包可移植到任何其他支持 OKF 的工具中——例如 Google 的 Knowledge Catalog、同事自行开发的读取器，或你未来构建的系统。

# Export your profile as an OKF v0.1 bundle directory
ogham export --format okf

# Round-trip it back (auto-detected as an OKF bundle)
ogham import ogham-okf-<profile>-<timestamp>

数据包的目录树如下：

ogham-okf-<profile>-<timestamp>/
├── index.md                     # declares okf_version: "0.1" (+ ogham_graph_version: 1)
├── context.jsonld               # predicate URIs, with Schema.org alignments where they fit
├── viewer.html                  # self-contained Cytoscape.js graph (opens with file://)
├── memories/
│   ├── <slug>-<uuid8>.md        # one markdown file per memory
│   └── ...
└── entities/                    # present only if the profile has a typed-edge graph
    ├── <slug>-e<entity_id>.md   # one file per entity, edges as frontmatter triples
    └── ...

每个记忆文件都包含 YAML frontmatter（type、id、tags、timestamp、source，以及可选的 title），并以 Markdown 格式保存记忆正文。type: 根据字母顺序排列后第一个 type:X 标签生成（若没有则默认为 Memory）。往返操作会保留 UUID、内容、标签、来源和所有扩展元数据；导入时会重新生成嵌入向量。

viewer.html 是一个 425 KB 的独立文件，内联打包了 Cytoscape.js（MIT）——无需服务端、互联网或 CDN。通过 file:// 在任何浏览器中打开，即可查看按类型着色的记忆关系图，边则对应数据包内的 Markdown 链接。传入 include_viewer=false 可跳过此文件。

导入行为：

• 带有 id: 扩展字段的记忆会按 UUID 执行 upsert（重复导入具有幂等性）。
• 不带 id: 的记忆会作为新记忆插入；其数量会在结果中的 missing_id_count 字段显示。
• 导入器要求数据包根目录中包含声明了 okf_version 的 index.md，因此若指向随机目录会立即失败。

导入实体关系图为可选功能，默认关闭：

# See what it would do -- writes nothing
ogham import <bundle> --with-graph --graph-dry-run

# Actually import the entities/ layer
ogham import <bundle> --with-graph

默认关闭是因为 entities 表没有 profile 列——它仅通过 memory_entities 和 entity_edges 进行全局范围控制——因此导入关系图会影响每个 profile 读取的行。

运行之前有两点值得了解：

• 它会合并，而不是还原。 导入到已有图谱的配置文件时，会将匹配的边向前移动，而不会将配置文件恢复到数据包中的状态。导入到全新的配置文件时，结果则完全一致。
• 无法撤销，因此提供了试运行。 先对配置文件做快照并不能实现撤销——快照由同一导出路径生成，而且边限定条件无法通过此路径往返保留。--graph-dry-run 会准确报告实际运行将执行的操作：要创建的实体、要写入的边、已存在的边，以及目标缺失于数据包中的边。

可以安全地重复运行。已存在的边会被跳过，而不是重写，因此部分失败后重试会逐步收敛，不会反复变动。

适用范围：仅适用于你自己的数据包。不支持导入他人安装中的数据包——读取器针对数据损坏做了边界限制，但并未防范恶意数据包。

面向用户的介绍：Ogham v0.15 speaks Open Knowledge Format。

从 Claude Code（自动记忆 MD 文件）导入

Claude Code 的自动记忆系统会在 ~/.claude/projects/<encoded-cwd>/memory/ 下为每个项目写入笔记。每条笔记都是一个带有 YAML 前置元数据（name、description、type、可选的 originSessionId）的 Markdown 文件。将它们导入 Ogham：

ogham import-claude-code ~/.claude/projects/<encoded-cwd>/memory \
    --project ogham --dedup 0.8

每个可解析的文件都会变成一条 Ogham 记忆，并标记为 source:claude-code-memory + type:<frontmatter type> + project:<inferred or explicit>。MEMORY.md（索引）和点文件会被跳过。无法识别前置元数据的文件会记录警告并跳过。

对于包含连字符的仓库名称，encoded-cwd 目录命名会造成信息丢失：openbrain-sharedmemory 会被解码为 sharedmemory，因为每个 / 和 - 都会变成相同的分隔符。传入 --project NAME 可覆盖推断出的标签，并保持项目标签一致。

导入器会遵循 inscribe_enabled()——--no-inscribe 和 OGHAM_INSCRIBE_ENABLED=false 都会跳过导入。重复运行时会通过 --dedup 余弦阈值（默认值为 0.8）安全去重。MCP 工具：import_claude_code_memories(directory, project_tag=...)。

从 Claude.ai（对话数据导出）导入

Anthropic 提供官方数据导出功能，路径为 Settings → Privacy → Request your data。约 24-48 小时后，你会收到一个包含 conversations.json 的 ZIP 文件。将其导入 Ogham：

ogham import-claude-ai ~/Downloads/data-<id>-batch-0000 --profile claude-ai

接受 ZIP 文件本身、解压后的目录，或直接传入 conversations.json。每组 (human, assistant) 轮次对会变成一条记忆，内容为助手轮次（你要搜索的信号），人类提示词则保存在 metadata.user_prompt 中（可用于还原上下文）。标签：source:claude-ai、claude-conversation:<title-slug>，以及可选的 project:<tag>。

保守的智能过滤器会丢弃客套话交流；传入 --no-smart-filter 可保留这些内容。使用 --since 2026-01-01 只导入近期对话，或使用 --mode raw，按单条消息而非轮次对导入，每条消息生成一条记忆。

若要获取导入对话的 LLM 提炼摘要，请通过 MCP 调用 compile_wiki(topic="claude-conversation:<slug>")。先逐字导入，再按需综合，既能保留原始轮次，也能获得摘要，而导入器无需预先调用大模型。源记忆发生变化时，摘要会重新生成。

导出文件中的 UUID 会保存在元数据中，因此之后重新导入同一导出文件时，只会添加新的轮次。MCP 工具：import_claude_ai_export(path, profile, mode=...)。

Ogham 会在写入时从每条已存储的记忆中提取实体标签（人物、文件、错误、位置、项目——纯正则表达式，不使用大模型）。v0.14 新增了实时接线，使这些标签也会填充到单独的实体图谱中，用于扩散激活检索和跨记忆关联建议。

在现有部署上应用迁移 036 后，运行一次性回填以填充历史记忆：

ogham backfill-entities --profile work

回填会遍历记忆表，运行实体提取器，并通过 link_memory_entities 将每条记忆关联到对应实体。ON CONFLICT DO NOTHING 可确保重复运行不会产生额外开销。v0.14 之后的新写入会自动关联；回填仅适用于升级前创建的记忆。

图谱填充完成后：

• suggest_connections 会返回与锚点记忆共享实体的记忆（此前始终返回空结果）。
• entity_graph_density 会返回实际数值（每个配置文件中不同实体和边的数量）。
• spread_entity_activation_memories RPC 会遍历二分记忆／实体图谱，以进行上下文丰富的检索。

MCP 工具：backfill_entities(profile=None, batch_size=200)。

评分和精简——三项服务端功能会自动运行，无需配置：

• 新颖度检测。 存储记忆时，Ogham 会检查它与现有内容的相似程度。冗余内容的新颖度得分会较低，在搜索结果中的排名也会靠后。你仍然可以找到它，但它不会挤掉更有用的记忆。
• 内容信号评分。 提及决策、错误、架构或包含代码块的记忆会获得更高的信号分数。修复实际错误的调试会话，排名会高于随手记录的会议笔记。评分完全基于正则表达式，不涉及大模型。
• 自动精简。 无人访问的旧记忆会逐渐缩短。全文会先变成关键句摘要，再变成附带标签的一行描述。原始内容始终会保留；如果记忆再次变得相关，可以将其恢复。可手动运行 compress_old_memories，也可按计划运行。重要性高且访问频繁的记忆不易被精简。

实体增强——每条记忆在写入时都会自动添加结构化实体标签；不调用大模型，完全通过正则表达式和词典匹配，支持 18 种语言：

• 六类实体。 事件（婚礼、音乐会、会议）、活动（徒步、编程、烹饪）、情绪（沮丧、开心、如释重负）、关系（姐妹、老板、同事）、数量（3 本书、5 英里）和地点（柏林、东京——通过 GeoNames 数据库识别）。
• 18 种语言。 英语、德语、法语、西班牙语、意大利语、葡萄牙语、巴西葡萄牙语、荷兰语、波兰语、俄语、乌克兰语、土耳其语、阿拉伯语、印地语、日语、韩语、中文和爱尔兰语。每种语言都包含常见的变形形式（格词尾、动词时态、辅音弱化），因此，俄语中的 “svadʹbu” 可以匹配 “svadʹba”，爱尔兰语中的 “bhainis” 可以匹配 “bainis”。
• 时间线表格。 搜索结果包含按时间顺序排列的时间线，其中预先计算了“距今几天”并提供记忆 ID 交叉引用。这有助于大模型读者回答与时间相关的问题，而无需进行日期计算。
• Lost in the Middle 重排。 搜索结果会重新排序，使相关性最高的记忆出现在上下文的开头和结尾，即大模型最关注的位置（Liu 等人，2023）。

交叉编码器重排 —— 为希望提高排序精度的可自托管用户提供可选的 FlashRank 交叉编码器重排。在 CPU 上每次搜索约增加 300ms。Ogham 的混合搜索返回候选结果后，FlashRank（ms-marco-MiniLM-L-12-v2，21MB）会使用更深入的 token 级注意力，根据查询对每条结果重新评分。最终得分综合检索排序和交叉编码器排序。

对 BEAM 基准测试的影响：R@10 从 0.69 提升至 0.70，MRR 提升 8 个百分点。最大提升出现在时间推理方面，从 0.84 提升至 0.98。完整结果。

pip install ogham-mcp[rerank]
# or: uv add ogham-mcp[rerank]

export RERANK_ENABLED=true
export RERANK_ALPHA=0.55   # 55% cross-encoder, 45% retrieval score

模型会在首次使用时下载（约 21MB）。更重视速度而非精度的可自托管用户可以关闭此功能（默认设置）。

ONNX 本地嵌入 —— 使用 ONNX Runtime 在本地运行 BGE-M3，在单次模型处理中生成稠密向量和稀疏向量，无需 API 调用，也无需 GPU。由 @ninthhousestudios 贡献。ONNX 提供器会生成 1024 维稠密向量和神经稀疏向量。稀疏向量可用时，Ogham 会自动使用三信号 Reciprocal Rank Fusion（稠密向量 + FTS + 稀疏向量），替代默认的双信号路径。

pip install ogham-mcp[onnx]

# Download the model (~2.2GB)
ogham download-model bge-m3

export EMBEDDING_PROVIDER=onnx
export EMBEDDING_DIM=1024

数据库架构中的嵌入列必须使用 vector(1024)。CPU 性能：每段简短文本约 0.3s，长文档（5K+ 字符）约 10s。RSS 峰值约为 4.3GB。ONNX 提供器专为希望实现零 API 成本的可自托管用户设计。云端用户应使用 Gemini 或 Voyage，以获得更低延迟。

Ogham 支持 Supabase 或原生 PostgreSQL。运行与你的设置相匹配的架构文件：

Supabase 和 Neon 都已内置 pgvector，无需额外设置。如果你要自托管 Postgres，则需要安装了 pgvector 扩展的 PostgreSQL 15+。我们的开发和测试环境使用 PostgreSQL 17。对于 Postgres，请在环境中设置 DATABASE_BACKEND=postgres 和 DATABASE_URL=postgresql://...。

本地 pgvector 测试数据库 —— Postgres 集成测试仅在临时数据库上运行。它们会通过 PostgreSQL + pgvector 处理真实的记忆记录，但除非 DATABASE_URL 包含 scratch 或设置了 OGHAM_TEST_ALLOW_DESTRUCTIVE=1，否则会跳过测试。这样可以避免常规 pytest 运行接触个人或生产环境中的 Ogham 数据库。

make test-postgres-db

export DATABASE_BACKEND=postgres
export DATABASE_URL=postgresql://ogham:ogham@localhost:5433/ogham_scratch

uv run pytest -m postgres_integration
# or:
make test-postgres

测试框架会将规范的 sql/schema_postgres.sql 应用到一个空的临时数据库，并在较旧的临时数据库上重新应用当前测试所需的幂等基线迁移。外部 Supabase + Ollama 集成测试为可选项：

OGHAM_RUN_EXTERNAL_INTEGRATION=1 uv run pytest -m integration -v
# or:
make test-external

升级现有 Ogham 数据库

对于 v0.10.x → v0.11.0（记忆生命周期版本），请参阅 UPGRADING.md。简而言之：

./sql/upgrade.sh $DATABASE_URL     # applies 025 + 026 + 027 idempotently

全新安装无需执行此操作——sql/schema.sql 已反映 v0.11.0 之后的状态。

对于更早版本（v0.4.x 至 v0.10.x），同一个 upgrade.sh 脚本会按顺序执行每项迁移——时间列、halfvec 压缩、稀疏嵌入、RRF/BM25 搜索，然后是 v0.11.0 生命周期新增内容。每项迁移都是幂等的。

# Postgres / Neon (psql required)
./sql/upgrade.sh $DATABASE_URL

# Supabase: paste migration files into the SQL Editor in order
#   (025_memory_lifecycle.sql → 026_memory_lifecycle_split.sql → 027_audit_log_backfill.sql
#   are the v0.11.0 set)

部分迁移要点：

• 016 添加 sparse_embedding 列，用于存储 ONNX BGE-M3 稀疏向量。
• 017 将搜索函数升级为真正的倒数排名融合，并采用长度归一化的关键词评分（Cormack 等人，2009）。
• 025 / 026 添加记忆生命周期表和触发器（参见 UPGRADING.md）。
• 027 为早于 audit_log 表的安装补填该表。

回滚脚本位于 sql/migrations/rollback/ 下，文件名前缀为 DANGER_，执行任何操作前都需要显式启用会话变量。请参阅 sql/migrations/rollback/README.md。

所有迁移都是幂等的，可安全重复运行。升级脚本会检查 pgvector 版本；如果 pgvector 低于 0.7.0，则会跳过 halfvec。全新安装无需迁移——架构文件已包含所有内容。

升级 CLI（uv tool）——uv 会积极缓存。新版本发布后，直接运行 uv tool install ogham-mcp 可能会安装旧版本。使用 --refresh 可强制从 PyPI 重新解析：

uv tool uninstall ogham-mcp
uv cache clean
uv tool install --refresh "ogham-mcp[gemini,postgres]"

使用 ogham config 验证（顶部会显示版本和提供方）。如果仍显示旧版本，请彻底删除工具环境目录后重试：

rm -rf ~/.local/share/uv/tools/ogham-mcp
uv tool install --refresh "ogham-mcp[gemini,postgres]"

这是一个已知的 uv 缓存行为——解析器缓存与包缓存相互独立，即使运行 uv cache clean，不带 --refresh 时也会保留解析器缓存。

Ogham 在 skills/ 中附带了三个工作流技能，用于串联常见的 MCP 工具链。可将它们安装到 Claude Code、Cursor 或任何支持技能的客户端中。

技能会调用现有的 MCP 工具——不会取代它们。必须连接 MCP 服务，技能才能正常工作。

npx skills add ogham-mcp/ogham-mcp                        # all three
npx skills add ogham-mcp/ogham-mcp --skill ogham-recall   # one
cp -r skills/ogham-research skills/ogham-recall skills/ogham-maintain ~/.claude/skills/   # manual