Mind Keg MCP

Mind Keg MCP

用于AI编码代理的持久内存MCP服务器。存储原子学习——调试见解、架构决策、代码库约定——因此每个代理会话都从相关的机构知识开始。

问题

AI编码代理（Claude Code、Cursor、Windsurf）在会话之间失去上下文。谈话一结束，来之不易的见解就被遗忘了。开发人员反复解释同样的事情；特工们一再犯同样的错误。

Mind Keg 通过任何MCP兼容代理都可以查询和贡献的集中、持久的大脑来解决这个问题。

运作原理

Mind Keg实现了 RAG（检索增强生成） AI编码代理的模式：

1. 检索 --Agent使用语义或关键字搜索在大脑中搜索相关学习
2. 增强 --检索到的学习内容被注入到代理的对话环境中
3. 生成 --代理人会意识到过去的发现和决定

与传统的将大型文档分块的RAG系统不同，Mind Keg存储 预先策划的原子学习 （每个最多500个字符）。不需要分块策略——每个学习都是检索单元。代理控制检索和存储，创建一个反馈循环，知识随着时间的推移而改进。

特性

• 存储和检索原子学习（最多500个字符，每个条目一个见解）
• 具有三个提供者选项的语义搜索：

- 快速嵌入 （免费、本地、基于ONNX-- BAAI/bge-small-en-v1.5，384调暗） - 开放人工智能 （付费，质量最好-- text-embedding-3-small，1536变暗） - 无 （FTS5关键字回退——零外部依赖）

• 六类： architecture, conventions, debugging, gotchas, dependencies, decisions
• 自由形式标签和组链接
• 三个范围界定级别：特定于存储库、工作区范围和全局学习
• 双传输：stdio（本地）+HTTP+SSE（远程）
• 授权免费stdio供本地使用；API密钥身份验证与HTTP的假定访问控制
• SQLite存储（零依赖，零配置）
• 导入/导出以进行备份和迁移
• 更智能的知识管理：自动分类（KNN投票）、冲突检测、智能陈旧性评分、具有相关性衰减的访问跟踪、近似重复合并、类型化学习关系
• 企业安全：静态加密、审计日志、TTL/数据保留、Prometheus监控、速率限制、内容完整性验证

快速开始

npx mindkeg-mcp init

就是这样。这将为您的AI代理（Claude Code、Cursor、Windsurf）在全球范围内安装Mind Keg。打开任何项目，您的代理都有持久内存——没有API密钥，没有每个项目的设置。

对于Claude Code，还安装了SessionStart挂钩——您的代理在每个会话开始时自动加载先验知识。

选项：

npx mindkeg-mcp init --agent cursor    # Target a specific agent
npx mindkeg-mcp init --project         # Per-project setup instead of global

init 是幂等的——可以安全地运行多次。它与现有的配置合并，从不覆盖。

手动设置

如果您更喜欢手动配置，或需要HTTP模式：

Click to expand manual setup instructions

安装

npm install -g mindkeg-mcp

创建API密钥（仅用于HTTP模式）

mindkeg api-key create --name "My Laptop"
# Displays the key ONCE — save it securely
# mk_abc123...

API密钥仅用于HTTP传输。stdio传输（由Claude Code、Cursor、Windsurf本地设置使用）是无身份验证的。

连接您的AI代理

Mind Keg可与任何兼容MCP的AI编码代理配合使用。选择您的设置：

克劳德代码 --添加到 ~/.claude.json 或者你的项目 .claude/mcp.json:

{
  "mcpServers": {
    "mindkeg": {
      "command": "mindkeg",
      "args": ["serve", "--stdio"]
    }
  }
}

光标 --添加到 .cursor/mcp.json 或全局设置：

{
  "mcpServers": {
    "mindkeg": {
      "command": "mindkeg",
      "args": ["serve", "--stdio"]
    }
  }
}

帆板运动 --添加到 ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "mindkeg": {
      "command": "mindkeg",
      "args": ["serve", "--stdio"]
    }
  }
}

HTTP模式（任何MCP客户端）：

MINDKEG_API_KEY=mk_your_key mindkeg serve --http
# Listening on http://127.0.0.1:52100/mcp

{
  "mcpServers": {
    "mindkeg": {
      "type": "http",
      "url": "http://127.0.0.1:52100/mcp",
      "headers": {
        "Authorization": "Bearer mk_your_key_here"
      }
    }
  }
}

