AVIDS2/memorix · 上手攻略

  • 仓库：AVIDS2/memorix
  • 链接：https://github.com/AVIDS2/memorix
  • 分类：skill（MCP 记忆层 · 跨 Agent 持久化）
  • 作者：Tom
  • 更新：2026-08-27

是什么

Memorix 是一个本地优先的跨 Agent 共享记忆层，通过 MCP（Model Context Protocol）为 AI 编码工具提供持久化、可搜索的项目上下文。无论你今天用 Claude Code、明天换 Cursor、后天下午换成 Windsurf，项目记忆始终存在，不会因为换工具或开新 Session 而丢失。

GitHub Stars：660（数据截至 2026-08，工作队列标记）。已入驻 官方 MCP Registry。

解决什么问题

AI 编码助手最大的体验断裂点是：每次新 Session 都是一张白纸。上一个 Session 探索出的数据库迁移方案、踩过的坑、决定的技术选型——新 Session 全忘了。切换 IDE 也会导致同样的问题：Cursor 里学会的东西，Claude Code 里没有。

Memorix 的解法是：

问题 Memorix 提供的答案
新 Session 失忆 项目级记忆 + Session 摘要 + 时间线
不同 Agent 知识不互通 单一本地记忆池，通过 MCP/CLI/SDK 统一访问
Git 记录了改动但 Agent 读不懂 Git Memory：将 commit 转化为可搜索的工程事实
架构决策消失在旧聊天记录里 Reasoning Memory：存储决策背景 + 备选方案 + 权衡
静态规则文件与实际脱节 从真实工作流中提炼 Gotchas / Fixes / Skills
并行 Agent 协作混乱 memorix orchestrate 协调任务上下文、交接、锁、验证

本地优先：数据存在项目 .git 同级的 ~/.memorix/（SQLite），不上云。没有 API Key 也能用全文检索；有 Key 时可开启 LLM-backed embedding 和语义检索。

快速安装

全局安装（推荐）

npm install -g memorix

安装后验证：

memorix --version
# 或
memcode --version

初始化项目

cd /your/project/path
memorix init

这会在项目根目录创建 .memorix/ 子目录（SQLite 数据库），并提示你配置 MCP。

Agent 快速接入

memorix setup --agent <agent-name>

支持的 --agent 值（大小写敏感）：

claude-code    # Anthropic Claude Code
codex          # OpenAI Codex CLI
cursor         # Cursor
windsurf       # Windsurf
copilot        # GitHub Copilot CLI
gemini-cli     # Google Gemini CLI
opencode       # OpenCode
openclaw       # OpenClaw
hermes-agent   # Hermes Agent
oh-my-pi       # Oh-my-Pi
pi             # Pi coding agent
kiro           # Kiro
antigravity    # Antigravity
trae           # Trae
deepseek-harness  # DeepSeek Harness

注意：memorix setup 会自动写入 MCP 配置文件（stdio transport），不同 Agent 配置路径不同，请参考 GitHub README 中的详细说明。

MCP 客户端配置（手动）

{
  "mcpServers": {
    "memorix": {
      "command": "memorix",
      "args": ["serve"]
    }
  }
}

核心用法

1. 记忆 Autopilot（任务接续）

# 获取当前任务上下文（给新 Session 用）
memorix context "修复登录 Bug" --brief-json

# 从上次中断处恢复
memorix resume "session-id" --brief-json

# 项目上下文变量（可注入 Agent）
memorix_project_context

输出的 JSON 包含：起始文件、当前记忆、源码支撑知识、工作流启动步骤、注意事项和验证步骤。

2. Observation Memory（日常记忆）

# 记录一条记忆
memorix memory add "使用了 UUID v7 代替自增 ID，避免序列预测攻击"

# 搜索记忆
memorix memory search "UUID"

# 列出所有记忆
memorix memory

# 查看长期记忆（需人工审核后才入库）
memorix memory long-term

3. Git Memory（从 Git 提取工程事实）

# 将某次提交转化为可搜索事实
memorix ingest commit <commit-hash>

# 配置 git hook，自动摄入每次新提交
memorix ingest hook

4. Reasoning Memory（记录设计决策）

# 记录一个决策
memorix reasoning "选择 Turso 而非 PlanetScale"
# 进入交互式输入：背景、备选方案、权衡点

# 查询决策
memorix reasoning search "Turso"

5. Code State / CodeGraph（代码状态追踪）

# 查看代码图谱状态
memorix codegraph status

# 初始化代码图谱（Lite 索引，无需 Key）
memorix codegraph init

# 同步最新代码状态
memorix codegraph sync

6. 知识库（Knowledge Workspace）

# 查看工作流
memorix knowledge workflow

