AI导哈

语义记忆存储服务

一个基于PostgreSQL和pgvector的持久化语义记忆存储服务，支持向量嵌入存储和多维度组织。

  • by markschaake
  • TypeScript
  • 本地部署
  • 更新于
在 GitHub 查看 markschaake/brain-mcp

使用说明

脑mcp

一个MCP（模型上下文协议）服务器，提供由PostgreSQL+pgvector支持的持久语义内存。使用向量嵌入存储“想法”，并通过灵活的维度模型对其进行组织。

两台服务器

此仓库提供了两个具有共享代码库的MCP服务器：

  • 脑mcp (dist/index.js)--支持ADR的通用知识库。将其用于非代码上下文。
  • 脑编码mcp (dist/code.js)——配备代码感知工具的大脑mcp超级集。将其用于软件项目。

你只需要配置一个——大脑代码mcp包括所有大脑mcp工具。

特性

  • 语义搜索 --利用向量嵌入上的余弦相似性从意义中寻找思想
  • 维度组织 --用键入的维度（人、项目、主题、标签、文件、符号等）标记想法
  • 思维时间性 --思想有类型(fact, decision, observation, question)在保留历史的同时可以被取代
  • 多脑支持 --通过 BRAIN_NAME 环境变量
  • 冲突检测 --在捕捉新想法时自动显示类似的现有想法
  • 架构决策记录 --具有自动编号、替代方案和后果的结构化ADR捕获
  • 代码链接知识 --将想法链接到存储库、文件和符号（大脑代码mcp）
  • 知识新鲜度 --当参考代码发生变化时检测过时的知识（大脑代码mcp）

工具

核心工具（两台服务器）

工具 说明
capture_thought 用类型、维度、元数据和嵌入来存储思想。表面与类似的积极想法相冲突。
search 带有可选过滤器（维度、思维类型等）的语义向量搜索
list_recent 按时间顺序列出，可选过滤器
explore_dimension 所有与特定维度相关的想法
list_dimensions 所有维度都很重要
list_brains 列出所有具有可选思维计数的大脑。尊重 BRAIN_ACCESSIBLE.
supersede_thought 替换现有的思想，保存历史。自动保留ADR元数据。
capture_adr 记录架构决策记录，包括上下文、备选方案和后果
list_adrs 按状态或维度列出和过滤ADR

代码工具（仅限大脑代码mcp）

工具 说明
capture_code_context 捕获与特定文件、符号或存储库链接的知识
search_code 语义搜索过滤到与代码相关的知识
check_freshness 通过比较git状态检查代码链接知识是否过时
refresh_stale_knowledge 使用git diffs查找过时的想法以供审查

核心提示（两台服务器）

提示 描述
brain_overview 综合定位：思想计数、维度、近期思想、ADR总结、开放式问题
deep_dive 深入探究一个包含所有相关思想、共同发生的维度和ADR的维度
decision_review 审查积极的决策和ADR，标记逾期的重新访问日期
capture_session 利用现有的分类法和相关知识建立知识获取会话

代码提示（仅限大脑代码mcp）

提示 描述
codebase_knowledge 关于按文件/符号分组的仓库的所有知识，以及可选的新鲜度检查
file_context 关于特定文件的所有知识，包括新鲜度和语义相关的未链接知识

设置

先决条件

快速入门（克劳德代码）

集 OPENROUTER_API_KEY 在您的shell环境中（例如 ~/.bashrc 或 ~/.zshrc):

export OPENROUTER_API_KEY="your-key-here"

然后添加到您的项目 .mcp.json:

{
  "mcpServers": {
    "brain": {
      "command": "npx",
      "args": ["-y", "github:markschaake/brain-mcp"],
      "env": {
        "DATABASE_URL": "postgresql://user:pass@host:5432/brain",
        "BRAIN_NAME": "personal"
      }
    }
  }
}

对于大脑代码mcp（包括代码感知工具）：

{
  "mcpServers": {
    "brain": {
      "command": "npx",
      "args": ["-y", "-p", "github:markschaake/brain-mcp", "brain-code-mcp"],
      "env": {
        "DATABASE_URL": "postgresql://user:pass@host:5432/brain",
        "BRAIN_NAME": "my-project"
      }
    }
  }
}

注： 不要放 OPENROUTER_API_KEY 在 .mcp.json --它经常被检查到版本控制中。服务器会自动从环境中读取它。