其他MCP兼容代理 --Mind Keg与任何支持 模型上下文协议 --包括Codex CLI、Gemini CLI、GitHub Copilot等。使用上面适合代理MCP设置格式的stdio配置。

将Mind Keg说明添加到您的存储库中

复制 templates/AGENTS.md 到您希望代理使用Mind Keg的任何存储库的根目录。

AGENTS.md 是由20多种AI工具（Cursor、Windsurf、Codex、Gemini CLI、GitHub Copilot等）支持的行业标准。

仅限克劳德代码：Claude代码未自动加载 AGENTS.md 本地。添加 @AGENTS.md 到你的 CLAUDE.md 来桥接它。

MCP工具

8种合并工具（主要API）：

向后兼容的别名： 所有19个旧工具名称(store_learning, search_learnings, update_learning, deprecate_learning, flag_stale, delete_learning, merge_learnings, store_decision, get_decisions, supersede_decision, store_finding, resolve_finding, get_open_findings, store_gotcha, get_gotchas, get_run_history, get_relevant_context, list_repositories, list_workspaces)被注册为委托给相同服务方法的别名。它们将在下一个主要版本中删除。

CLI命令

# Global setup (one-time) — writes MCP config, SessionStart hook, runs migrations
mindkeg init
mindkeg init --agent cursor    # Target a specific agent (default: claude-code)
mindkeg init --project         # Per-project setup instead of global (optional)

# Database statistics
mindkeg stats
mindkeg stats --json

# Start in stdio mode (for local agent connections)
mindkeg serve --stdio

# Start in HTTP mode (for remote connections)
mindkeg serve --http

# API key management
mindkeg api-key create --name "My Key"
mindkeg api-key create --name "Team Key" --repositories /repo/a /repo/b
mindkeg api-key list
mindkeg api-key revoke 

# Database
mindkeg migrate

# Near-duplicate detection (backfill existing learnings)
mindkeg dedup-scan
mindkeg dedup-scan --dry-run

# Backup and restore
mindkeg export --output backup.json
mindkeg import backup.json --regenerate-embeddings

# Data retention
mindkeg purge --older-than 90          # Purge learnings older than 90 days
mindkeg purge --repository /path/repo  # Purge all learnings for a repo
mindkeg purge --all --confirm          # Purge everything (requires --confirm)

# Encryption at rest
mindkeg encrypt-db   # Encrypt existing database (requires MINDKEG_ENCRYPTION_KEY)
mindkeg decrypt-db   # Decrypt existing database (requires MINDKEG_ENCRYPTION_KEY)

# Integrity backfill
mindkeg backfill-integrity  # Compute SHA-256 hashes for legacy learnings

配置

嵌入提供者

FastEmbed（默认、免费、本地）

语义搜索使用FastEmbed开箱即用-无需API密钥，无需网络调用。用途 BAAI/bge-small-en-v1.5 （384个维度）通过本地ONNX运行时。模型文件在首次使用时下载一次（约50MB）。

OpenAI（付费，最高质量）

export MINDKEG_EMBEDDING_PROVIDER=openai
export OPENAI_API_KEY=sk-...

用途 text-embedding-3-small （1536个维度）。最好的语义搜索质量，但需要一个API密钥，并导致每次请求成本。

无（仅关键字搜索）

export MINDKEG_EMBEDDING_PROVIDER=none

禁用语义搜索并回退到SQLite FTS5全文搜索——所有其他功能的工作方式相同。

企业安全

Mind Keg提供了一套适用于企业和受监管环境的安全功能。

静态加密

加密 content 和 embedding 使用AES-256-GCM的字段。所有其他字段（类别、标签、时间戳）仍为明文。

# Generate a 256-bit key
node -e "console.log(require('crypto').randomBytes(32).toString('base64'))"

export MINDKEG_ENCRYPTION_KEY=
mindkeg serve --stdio

要就地加密现有数据库，请执行以下操作：

MINDKEG_ENCRYPTION_KEY= mindkeg encrypt-db
# Creates a backup automatically before operating

备注：启用加密后，FTS5关键字搜索不起作用。使用FastEmbed或OpenAI嵌入提供程序进行搜索。

审计日志

所有MCP工具调用都写入结构化JSON行审计日志（SIEM兼容）。

export MINDKEG_AUDIT_LOG=~/.mindkeg/audit.jsonl  # default
# Or: MINDKEG_AUDIT_LOG=stderr  (write to stderr alongside app logs)
# Or: MINDKEG_AUDIT_LOG=none    (disable)