# 新建知识条目（需审核后才入库，防止 AI 静默覆盖）
memorix knowledge add "部署流程"

7. Orchestration（多 Agent 协调）

# 发起任务编排
memorix orchestrate "重构用户模块"

# 创建团队 + 交接任务
memorix team create api-task
memorix lock acquire api-task

# 验证完成后解锁
memorix lock release api-task

8. memcode（内置终端 Agent）

memcode 是 Memorix 自带的终端编码 Agent，已接入同一项目记忆，直接可用：

memcode
# 进入交互式对话，它已知道你的项目上下文

9. Dashboard（Web UI）

memorix dashboard
# 启动本地 HTTP 服务，可浏览记忆、项目状态、团队协作情况
memorix background start

10. 诊断与修复

# 检查 Agent MCP 配置是否正确
memorix doctor agents

# 修复配置
memorix repair agents

卸载

memorix uninstall --yes --background --hooks --purge-data
npm uninstall -g memorix

注意：memorix uninstall 会报告 MCP 配置项，供你手动清理。

典型适用场景

  • 多 Agent 切换者：一天内轮用 Claude Code / Cursor / Windsurf，不想每次重头解释项目上下文
  • 长周期项目维护：6 个月前的架构决策、踩过的坑，新人接手时直接查询
  • 多 Agent 协作：A Agent 完成 API 部分后交接给 B Agent，memorix orchestrate 协调上下文传递
  • Agent 能力边界探索：同一个项目在不同 Agent 里知识不一致，Memorix 作为单一真相来源
  • 项目知识沉淀：不想知识留在个人聊天记录里，而是变成可搜索、可引用的工程事实

坑与注意

  1. 需要先 Git init：memorix init 需要项目目录下有 Git 仓库，因为它依赖 Git 信息做 Git Memory 和项目上下文判断。
  2. SQLite 数据量增长：长期项目会产生大量记忆数据，memorix 支持 memorix memory prune 清理，请定期维护。
  3. MCP 配置手动清理：卸载时 memorix uninstall 只报告需要清理的文件路径，不会自动删除所有 Agent 的 MCP 配置。
  4. Embedding 需要 API Key：纯本地使用时是全文检索（Orama），无 Key 够用；开启语义检索需要配置 LLM API Key。
  5. Agent 支持范围：非 MCP 原生的 Agent（如某些闭源 IDE 插件）可能无法完美接入，列表中未列出的 Agent 不保证支持。
  6. 并发写入：多 Agent 同时向同一个 Memorix 实例写入时，SQLite 有写锁，建议通过 memorix lock 协调。

与同类对比

工具 定位 存储 MCP 多 Agent 特色
Memorix 跨 Agent 项目记忆层 SQLite + Orama ✅ ✅ 原生 Git Memory / Reasoning Memory / Orchestration
** CLAUDE.md / AGENTS.md** 单 Agent 项目规则 纯文本 ❌ ❌ 简单直接，但不持久化、不搜索
MCP Memory Server（官方） MCP 官方的记忆协议 可插拔 ✅ ⚪ 偏协议层，无 Git/Reonextra 记忆能力
Zed Agent Context Zed 内置 闭源 ❌ ❌ 仅限 Zed IDE 内
Continue（Datalore） VS Code/JetBrains 插件 本地 ✅ ⚪ 更偏 IDE 集成，记忆能力弱于 Memorix

Memorix 的核心差异化是本地 SQLite + Git 感知 + 多层记忆类型 + 原生多 Agent 协调，是一套完整的记忆操作系统而非简单提示词仓库。

一句话推荐结论

如果你每天和多个 AI 编码工具打交道，或者项目周期长到上一个 Session 的知识早就不记得了，Memorix 是目前最完整的开源解法——npm install -g memorix 后跑 memorix setup --agent 就能用，门槛极低。

参考来源

  • GitHub README：https://github.com/AVIDS2/memorix
  • 中文 README：https://github.com/AVIDS2/memorix/blob/main/README.zh-CN.md
  • MCP Registry 页面：https://registry.modelcontextprotocol.io/?q=io.github.AVIDS2%2Fmemorix
  • MCP Toplist：https://mcpmarket.com/server/memorix
  • DEV Community 介绍：https://dev.to/_2340687267e5cacfe32da1/memorix-give-your-ai-coding-agents-shared-persistent-project-memory-1pk2
  • npm：https://www.npmjs.com/package/memorix

不确定处：npm 当前最新版本号建议自行运行 npm view memorix version 确认（npmjs.com 有 Cloudflare 保护未能直接获取）；Agent 支持列表以 GitHub README 为准，本文可能未覆盖最新新增 Agent。