数据库架构在首次运行时自动创建。

数据库选项

选项1：使用附带的docker compose （最适合当地发展）

git clone https://github.com/markschaake/brain-mcp.git
cd brain-mcp
docker compose up -d   # starts PostgreSQL+pgvector on port 5488

使用docker compose时，默认 DATABASE_URL (postgresql://brain:brain@localhost:5488/brain)无需任何配置即可工作。

选项2：自带PostgreSQL

任何安装了pgvector扩展的PostgreSQL实例都可以工作。Set DATABASE_URL 在您的MCP配置中。架构在第一次服务器启动时自动应用。

本地开发

pnpm install
pnpm run build
pnpm run dev    # watch mode (tsc --watch)
pnpm run lint   # run ESLint

# Run directly
OPENROUTER_API_KEY=your-key node dist/index.js      # brain-mcp
OPENROUTER_API_KEY=your-key node dist/code.js        # brain-code-mcp

环境变量

变量 描述 默认值
DATABASE_URL PostgreSQL连接字符串 postgresql://brain:brain@localhost:5488/brain
OPENROUTER_API_KEY 嵌入生成所需 --
EMBEDDING_MODEL 覆盖嵌入模型 openai/text-embedding-3-small
BRAIN_NAME 使用哪个大脑（知识空间） personal
BRAIN_ACCESSIBLE 此实例可以访问的以逗号分隔的大脑名称白名单。空=所有大脑都可以访问。 （空）

多脑使用

所有工具和提示都接受可选 brain 参数，在运行时按名称定位特定大脑，而无需重新启动服务器。省略它以使用默认大脑(BRAIN_NAME).

只读工具(search, list_recent, explore_dimension, list_dimensions, list_adrs, search_code, check_freshness, refresh_stale_knowledge)也接受 brain: "*" 在所有可访问的大脑中查询。

编写工具(capture_thought, supersede_thought, capture_adr, capture_code_context)拒绝 "*" --您必须为写入指定一个大脑名称。

使用 BRAIN_ACCESSIBLE 限制服务器实例可以访问哪些大脑：

{
  "mcpServers": {
    "brain": {
      "command": "npx",
      "args": ["-y", "github:markschaake/brain-mcp"],
      "env": {
        "DATABASE_URL": "postgresql://user:pass@host:5432/brain",
        "BRAIN_NAME": "personal",
        "BRAIN_ACCESSIBLE": "personal,work,shared"
      }
    }
  }
}

当 BRAIN_ACCESSIBLE 如果为空（默认），则所有大脑都是可访问的。

建筑

源文件

文件 目的
src/index.ts 脑mcp入口点
src/code.ts 脑编码mcp入口点（超集）
src/tools.ts 共享工具注册（核心+ADR工具）
src/db.ts PostgreSQL连接池和助手
src/migrate.ts 自动迁移运行器（适用 migrations/*.sql 启动时）
src/embeddings.ts 通过OpenRouter嵌入生成
src/git.ts 用于新鲜度检测的Git操作
src/prompts.ts MCP提示注册（两台服务器的核心提示）

数据库模式

移民正在 migrations/ 并在服务器启动时自动应用。

  • 大脑 --孤立的知识空间
  • 想法 --内容+矢量（1536）嵌入+元数据（jsonb）+思维类型+状态
  • 维度 --带有元数据的类型化类别，每个类别（大脑、姓名、类型）都是唯一的
  • 思想维度 --带有可选上下文的多对多链接

使用HNSW对嵌入进行索引，以实现快速余弦相似性搜索。

代码链接维度类型

大脑代码mcp使用这些维度类型将知识与代码联系起来：

类型 名称约定 元数据
repo 存储库名称 {} （可扩展）
file 回购相对路径 {repo, line_start, line_end, git_sha}
symbol 符号名称 {repo, file, kind}

ADR元数据

ADR存储为 decision 结构化元数据的思考：

{
  "adr": true,
  "adr_number": 7,
  "adr_title": "Use pgvector for semantic search",
  "adr_status": "accepted",  // proposed | accepted | deprecated | superseded
  "adr_context": "Why this decision was needed...",
  "adr_alternatives": [{ "name": "Pinecone", "pros": [...], "cons": [...] }],
  "adr_consequences": ["Must run PostgreSQL with pgvector"],
  "adr_decided_date": "2026-03-01"
}

许可证

ISC

相关 MCP