AI导哈

向量内存服务器

Fremem 是一个持久化的向量内存服务器，专为 Windsurf、VS Code 和其他 MCP 兼容编辑器设计，提供本地优先的 AI 内存服务。

  • by iamjpsharma
  • Python
  • 本地部署
  • 1 星标
  • 更新于
在 GitHub 查看 iamjpsharma/MCPServer

使用说明

Fremem（前身为MCP内存服务器）

用于Windsurf、VS Code和其他MCP兼容编辑器的持久向量内存服务器。

🌟 哲学

  • 隐私第一，本地第一AI内存： 您的数据保留在您的机器上。
  • 无供应商锁定： 使用开放标准和本地文件。
  • 专为MCP设计： 专为增强Windsurf、Cursor和其他MCP兼容IDE而设计。

ℹ️ 状态（v0.2.0）

稳定：

  • ✅ 带Windsurf/Cursor的本地MCP内存
  • ✅ 多项目隔离
  • ✅ Markdown文档的摄入

还不稳定：

  • 🚧 自动摄取（文件观看）
  • 🚧 记忆修剪
  • 🚧 远程同步

注： 有两种方法可以运行此服务器：

  1. 本地IDE（stdio）：由Windsurf/Cursor使用（默认）。
  2. Docker/服务器（HTTP）：用于远程部署或Docker（暴露端口8000）。

🏥 健康检查

要验证服务器二进制文件是否正确运行：

# From within the virtual environment
python -m fremem.server --help

✅ 快速启动（5分钟设置）

有两种设置方法： 全局安装 （为便于使用而推荐）或 本地开发人员.

选项A：全局安装（如 npm -g)

此方法允许您运行 fremem 无需手动管理虚拟环境。

1.安装 pipx （如果尚未安装）：

MacOS（通过Homebrew）：

brew install pipx
pipx ensurepath
# Restart your terminal after this!

Linux/Windows： 看 pipx安装说明.

2.安装 fremem:

# Install from PyPI
pipx install fremem

# Verify installation
fremem --help

配置Windsurf/VS代码：

自从 pipx 将可执行文件放在PATH中，配置更简单：

{
  "mcpServers": {
    "memory": {
      "command": "fremem",
      "args": [],
      "env": {
        "MCP_MEMORY_PATH": "/Users/YOUR_USERNAME/mcp-memory-data"
      }
    }
  }
}

注意 MCP_MEMORY_PATH：这就是 fremem 将存储其持久数据库。您可以将其指向您喜欢的任何目录（在本地检查或创建它，如果它不存在）。我们推荐这样的东西 ~/mcp-memory-data 或 ~/.fremem-data这一定是一条绝对的道路。

选项B：本地开发设置

1.克隆和设置

git clone https://github.com/iamjpsharma/fremem.git
cd fremem

# Create virtual environment
python3 -m venv .venv
source .venv/bin/activate

# Install dependencies AND the package in editable mode
pip install -e .

2.配置Windsurf/VS代码（本地开发）

将此添加到您的 mcpServers 配置（例如。， ~/.codeium/windsurf/mcp_config.json):

注： 替换 /ABSOLUTE/PATH/TO/fremem 带有克隆目录的实际完整路径。

{
  "mcpServers": {
    "memory": {
      "command": "/ABSOLUTE/PATH/TO/fremem/.venv/bin/python",
      "args": ["-m", "fremem.server"],
      "env": {
        "MCP_MEMORY_PATH": "/ABSOLUTE/PATH/TO/fremem/mcp_memory_data"
      }
    }
  }
}

在本地开发模式下，通常将数据存储在仓库中（被git忽略），但您可以使用任何绝对路径。

🚀 用法

0.HTTP服务器（新）

如果您愿意，可以通过HTTP（SSE）运行服务器：

# Run on port 8000
python -m fremem.server_http

访问SSE端点 http://localhost:8000/sse 并向发送消息 http://localhost:8000/messages.

🐳 使用Docker运行

要在容器中运行服务器，请执行以下操作：

# Build the image
docker build -t fremem .

# Run the container
# Mount your local data directory to /data inside the container
docker run -p 8000:8000 -v $(pwd)/mcp_memory_data:/data fremem

服务器将在以下时间可用 http://localhost:8000/sse.

1.摄入（添加上下文）

使用附带的辅助脚本 ingest.sh 将文件添加到特定项目中。

# ingest.sh <project_name> <file1> <file2> ...

# Example: Project "Thaama"
./ingest.sh project-thaama \
  docs/architecture.md \
  src/main.py

# Example: Project "OpenClaw"
./ingest.sh project-openclaw \
  README.md \
  CONTRIBUTING.md