每个审计条目包含： timestamp （ISO 8601）， action, actor （API密钥前缀）， resource_id, result, client 传输元数据。敏感领域(content, embedding)从未被记录。

TTL和数据保留

设置全局默认TTL或每次学习TTL以自动过期旧条目。

export MINDKEG_DEFAULT_TTL_DAYS=365    # Expire all learnings after 1 year by default
export MINDKEG_PURGE_INTERVAL_HOURS=24 # Run purge every 24 hours (default)

每次学习TTL会覆盖全局默认值：

{ "content": "...", "ttl_days": 30 }

手动吹扫：

mindkeg purge --older-than 180 --confirm

监控

HTTP传输公开了与Prometheus兼容的端点：

GET /health   → JSON: { status, version, uptime, database }
GET /metrics  → Prometheus text format

默认情况下，这两个端点都未经过身份验证。集 MINDKEG_METRICS_AUTH=true 要求API密钥身份验证。

暴露的指标： mindkeg_learnings_total, mindkeg_tool_invocations_total, mindkeg_tool_duration_seconds, mindkeg_errors_total, mindkeg_uptime_seconds, mindkeg_search_latency_seconds.

速率限制

HTTP传输通过单独的写入和读取桶强制每个API密钥的令牌桶速率限制。

export MINDKEG_RATE_LIMIT_WRITE_RPM=100  # default: 100 write req/min per key
export MINDKEG_RATE_LIMIT_READ_RPM=300   # default: 300 read req/min per key

返回HTTP 429 Retry-After 超过标头时。stdio传输不受速率限制。

供应链安全

• 使用发布的npm包 --provenance （通过GitHub Actions进行Sigstore认证）
• CycloneDX SBOM在每个GitHub版本上生成并上传为发布资产
• npm tarball的Cosign签名作为发布资产上传

内容完整性

每次写时学习都会计算并存储SHA-256完整性哈希。按需验证：

{ "query": "...", "verify_integrity": true }

每个结果包括 integrity_valid: true | false | null (null 用于没有存储哈希的遗留学习）。

回填现有学习的完整性哈希值：

mindkeg backfill-integrity

数据模型

每项学习都包含：

界定范围

学习有三个范围级别：

自动检测工作区 从存储库路径的父文件夹中。例如，如果您的repos组织为：

repositories/
  personal/     ← workspace
    app-a/
    app-b/
  work/          ← workspace
    project-x/

存储在下的工作空间学习 repositories/personal/ 共享 app-a 和 app-b 但不是 project-x.

搜索时，结果包括所有三个范围：特定于仓库+工作区+全局。每个结果都有一个 scope 字段指示其级别。

什么是好的学习？

• 原子：每个条目一个见解。最多500个字符。
• 可操作：做什么或避免什么，而不仅仅是存在什么。
• 特定的：提到具体的上下文（库、模式、文件）。

好：“始终将Prisma查询包装在try/catch中——它会抛出违反约束的情况，而不会返回null。”

坏：“小心数据库。”（太模糊）

发展

# Clone and install
git clone ...
npm install

# Run tests
npm test

# Build
npm run build

# Development mode (rebuilds on change)
npm run dev

# Type check
npm run typecheck

在没有外部API的情况下运行

默认情况下，Mind Keg完全脱机工作。FastEmbed使用ONNX Runtime提供免费的本地语义搜索，无需API密钥或网络调用。所有CRUD操作和搜索都是开箱即用的。

建筑

CLI (Commander.js)
  └── init / stats / serve / api-key / migrate / export / import / dedup-scan
      purge / encrypt-db / decrypt-db / backfill-integrity

src/
  index.ts          Entry point, stdio + HTTP transports
  server.ts         MCP server + tool registration
  config.ts         Config loading (env vars → defaults)
  audit/            Structured JSON lines audit logger
  auth/             API key generation + validation middleware
  crypto/           AES-256-GCM field encryption
  hooks/            Hook script generation (SessionStart auto-retrieval)
  monitoring/       Prometheus metrics + /health endpoint
  security/         Content sanitization, integrity hashing, rate limiter
  tools/            MCP tool handlers (8 consolidated + 19 backwards-compatible aliases)
  services/         LearningService + EmbeddingService + PurgeService + ConflictDetector + StalenessEngine
  storage/          StorageAdapter interface + SQLite impl
  models/           Zod schemas + TypeScript types
  utils/            Logger (pino → stderr) + error classes

templates/
  AGENTS.md         Template for instructing agents to use Mind Keg

看 CLAUDE.md 了解详细的开发约定。

许可证

麻省理工学院