快速上手

按你的使用方式选一条路线：用桌面端管理知识，或接入 Cursor 让 Agent 主动读写上下文。

选择使用方式

桌面端

像笔记一样整理、检索你的知识库
CLI + Cursor

把 OpenContext 接进 Cursor，让 Agent 通过工具读取/沉淀上下文
仅 CLI

纯命令行管理、检索与脚本化
A

桌面端

推荐

适合大多数人：用桌面端创建/整理文档，需要时把引用粘贴到 Cursor/Agent 即可。

1 下载桌面端

下载 macOS / Windows 版

跳转至 GitHub Releases

2 首次使用：建目录 + 写第一篇文档

  • 新建一个目录（如 personal/ 或 project-x/）
  • 写下第一篇文档（哪怕先是草稿）

建议从这些开始：项目背景、验收标准、接口约定、常见坑。

3 检索内容

  • 快捷键： Cmd/Ctrl + K
  • 可搜索标题、描述与正文。
  • 需要语义检索：在 Settings → Embedding 填入 API Key（桌面端会自动构建索引）。

4 引用到 Cursor / Agent 可选

桌面端支持复制引用：让 Agent 读取指定片段/整篇文档/整个目录，并保留来源。

操作 步骤 效果
引用文本片段 选中文本 → 右键 → "复制引用" Agent 读取片段 + 来源
引用整篇文档 点击文档标题旁的引用图标 Agent 获得完整文档 + stable_id
引用整个文件夹 右键文件夹 → "复制文件夹引用" Agent 批量读取所有文档

5 什么时候需要 CLI？

只用桌面端也够：

  • 手动管理和编辑文档
  • 手动复制引用到 Cursor/Agent

需要 CLI 的场景：

  • 希望在 Cursor 里让 Agent 主动检索/读取上下文（工具调用）
  • 希望在对话中用命令把结论写回知识库（如 /opencontext-iterate）
  • 需要通过 MCP 把 OpenContext 接入 Cursor/其他 Agent 平台

→ 继续看下面的 Path B，完成 CLI + Cursor 配置

B

CLI + Cursor / Agent

开发者推荐

把 OpenContext 作为 MCP 工具接入 Cursor。之后你可以用斜杠命令让 Agent 安全地读上下文、搜索、创建文档，并把结论沉淀回知识库。

前置条件

  • 已安装 Node.js（npm / npx 可用）
  • Cursor（或其他支持 MCP 的 Agent 平台）

步骤 1：安装 CLI

$ npm install -g @aicontextlab/cli
# 或使用 npx：npx @aicontextlab/cli <command>

步骤 2：在仓库中初始化

在你要启用 Cursor 集成的仓库里运行：

$ oc init
oc init 做了什么：
  • 准备全局知识库（首次使用时）
  • 写入 Cursor 配置（AGENTS.md、.cursor/mcp.json、.cursor/commands/）
  • 可重复执行（不会重复生成冲突配置）

默认路径

  • Contexts: ~/.opencontext/contexts
  • Database: ~/.opencontext/opencontext.db

通过环境变量覆盖：

export OPENCONTEXT_CONTEXTS_ROOT="/path/to/contexts"
export OPENCONTEXT_DB_PATH="/path/to/opencontext.db"

步骤 3：使用新手命令

建议从上往下用：越靠前越稳妥，也更不容易误触发成本。

/opencontext-help 不确定从哪开始？先用这个
/opencontext-context （安全模式：只读，不构建索引） 为当前任务加载必要上下文
/opencontext-search 搜索/查看文档清单（manifest）
/opencontext-create 新建文档或草稿
/opencontext-iterate 把本次结论写回知识库（附引用）

注意：这些命令操作的是你的全局知识库（~/.opencontext/contexts），不是当前仓库里的文件。

C

仅 CLI（不接 Cursor）

不接 Cursor 也能用：用命令行管理文档/目录、检索内容，适合脚本化场景。

# 最小示例
oc folder ls --all
oc folder create project-a -d "My project"
oc doc create project-a design.md -d "Design doc"
# 搜索与清单
oc search "your query" --mode keyword --format json
oc context manifest project-a --limit 10

搜索与 Embedding 配置

桌面版：自动构建索引

桌面端会在后台自动构建并更新索引；不需要手动运行 oc index build。只要在设置里配置 Embedding 即可。

搜索模式

--mode keyword

关键词检索（无需 embeddings）

--mode vector

向量检索（需要 embeddings + 索引）

--mode hybrid

混合检索（默认，需要 embeddings + 索引）

关于 CLI 构建索引的费用

CLI 的语义检索需要 oc index build，可能调用付费 API。默认不建议让 Agent 自动执行。

CLI 用户：要启用混合/向量检索，请先配置 Embedding：

# 1. Set sensitive API Key
oc config set EMBEDDING_API_KEY "<your_key>"
# 2. (Optional) Set base URL
oc config set EMBEDDING_API_BASE "https://api.openai.com/v1"
# 3. (Optional) Set Model
oc config set EMBEDDING_MODEL "text-embedding-3-small"
# 4. Build Index
oc index build

推荐日常工作流

开工前（1 分钟）
/opencontext-context

先让 Agent 加载项目背景与已知坑

工作中
/opencontext-search

不确定时先搜索已有文档/结论

收工后（2 分钟）
/opencontext-iterate

把本次决策、坑点与下一步写回知识库

建议： 优先沉淀：验收标准、常见坑、接口约定、依赖版本。

MCP 服务

OpenContext 以标准 MCP 服务（stdio）运行。

  • 手动启动: oc mcp
  • Cursor: oc init 会自动写入 Cursor 配置

Web UI（实验性）

无需桌面端，在浏览器中浏览和编辑上下文。

$ oc ui

默认地址： http://127.0.0.1:4321

常见问题

为什么 A 项目的文档在 B 项目也能看到？

这是设计如此：知识库存储在全局共享目录（~/.opencontext/contexts），用于跨仓库复用。

如何修改默认存储路径？

在运行 oc 命令前设置环境变量：

export OPENCONTEXT_CONTEXTS_ROOT="/path/to/contexts"
export OPENCONTEXT_DB_PATH="/path/to/opencontext.db"

为什么语义搜索不可用？

通常是：还没构建索引，或没有配置 Embedding。先用关键词检索/清单；需要语义检索再配置并手动运行 oc index build。