Gemdex

只需保存一次有用的记忆，即可在不同代码仓库和会话中随时取用。Gemdex 会为小块内容建立索引，通过语义与 BM25 混合匹配实现精准检索，然后将 匹配结果关联到完整的父级记忆。MCP Agent 会先扫描开销低廉的标题索引，只打开 所需的记忆。

两种运行方式

	本地	自托管
Agent 连接方式	npx gemdex-mcp，stdio	Streamable HTTP /mcp
嵌入	通过 MLX 在设备上运行 EmbeddingGemma 2	由服务端管理 Gemini，支持多模态
存储	~/.gemdex 下的 LanceDB 和 blob	Postgres/pgvector 和文件/S3 blob
平台	Apple Silicon、macOS 14+、原生 arm64 Node ≥24	Docker 主机
人工管理	通过 localhost sidecar 使用原生 macOS 应用	Web 管理器
记忆池	每台设备一个	多台设备共享
MCP 工具	七个，包含删除	六个，不含删除

这是两个独立的记忆池。npx 包和桌面 sidecar 仅支持本地连接； 如需使用自托管记忆池，请直接连接 HTTP MCP。

本地快速入门

npx gemdex-mcp install
claude mcp add gemdex -- npx -y gemdex-mcp@latest

显式安装会下载托管的 Python/MLX，以及固定版本的 mlx-community/embeddinggemma-2-8bit 权重，下载约需 1.45 GB，磁盘占用为 1.9 GB。无需配置 Python、uv、Homebrew、 HF CLI 或编译器。安装后，嵌入可离线运行。无需 API 密钥、 占位值或切换提供商。不支持 Rosetta Node。 请参阅 MLX 模型和运行时要求。

安装前即可发现全部七个工具，但调用时会返回设置指南。安装后重试工具， 或重新连接 MCP 客户端。

使用其他 MCP 客户端：

{
  "mcpServers": {
    "gemdex": {
      "command": "npx",
      "args": ["-y", "gemdex-mcp@latest"]
    }
  }
}

保存和回忆

让 Agent 保存一条值得长期保留的信息：

Save how we set up the review workflow to memory.

然后，在使用同一记忆池的另一个会话或代码仓库中：

Check memory for our review workflow and use it here.

在 Agent 的指令中说明何时使用记忆：

## Memory

Use Gemdex recall to find relevant memories before starting work.
Save reusable findings and update existing memories when correcting them.
Report worked/failed/stale outcomes after acting on a fetched memory.
Use read_attachment for transcript bytes.
Delete only when a memory should be permanently removed and the connected
surface provides delete_memory.

MCP 工具

工具	行为
save_memory	保存内容和/或附件（图像、音频、视频、文本文件）；返回 id 和标题
recall	使用文本查询和/或示例媒体文件，返回排名前 10 的标题及 id，不返回完整正文
get_memory	返回完整的父级正文、年龄、附件和使用记录
update_memory	完整替换 content 或应用字面量 edits，可选更新标题/附件
report_outcome	记录 worked、failed 或 stale，可附加备注
read_attachment	将附件作为 UTF-8 文本、可查看图像或 base64 返回
delete_memory	仅限 Stdio，永久删除并清理客户端统计数据

只有 get_memory 会增加回忆次数，标题索引检索不会。 统计数据存储在单独的账本中（默认为 ~/.gemdex/stats.json）。 GEMDEX_TRUST_RANKING=true 可启用按结果加权的标题排序； 否则仅按相关性排序。

本地保存时，如果现有记忆与新内容相似，系统会发出提示；提示使用 已计算的向量和质心相似度（默认阈值为 0.93）。 提示不会阻止保存。可通过 GEMDEX_SIMILAR_ON_SAVE 和 GEMDEX_SIMILAR_THRESHOLD 配置。

附件

本地记忆可以包含图像（PNG、JPEG、WebP、GIF）、音频（WAV、MP3、M4A、 FLAC、AAC、AIFF；最长 5 分钟）和视频（MP4、MOV、M4V、WebM）。EmbeddingGemma 2 会在设备本地将每个文件嵌入到与文本相同的空间中，因此可以根据图像内容或录音内容找到记忆。回忆时也可以提供示例文件： “记忆里有没有关于这张截图的内容？”无论是否提供文本查询，都可以使用。说明文字是可选的；它们会增加关键词匹配，对音频最有帮助。文本文件（.txt、.json、.jsonl/.ndjson）以未嵌入的二进制数据存储。每条记忆最多可包含：8 张图像、4 个音频文件、2 个视频和 4 个文本文件，每个文件最大 100 MiB。本地不支持 PDF。请使用本地 path 或内嵌的 base64 data + mimeType；所有附件都可以通过 read_attachment 读取。

可自托管服务通过 /v1 支持 Gemini 多模态嵌入和媒体回忆。 HTTP MCP 附件输入只能使用内嵌的 base64，绝不能使用客户端文件系统路径。请参阅 /v1 contract。

