Mimir MCP

Medha MCP

Git-backed AI Memory System

Medha是一个模型上下文协议（MCP）服务器，为LLM应用程序提供持久的、git版本的内存存储。它将Git的版本控制功能与基于图的内存关联相结合，使LLM能够维护长期内存。

特性

• 🔐 灵活的身份验证：本地模式（开发）或SAML 2.0（使用DUO/Okta生产）
• 📝 Git备份存储：每次内存更改都是一次具有完整历史记录的git提交
• 🕸️ 图形关联：将记忆与键入的关系联系起来
• 🔍 强大的搜索功能：按标签、日期、内容和关联进行搜索
• 🧠 语义搜索：使用OpenAI嵌入的可选AI驱动矢量搜索
• 📊 知识图谱：通过N-hop查询遍历内存关联
• 🔄 自动同步：通过PAT身份验证每小时同步到GitHub
• 💾 双存储器：Git存储库（主）+每个用户的SQL数据库（索引）
• 🗑️ 软删除：存档记忆，同时保留完整的历史
• 🏢 多数据库：SQLite用于开发/本地，PostgreSQL用于系统数据库
• 🔒 乐观锁：来自多个AI代理的安全并发访问

建筑

需求

• 转到1.24+ -从源头进行建设
• Git 2.x+ -版本控制内存存储所需（git必须在PATH中）
• GCC/构建工具 -CGO（sqlite-vec矢量搜索）所需

- macOS： xcode-select --install - Linux： sudo apt install build-essential - Windows：使用Docker（推荐）或MinGW

快速开始

1.建造

make setup    # Run initial setup
make deps     # Install dependencies
make build    # Build the binary

2.MCP客户端集成

选项1：原生二进制

添加到MCP客户端配置中：

光标 (~/.cursor/mcp_settings.json):

{
  "mcpServers": {
    "medha": {
      "command": "/path/to/bin/medha",
      "env": {
        "ENCRYPTION_KEY": "your-32-char-encryption-key-here"
      }
    }
  }
}

克劳德桌面版 (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "medha": {
      "command": "/path/to/bin/medha",
      "args": [],
      "env": {
        "ENCRYPTION_KEY": "your-32-char-encryption-key-here"
      }
    }
  }
}

选项2：快跑

直接使用运行Medha go run 无需安装-类似于 uvx 对于Python或 npx 对于Node.js。

先决条件： 安装Go 1.24+ go.dev/dl Git在你的路径中：

# macOS (Homebrew)
brew install go git

# Ubuntu/Debian
sudo apt update && sudo apt install golang-go git

# Windows (Chocolatey)
choco install golang git

MCP客户端配置：

{
  "mcpServers": {
    "medha": {
      "command": "go",
      "args": ["run", "github.com/tejzpr/medha-mcp/cmd/server@latest"],
      "env": {
        "ENCRYPTION_KEY": "your-32-char-encryption-key-here"
      }
    }
  }
}

选项3：Docker容器

配置您的MCP客户端以使用Docker Hub映像（无需构建）。

简单模式（单用户）：

用途 whoami 内部容器，返回 medha。所有记忆都存储在 medha 用户。

{
  "mcpServers": {
    "medha": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-v", "/Users/yourname/.medha:/home/medha/.medha",
        "-e", "ENCRYPTION_KEY=your-32-char-encryption-key-here",
        "tejzpr/medha-mcp"
      ]
    }
  }
}

多用户模式（带 --with-accessinguser):

用途 ACCESSING_USER env-var表示用户身份。当多个用户共享同一Medha实例或与经过身份验证的系统集成时非常有用。

{
  "mcpServers": {
    "medha": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-v", "/Users/yourname/.medha:/home/medha/.medha",
        "-e", "ENCRYPTION_KEY=your-32-char-encryption-key-here",
        "-e", "ACCESSING_USER=yourname",
        "tejzpr/medha-mcp",
        "--with-accessinguser"
      ]
    }
  }
}

重要提示： - 替换 /Users/yourname 使用您的实际主目录路径（例如。， /Users/john 在macOS上， /home/john 在Linux上） - 替换 yourname 在 ACCESSING_USER 使用您的实际用户名 - MCP客户端不扩展 $HOME 或 ~ 在JSON配置中-使用绝对路径 - 这 .medha mount持久化您的数据库和git存储库 - 容器以用户身份运行 medha （uid 1000），数据存储在 /home/medha/.medha

本地构建（可选）：

docker build -t medha-mcp .

然后使用 medha-mcp 而不是 tejzpr/medha-mcp 在您的配置中。

所需安装：

环境变量：

旗帜说明：

• -i =交互模式（stdio传输所需）
• --rm =完成后移除容器
• --with-accessinguser =使用 ACCESSING_USER env-var而不是 whoami 用于用户身份

3.运行模式

stdio模式（默认）：用于MCP客户端集成

./bin/medha                      # Uses system user (whoami)
./bin/medha --with-accessinguser # Uses ACCESSING_USER env var

• 通过stdin/stdout进行通信
• 自动对用户进行身份验证
• 无需web界面

HTTP模式：用于web界面

./bin/medha --http              # Default port 8080
./bin/medha --http --port=9000  # Custom port

