dark-memory-mcp

╔════════════════════════════════════════════════════════════════════════════════════╗
║                                                                                    ║
║         ██████╗  ██████╗██████╗ ███╗   ███╗      ███╗   ███╗ ██████╗██████╗        ║
║        ██╔═══██╗██╔════╝██╔══██╗████╗ ████║      ████╗ ████║██╔════╝██╔══██╗       ║
║        ██║   ██║██║     ██║  ██║██╔████╔██║      ██╔████╔██║██║     ██████╔╝       ║
║        ██║   ██║██║     ██║  ██║██║╚██╔╝██║      ██║╚██╔╝██║██║     ██╔═══╝        ║
║        ▚██████╔╝╚██████╗██████╔╝██║ ╚═╝ ██║      ██║ ╚═╝ ██║╚██████╗██║            ║
║         ╚═════╝  ╚═════╝╚═════╝ ╚═╝     ╚═╝      ╚═╝     ╚═╝ ╚═════╝╚═╝            ║
║                                                                                    ║
║                     MEMORIA PERSISTENTE PARA AGENTES DE IA                         ║
║                                                                                    ║
╚════════════════════════════════════════════════════════════════════════════════════╝

它解决的问题

Lunes:   "Vamos a refactorizar el módulo de autenticación."
         El agente trabaja. Tomas 5 decisiones de arquitectura.
         Cierras la sesión.

Martes:  "Continuemos con el refactor."
         El agente: "¿Qué refactor? ¿Qué módulo? ¿Quién eres?"
         Tienes que explicarle TODO otra vez. 20 minutos perdidos.

使用 Dark Memory：

Lunes:   "Vamos a refactorizar el módulo de autenticación."
         El agente anota: proyecto, decisión #1, decisión #2...
         Todo queda en tu disco.