💡 项目ID命名约定

建议为项目ID使用一致的前缀，以避免冲突：

  • project-thaama
  • project-openclaw
  • project-myapp

2.在编辑器中连接

配置后，AI助手将可以使用以下工具：

  • memory_search(project_id, q, filter=None)：语义搜索。支持元数据过滤（例如。， filter={"type": "code"}).返回距离分数。
  • memory_add(project_id, id, text)：手动添加。
  • memory_list_sources(project_id)：摄入的特定文件。
  • memory_delete_source(project_id, source)：删除特定文件。
  • memory_stats(project_id)：获取块计数。
  • memory_reset(project_id)：清除项目的所有记忆。

人工智能将有效地对你摄入的文件进行“长期记忆”。

🛠 故障排除

  • 安装后“fremem:找不到命令”:

    • 这意味着 pipx 将二进制文件安装到不在系统PATH中的位置（例如。， ~/.local/bin).
    • 修复： 跑 pipx ensurepath 并重新启动您的终端。
    • 手动修复： 添加 export PATH="$PATH:$HOME/.local/bin" 到你的shell配置（例如。， ~/.zshrc).

  • “未找到MCP服务器”或连接错误:

    • 检查输出 pwd 以确保您的绝对路径 mcp_config.json 100%正确。
    • 确保虚拟环境(.venv)创建并安装依赖项。

  • “使用了错误的project_id”:

    • 人工智能有时会猜测项目ID。你可以明确地告诉它：“使用project_ID'project thaama'”。

  • 嵌入模型下载:

    • 在第一次运行时，服务器下载 all-MiniLM-L6-v2 型号（约100MB）。这可能会导致第一个请求的轻微延迟。

🗑️ 卸载

移除 fremem 从您的系统：

如果通过安装 pipx （全球）：

pipx uninstall fremem

如果本地安装（Dev）： 只需删除该目录。

📁 回购结构

/
├── src/fremem/
│   ├── server.py       # Main MCP server entry point
│   ├── ingest.py       # Ingestion logic
│   └── db.py           # LanceDB wrapper
├── ingest.sh           # Helper script
├── requirements.txt    # Top-level dependencies
├── pyproject.toml      # Package config
├── mcp_memory_data/    # Persistent vector storage (gitignored)
└── README.md

🗺️ 路线图

✅ 已完成（v0.1.x）

  • [x] 本地矢量存储（LanceDB）
  • [x] 多项目隔离
  • [x] Markdown摄取
  • [x] PDF摄取
  • [x] 语义组块策略
  • [x] Windows支持+可编辑安装修复程序
  • [x] HTTP传输包装器（SSE）
  • [x] 修复资源列表错误（清理MCP UX）
  • [x] 强大的文档+5分钟设置
  • [x] 多IDE支持（Windsurf、兼容Cursor的MCP）

🚀 近期（v0.2.x–生产准备就绪）

🧠 内存管理

  • [x] 列出每个项目的内存源
  • [x] 按源删除内存（文件级删除）
  • [x] 为每个项目重置内存
  • [x] 替换/重新索引模式（防止过时块）
  • [x] 内存统计数据（块计数、上次更新、大小）

🎯 检索质量

  • [x] 元数据过滤（例如，类型=决策|规则|上下文）
  • [x] 结果中的相似性评分
  • []混合搜索（语义+关键字）
  • []返回证据+与搜索结果的相似性得分
  • []每个项目可配置的top_k默认值

⚙️ 开发工作流程

  • []git提交/文件更改时自动摄取
  • [ ] mcp-memory init <project-id> 引导命令
  • []项目模板（Project_CONTEXT.md、DECISIONS.md、AI_RULES.md）

🧠 高级RAG（v0.3.x–差速器）

  • []分层检索（摘要优先，细节回退）
  • []内存压缩（旧块→ 摘要）
  • []时间排名（首选较新的决策）
  • []范围检索（计划者vs编码者vs审阅者代理）
  • []查询重写/扩展以提高召回率

🏢 团队/SaaS模式（可选）

理念：本地优先仍然是默认设置。SaaS是一种可选的部署模式。

🔐 授权和多租户

  • []项目级授权（API密钥或JWT）
  • []组织/团队分离
  • []内存更改的审核日志

☁️ 远程存储后端（可插拔）

  • []S3兼容矢量存储后端
  • []Postgres/pgvector后端
  • []同步和联合（本地↔ 远程）

🚫 非目标

  • ❌ 无强制云依赖
  • ❌ 无供应商锁定
  • ❌ 默认情况下，没有聊天记录作为“内存”（信号>噪声）
  • ❌ 无模型微调

相关 MCP