Omni Memory MCP

全内存MCP

用于多代理工作流的通用内存MCP服务器。\ 100%本地使用SQLite+FTS5。

npm包

• 包裹： @sharkdyt/omni-memory-mcp
• npm： https://www.npmjs.com/package/@sharkdyt/omni-memory-mcp
• 当前 latest: 1.0.7

发布说明

v1.0.7

• 船舶 memory_context_pack 用于只读、令牌预算的提示程序集。
• 返回紧凑的摘录和结构化元数据，而不会发生变异 access_count.
• 保持当前的本地SQLite+FTS5架构：没有模式迁移、向量检索或排名重写。

项目记忆

此项目不保持本地 memory-bank/ 文件夹。 操作上下文通过Omni Memory本身存储。

为什么存在

• 将AI内存保持在本地（不依赖于云）
• 跨工具/代理重用相同的内存
• 使用SQLite FTS5快速搜索

特性

• 本地第一存储（SQLite）
• 使用FTS5进行全文搜索
• MCP原生工具
• 渐进式披露： 搜索返回元数据和摘要，而不是全文，以防止LLM上下文溢出。
• 上下文包： memory_context_pack 组装紧凑的、象征性的预算摘录，以便迅速施工。
• 主动遗忘追踪： 读取操作(memory_get)增量 access_count 并更新 accessed_at.
• CRUD操作(memory_add, memory_upsert, memory_get, memory_update, memory_delete, memory_list, memory_search)
• 上下文优化工具(memory_prune)
• 诊断工具(memory_stats)
• 组织方式 area, project，以及 tags
• 跨多个项目和多个编码代理/客户端共享长期内存
• 标准MCP配置+客户端适配器（OpenCode、Codex、Cursor）

跨客户端MCP标准

此项目保留一个规范的MCP配置，并生成特定于客户端的文件。

标准来源：

• config/mcp/servers.json

生成适配器：

npm run mcp:generate

验证适配器：

npm run mcp:validate

生成的文件：

• config/mcp/generated/opencode.windows.json
• config/mcp/generated/opencode.posix.json
• config/mcp/generated/opencode.windows.array.npx.json
• config/mcp/generated/opencode.windows.string-args.npx.json
• config/mcp/generated/opencode.windows.array.fallback-dist.json
• config/mcp/generated/opencode.posix.array.npx.json
• config/mcp/generated/opencode.posix.string-args.npx.json
• config/mcp/generated/opencode.posix.array.fallback-dist.json
• config/mcp/generated/codex.windows.json
• config/mcp/generated/codex.posix.json
• config/mcp/generated/cursor.windows.json
• config/mcp/generated/cursor.posix.json

兼容性矩阵：

• docs/mcp-compatibility-matrix.md

快速入门（最适合新手）

如果您的MCP客户端支持 command + args + env，使用：

{
  "mcpServers": {
    "omni-memory": {
      "command": "npx",
      "args": ["-y", "@sharkdyt/omni-memory-mcp"],
      "env": {
        "OMNI_MEMORY_DIR": "~/.omni-memory"
      }
    }
  }
}

这是最简单的设置，因为：

• 无手动克隆路径
• 无手动构建路径
• npm注册表发布后工作

OpenCode兼容性配置文件

OpenCode支持可能因客户端版本和环境而异。\ 此存储库现在为每个平台生成三个OpenCode配置文件：

• array.npx: command 作为数组(["npx","-y","@sharkdyt/omni-memory-mcp"])
• string-args.npx: command 作为字符串+ args
• array.fallback-dist：尝试执行的shell命令 npx 并回落到本地 dist/index.js

OpenCode的推荐默认值：

• `config/mcp/generated/opencode.

.json （这指向 array.fallback-dist`)

如果您更喜欢显式配置文件选择，请复制以下选项之一：

• `config/mcp/generated/opencode.

.array.npx.json`

• `config/mcp/generated/opencode.

.string-args.npx.json`

• `config/mcp/generated/opencode.

.array.fallback-dist.json`

路径引导（相对与绝对）

如果您更喜欢从本地源运行(dist/index.js)，使用 绝对路径.

• 相对路径示例（可能中断）： ./dist/index.js
• 绝对路径示例（推荐）：磁盘上文件的完整路径

为什么相对路径会中断：

• 许多MCP客户端从自己的进程工作目录解析路径，而不是从配置文件目录解析路径。

绝对路径示例

Linux：

{
  "command": "node",
  "args": ["/home/your-user/.local/mcp/omni-memory-mcp/dist/index.js"]
}

macOS：

{
  "command": "node",
  "args": ["/Users/your-user/.local/mcp/omni-memory-mcp/dist/index.js"]
}

窗户：

{
  "command": "node",
  "args": ["C:\\Users\\your-user\\.local\\mcp\\omni-memory-mcp\\dist\\index.js"]
}

注：

• ~ 很方便，但并非每个客户端都能在Windows上一致地扩展它。绝对路径更安全。

从源代码安装（本地开发人员）

git clone https://github.com/allanschramm/omni-memory-mcp.git
cd omni-memory-mcp
npm install
npm run build

然后配置MCP客户端 node +绝对路径 dist/index.js.