Martes:  Abres sesión. El agente recibe:
           - Proyecto: dark-memory-mcp
           - Decisiones del lunes: 5 (la #3: "RS256, no HS256")
           - Pendientes: 2
         "OK, ayer elegimos RS256, terminemos los tests."
         0 minutos de re-explicación.

你不需要直接与 Dark Memory 交互。你的 Agent（Claude、opencode、Cursor） 会通过 MCP 使用它，就像查阅笔记本一样。

Vibe 循环

打通你的要求与交付结果之间的闭环。

Sin supervisión:
  Tú:    "Crea una API que devuelva productos filtrados por categoría."
  Agente: [200 líneas]
  Tú:    "También devuelve los borrados..."
  Agente: "Cierto." [150 líneas más]
  Tú:    "No tiene paginación."
  Agente: "..."  ← iteración sin fin

Con vibe-loop:
  1. CREAS LA PROMESA (spec)      → dark_memory_vibe_spec
  2. EL AGENTE TRABAJA
  3. ENTREGA EL ARTEFACTO         → dark_memory_vibe_publish
  4. EL JUEZ COMPARA entrega vs promesa:
        "aligned"        → cumple, adelante        ✅
        "drift_detected" → se desvió, reintenta    🔄
        "needs_human"    → no está seguro, te pregunta 🤔
  5. CIERRE — queda registrado qué pediste, qué entregaron, qué dijo el juez

你不必逐行检查。由裁判根据最初的承诺评估每次交付，Agent 会自行修正。

快速开始

你需要 Node.js 18+（npm 包装器）或 Go 1.25+（从 source 构建）。

// Agrega esto a la config MCP de tu agente
{
  "mcpServers": {
    "dark-memory": {
      "command": "npx",
      "args": ["-y", "@opitacode/dark-memory-mcp"]
    }
  }
}

npx 首次运行时会下载适用于你系统的二进制文件。无需编译。

验证是否正常运行

> "Llama a dark_memory_health_ping y dime qué responde."

{
  "server": { "version": "4.0.0-alpha.32", "name": "dark-memory-mcp" },
  "db": { "live": true, "schema_version": 32 },
  "registry": { "canonical_tools": 78 }
}

78 是实时测得的注册数量。server.version 是构建标记 （已发布的 tag 或本地伪版本）；重要的是上面的格式：运行状态 + schema + 数量。

server.version 会显示构建标记：如果编译时未使用 -ldflags，你会看到 dev 而不是版本号。这不是错误。

入门

1. "Inicia sesión en dark-memory. Operador: [tu nombre]. Proyecto: mi-proyecto."
2. "Guarda: 'Estamos usando Postgres 16 con uuidv7 como PKs.'"
3. "¿Qué tenemos anotado sobre la base de datos?"
4. "Cierra la sesión."

从 source 构建：go build -o bin/dark-mem-mcp ./cmd/dark-mem-mcp 各主机的详细说明：docs/npm-install.md。

选择你的级别

级别 1 — 笔记本。 Agent 能在不同会话之间记住信息。适合第一天使用。 session_start、agent_memory_save、agent_memory_recall、session_close。

级别 2 — Vibe 循环。 验证交付结果是否符合要求。 用 vibe_spec 作出承诺，用 vibe_publish 交付，用 pipeline_status 获取 判定结果，用 resolve_drift 接受或拒绝。

级别 3 — 委派。 适用于大型任务：delegate_intent 决定直接执行还是交由 子 Agent 执行，mindset_apply 则组合它们的提示词。

级别 4 — 扩展。 添加工具、调整评分标准、改进搜索。 从 CONTRIBUTING.md → 适合新手的议题 开始。

你会在代码中看到的概念

完整目录：docs/tools.md。

如果出现问题

目前还做不到的事

坦诚相告，因为只会推销的 README 无助于做出判断：

• 预发布版。 注册表中测得 78 个规范工具 （+3 个通过环境变量组装的额外工具 = 81 个）。工具范围会随着 release 增长，并由 freeze test 固定——相较于 alpha.31，变化量为 +5 （vibe_compile + 包含 4 项的 OAUTH 命名空间）。各命名空间的详情见 docs/v4-status.md §1。
• Phase 21 只覆盖 9 个原语中的 2 个。 Vibe-loop 引擎是一个已经验证、 正在开始接线的库，而非完成的产品。剩余 7 个原语会改变行为，需要 instrument → measure → decide → flip。
• Postgres 尚未在实际环境中测试。 58 个方法返回 notImpl（SQLite 中为 0 个）。 生产路径使用 SQLite。
• 目前还没有外部使用者。 作者自 2026-10-08 起每天都在使用。

所有这些数据都附有测量时间和来源，详见 docs/v4-status.md。 如果该文档与正在运行的代码不一致，internal/tools/v4_status_consistency_test.go 会导致构建失败，因此内容不会悄无声息地过时。

内部工作原理

Tu agente (Claude / opencode / Cursor)
    │  MCP (JSON-RPC sobre stdin/stdout)
    ▼
dark-mem-mcp.exe  ←── proceso local, 78+3 herramientas
    │  SQL
    ▼
SQLite (archivo .db en tu disco)   ←── o Postgres con DARK_DRIVER=postgres

• 数据库 Schema： 32，存储在 schema_migrations.version 中。运行实例中有 66 张表， 包括 FTS5 的影子表。
• 外部依赖： 运行时无外部依赖。Go 标准库 + 嵌入式 SQLite。
• 测试： 权威数字以 CI 中的为准，而非本 README 中的数字。把数字复制到 README 中， 正是这个项目不再做的事。

贡献

MIT。欢迎各种水平的贡献。

1. CONTRIBUTING.md — 项目规范
2. §10 保持已发布声明的准确性 — 项目曾付出惨痛代价才学到的规则
3. 所有贡献都必须经过 vibe-loop：spec → artifact → drift_judge → merge

设计原则：

• 仅追加：迁移永不编辑，只能新增
• 规范顺序：工具顺序固定，不重新编号
• 尽力而为：VLP、清理器和遥测永不阻塞主要操作
• 不硬编码：每个数字、名称和版本都只有一个事实来源