聊天记录与记忆整理

本地消化和整理使用你现有的 Claude Code 登录状态。安装 Claude Code 并运行 claude auth login，然后：

npx gemdex-mcp status
npx gemdex-mcp ingest-history --source claude --dry-run
npx gemdex-mcp ingest-history --source claude

来源包括 Claude Code、Factory CLI、Codex、Antigravity 或文件夹路径。 只会处理此前从未摄取过的会话。每个会话都会生成一条摘要记忆和一份经过整理的对话记录附件。backfill-transcripts 会附加较早摘要页脚中引用的文件，并支持 --dry-run 和 --force 选项；找不到的文件会跳过并显示提示。

推理以相互隔离的 claude -p --model haiku 结构化 JSON 调用运行： 不使用工具、设置、技能、MCP 服务、钩子、CLAUDE.md 或会话持久化，并使用临时工作目录。并发数为 4，每次调用最多尝试 3 次，总超时时间为 5 分钟。

费用估算采用 Haiku API 列表价格等值（每百万个 token 输入 $1 / 输出 $5）。使用 Claude 订阅时，额度计入套餐限制，而非按 token 计费。本地嵌入始终在设备上完成，但摄取的对话记录和整理候选项会通过 Claude Code 推理处理。

整理流程会先对本地向量进行聚类，再由 Claude Code 判断候选项。删除发现项需要人工批准。可自托管部署的上传内容则使用服务端的 Gemini 消化流程。请参阅聊天记录路径。

桌面应用

原生 macOS 应用负责管理本地池：浏览、搜索（按文本或文件）、编辑记忆、附加和预览图像、音频与视频、摄取聊天记录，以及审核整理发现项。它与 gemdex serve 通信，后者仅绑定到 127.0.0.1，并使用每次启动时生成的令牌。其接口提供明确的 MLX 安装／迁移任务和 Claude Code 就绪状态。安装完成前，记忆路由会返回 503 {needsInstall:true}；开始摄取／整理前，Claude Code 必须处于就绪状态。请参阅 sidecar contract。

Web 管理器是可自托管部署中主要供人使用的界面。 桌面应用不是该池的客户端。

自托管整套服务（一条命令）

curl -fsSL https://raw.githubusercontent.com/nikships/gemdex/main/scripts/install.sh | bash

安装程序会启动 Postgres、gemdex-server、HTTP MCP 和 Web 管理器，生成密钥，等待迁移完成，验证实际的保存和回忆操作，并打印 Streamable HTTP 客户端配置。它会要求提供 Google AI Studio 密钥，或读取 GEMINI_API_KEY。此密钥属于服务端，而非 Agent 客户端。

默认情况下仅监听本地回环地址。使用 --lan 可通过静态 MCP 身份验证向可信的局域网开放 MCP 和 Web，并允许免登录访问 Web。若要公开访问，请使用 HTTPS、Google OAuth 和部署指南。切勿公开 Postgres 或 /v1。

{
  "mcpServers": {
    "gemdex": {
      "type": "http",
      "url": "https://gemdex.example.com/mcp"
    }
  }
}

此示例面向 Google OAuth 部署；客户端会处理登录。

指南	用途
自托管部署	Compose、Google OAuth、HTTPS 入口和开放检查
运维	存储、备份/恢复、升级和故障排查
进一步探索	DNS、托管平台、规格和成本
安全	强制执行的边界和上线前检查清单
聊天记录	本地导入、Web 上传和 OAuth 记录导入

软件包和库的使用

软件包	职责
core	MemoryStore、嵌入提供方、共享 HTTP 路由器和推理
mcp	本地 stdio 工具、命令行和桌面端 sidecar
server	BYOI /v1、Postgres/pgvector、Gemini 和文件/S3 blob
mcp-http	六工具 Streamable HTTP Agent 接口
web	浏览器管理器和会话上传 BFF
app	原生本地管理器

如需直接使用引擎，请参阅 core 库示例。 本地环境设置见 MCP README；自托管设置见 server README。

隐私与安全

除非你自行添加存储控制措施，否则记忆文本和附件字节均以明文形式存储。Gemdex 不提供机密信息脱敏或托管保管服务。本地嵌入在设备上运行；本地导入和数据清理会通过你的账户，使用 Claude Code 处理所选内容。自托管服务端会使用自己的密钥，将嵌入载荷和上传会话的内容整理结果发送给 Gemini。请参阅保管和自托管安全。

从源代码构建

在 Node ≥24 和 pnpm ≥10 的克隆仓库中运行：

pnpm install
pnpm build

本地 MCP 入口点为 packages/mcp/dist/index.js。 检查与开发指南请参阅 CONTRIBUTING.md。

许可证

MIT。请参阅 LICENSE。

MCP Registry

mcp-name: io.github.nikships/gemdex