OpenCode/Codex/游标

与其手工编写每个配置，不如生成特定于客户端的适配器：

npm run mcp:generate

然后从以下位置复制为您的客户端/平台生成的文件 config/mcp/generated/.

OpenCode故障排除优先级

1. 使用 `opencode.

.json` 第一个（默认回退配置文件）。

1. 如果你的OpenCode构建更喜欢原生 npx 只是，试试 `opencode.

.array.npx.json`.

1. 如果您的OpenCode构建需要 command 字符串+ args，使用 `opencode.

.string-args.npx.json`.

工具

memory_add

{
  "name": "User typescript preferences",
  "content": "User prefers TypeScript with strict mode",
  "area": "preferences",
  "project": "my-project",
  "tags": ["typescript", "coding-style"],
  "metadata": {
    "source": "conversation setup"
  }
}

使用 memory_add 寻找全新的、一次性的记忆。

memory_upsert

{
  "name": "User typescript preferences",
  "content": "User prefers TypeScript with strict mode",
  "project": "my-project",
  "tags": ["typescript", "coding-style"],
  "allow_create": true
}

*注： memory_upsert 故意保守。它使用归一化 name + project 匹配，仅在有一个明确的候选者时更新，在匹配不明确时拒绝写入。* *使用 memory_upsert 之前 memory_add 为了获得持久的事实、偏好和不断发展的项目记忆。*

memory_get

*注意：通过以下方式获取内存 memory_get 注册访问（增量 access_count 和更新 accessed_at)，表示内存正在被积极使用。*

{
  "id": "abc123"
}

memory_update

{
  "id": "abc123",
  "name": "Updated typescript preferences",
  "content": "Updated content",
  "project": null,
  "metadata": null,
  "tags": ["new-tag"]
}

*使用 null 为了 project 或 metadata 为了明确这些价值观。*

memory_delete

{
  "id": "abc123"
}

memory_list

*注：强制渐进式披露。它只返回ID、名称和元数据。你必须打电话 memory_get 使用特定ID读取完整内容。*

{
  "area": "snippets",
  "project": "my-project",
  "tag": "important",
  "limit": 20
}

memory_search

*注：强制渐进式披露。它只返回ID、名称和元数据。你必须打电话 memory_get 使用特定ID读取完整内容。*

{
  "query": "typescript configuration",
  "project": "my-project",
  "limit": 10,
  "enableAdvancedSyntax": false,
  "search_mode": "balanced"
}

*注： enableAdvancedSyntax 允许FTS5布尔逻辑（例如。 "typescript" AND "react" NOT "vue")但需要严格有效的FTS5查询，否则将抛出错误。* *注： search_mode 仅限曲目排名。 balanced 是默认值， exact 更难进行精确的冠军赛，以及 broad 对内容较多的结果更为宽容。* *搜索结果包括一个压缩 Match: 说明哪些索引字段对结果有贡献。*

memory_context_pack

*注意：从匹配的内存构建一个紧凑的提示就绪包，无需递增 access_count。它通过返回简短的摘录而不是完整的文件来保持渐进式披露的完整性。*

{
  "query": "typescript configuration",
  "project": "my-project",
  "tag": "important",
  "max_tokens": 1200,
  "max_memories": 5,
  "search_mode": "balanced"
}

退货：

• 简洁的文本，供即时代理使用
• 结构化元数据 count, estimated_tokens, truncated，以及根据内存摘录
• 摘录由现有 memory_search 排名

memory_stats

{}

*返回总内存、磁盘大小、按项目和区域细分，以及本地追加销售指标，如 memory_upsert_created 和 memory_upsert_updated.*

memory_prune

*注意：清除衰减到特定分数以下的记忆，该分数基于以下因素动态计算 created_at, accessed_at，以及 access_count.*

{
  "threshold_score": 0,
  "dry_run": true
}

*始终使用 dry_run: true 首先看看在运行可销毁清理之前，会修剪多少和哪些记忆。*

内存区域

数据存储

默认目录：

~/.omni-memory/
|- omni-memory.db
|- omni-memory.db-wal
`- omni-memory.db-shm

环境变量：

发展

npm install
npm run check
npm run build
npm test

额外命令：

npm run dev    # watch mode
npm run start  # run server from dist/

文档和内存卫生

对于每一个有意义的项目变更，都要更新两个信息来源：

1. 存储库文档(README.md, docs/*，兼容性/config文档）必须反映当前行为。
2. Omni Memory必须收到一个简洁的项目内存条目，其中包含：

- 发生了什么变化， - 为什么它改变了， - 约束/假设， - 接下来的步骤（如果有的话）。

最小发布/更新时间：

1. npm run mcp:generate
2. npm run mcp:validate
3. npm run check
4. 更新任何行为/配置更改的文档
5. 在Omni memory中添加/更新重要项目内存

此存储库的更改后运行时验证：

1. npm run build
2. 同步仓库 dist/ 进入 C:\Users\allan\.local\mcp\omni-memory-mcp\dist
3. 烟雾测试部署 omni-memory-mcp

操作检查表：

• docs/release-checklist.md

许可证

Apache 2.0。看 LICENSE.