• 在以下位置提供web身份验证 http://localhost:8080/auth
• 支持SAML 2.0用于企业SSO

4.配置（可选）

编辑 ~/.medha/configs/config.json 对于高级设置：

{
  "auth": {
    "type": "local"
  },
  "server": {
    "host": "localhost",
    "port": 8080
  },
  "database": {
    "type": "sqlite",
    "sqlite_path": "~/.medha/db/medha.db"
  },
  "git": {
    "sync_interval_minutes": 60
  },
  "security": {
    "token_ttl_hours": 24
  },
  "embeddings": {
    "enabled": false,
    "provider": "openai",
    "model": "text-embedding-3-small",
    "api_key_env": "OPENAI_API_KEY",
    "dimensions": 1536
  }
}

看 配置指南 包括SAML设置在内的所有选项。

5.启用语义搜索（可选）

对于基于AI的语义搜索，启用嵌入：

# Via command line
./bin/medha --enable-embeddings

# Or set in config.json
"embeddings": { "enabled": true }

要求：

• 集 OPENAI_API_KEY 环境变量
• 或者配置兼容的嵌入API端点

带嵌入的Docker：

{
  "mcpServers": {
    "medha": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-v", "/Users/yourname/.medha:/home/medha/.medha",
        "-e", "ENCRYPTION_KEY=your-32-char-key",
        "-e", "OPENAI_API_KEY=sk-your-key",
        "-e", "MEDHA_EMBEDDINGS_ENABLED=true",
        "tejzpr/medha-mcp"
      ]
    }
  }
}

MCP工具

Medha使用 人工对齐工具 表达意图而非实施。这使得LLM更容易正确使用它们。

medha_recall

“我对X了解多少？” -查找和检索信息：

{
  "topic": "authentication approach",
  "limit": 10
}

还支持 list_all: true 用于浏览和 exact: "text" 用于文字搜索。

medha_会员

“保存此内容以备后用” -创建或更新记忆：

{
  "title": "Project Alpha Kickoff",
  "content": "# Meeting Notes\n\nDiscussed project timeline...",
  "tags": ["project", "meeting"],
  "replaces": "old-meeting-notes"
}

使用 replaces 取代旧信息（将其标记为过时）。

梅达历史

“我什么时候知道X的？” -时态查询：

{
  "slug": "project-alpha",
  "show_changes": true,
  "since": "7d"
}

medha_connect

“这些是相关的” -链接或取消链接记忆：

{
  "from": "project-alpha",
  "to": "contact-john-doe",
  "relationship": "person"
}

medha_forget

“不再相关” -存档内存：

{
  "slug": "old-decision"
}

Medha恢复

“把存档的记忆带回来” -取消删除：

{
  "slug": "old-decision"
}

Med shaync

手动同步到GitHub：

{
  "force": false
}

内存格式

内存存储为带有YAML frontmatter的Markdown文件：

---
id: project-alpha-kickoff-2024-01-15
title: "Project Alpha Kickoff Meeting"
tags: [project, meeting]
created: 2024-01-15T10:30:00Z
updated: 2024-01-15T14:00:00Z
associations:
  - target: contact-john-doe
    type: person
    strength: 1.0
---

# Project Alpha Kickoff Meeting

## Attendees
- John Doe (Project Lead)

## Key Decisions
...

目录结构

~/.medha/
├── configs/
│   └── config.json              # User configuration
├── db/
│   └── medha.db                 # System database (users, auth, repos)
└── store/
    └── medha-{username}/        # User's git repository
        ├── .medha/
        │   └── medha.db         # Per-user database (memories index)
        ├── 2024/
        │   └── 01/              # Date-organized memories
        ├── tags/
        │   └── meetings/        # Tag-based organization
        └── archive/             # Soft-deleted memories

数据库体系结构（v2）：

• 系统数据库 (~/.medha/db/medha.db)：用户、身份验证、存储库注册表
• 每个用户数据库 (store/medha-{user}/.medha/medha.db)：内存索引、关联、标签（git跟踪）

发展

注： sqlite-vec需要CGO。确保GCC已安装。

# Build
make build              # Build binary (CGO enabled)
make build-native       # Build optimized for current platform

# Run tests
make test               # Run unit tests
make test-integration   # Run integration tests
make test-functional    # Run functional tests
make test-all           # Run all tests

# Run server
make run                # stdio mode (MCP)
make run-http           # HTTP server mode
make run-with-embeddings # With semantic search

# Code quality
make lint               # Run linter
make vet                # Run go vet
make coverage           # View test coverage

# Docker
make docker-build       # Build Docker image
make docker-run         # Run container
make docker-run-with-embeddings # With embeddings

数据库重建

如果你需要从git仓库重建数据库索引：

# Rebuild system database from git
medha --rebuilddb

# Rebuild and overwrite existing data
medha --rebuilddb --force

# Rebuild per-user database (v2)
medha --rebuild-userdb all           # All users
medha --rebuild-userdb username      # Specific user
medha --rebuild-userdb /path/to/repo # By path
medha --rebuild-userdb all --force   # Force overwrite

贡献

欢迎投稿！请确保：

• 所有测试均通过(make test)
• 代码格式正确(go fmt)
• 林特尔传球(make lint)
• 文档已更新

许可证

该项目根据 Mozilla公共许可证2.0.