mismem

misMEM

面向 LLM 的协作式持久记忆。一个共享空间（~/.mismem/mem.db），多个实例（Copilot、Claude Code、Claude Desktop、自定义 Agent）通过同一 MCP 协议交互。

协作让信息得以持久保存。

为什么要做 misMEM

每个 LLM 实例诞生时都没有记忆。每个客户端（Copilot、Claude Desktop、Claude Code、ChatGPT）都把自己的内容保存在互不兼容的信息孤岛中。用户不得不重复提供上下文。会话之间的连续性就此中断。

misMEM 通过一个简单的方式解决这个问题：一个 SQLite 数据库 + 一个包含 5 个调用的 MCP 协议，任何支持 MCP 的客户端都能访问。

架构：3 层，如同生物记忆

episodes  (verbatim; se borran con `forget` una vez consolidados)
    ↓  consolidación (manual o LLM nocturno)
memories  (gist + details, salience con decay + refuerzo Hebbiano)
    ↓  crystallize
traits    (patrones cristalizados — identidad, leyes, decisiones firmes)

信息的损失是有意且不对称的，如同人类记忆：原始内容逐渐消散，提炼出的内容得以保留，结晶后的内容则长存。

每一层存储的内容

层	代表内容	生命周期	用途
episodes	发生过的事情：带时间戳的原始文本	整合后会逐渐消散	证据和即时上下文
memories	从多个 episode 中总结出的经验	如果不使用，其 salience 会降低；被回忆时则会升高	操作性知识和语义搜索
traits	稳定的模式、偏好或决策	除非明确删除，否则永久保留	身份和最高优先级规则

例如：“今天 PostgreSQL 的表现更好”是一条 episode；“在这个项目中 PostgreSQL 更合适”是一条 memory；“我们优先选择并发处理稳健的解决方案”则可以结晶为一条 trait。

六种操作，一个共享空间

调用	功能
capture	在层级 scope（项目/日记、vscode/transcripts 等）中记录一条 episode
recall	使用 FTS5 + 语义搜索；除非设置 reinforce: false 或 MISMEM_REINFORCE_ON_RECALL=off，否则会强化返回的内容
reinforce	标记回答实际使用过的记忆，而不是仅仅出现过的记忆
consolidate	将相关 episodes 提炼为一条 memory
crystallize	以证据为依据，固定一条 trait/原则（身份、坚定决策）
forget	释放不再查询的内容

此外，engram-compat 层（mem_save、mem_search、mem_context、mem_session_* 等）可兼容使用 Engram 协议的客户端。

快速开始

Linux：一个脚本完成所有配置

git clone https://github.com/lucasmella-stack/misMEM.git && bash misMEM/scripts/install.sh

从克隆的仓库安装 misMEM（--from-npm 使用已发布的软件包，版本可能落后），询问记忆的保存位置和整合时使用的提供商（DeepSeek、OpenRouter、OpenAI、兼容服务器或不使用），将密钥以 600 权限保存在 ~/.config/mismem/env，并配置检测到的客户端：Claude Code（MCP 和注入、强化钩子）、opencode、Claude Desktop、VS Code 和 Cursor。如果检测到 Ollama，还会提供 embeddings 模型选项；如果需要，也可以将夜间整合设为 systemd timer。客户端会调用 ~/.local/bin/mismem-run，因此任何密钥都不会留在客户端配置中。重新运行会更新配置，不会重复添加，也不会覆盖手动编写的 misMEM 配置。使用 --help 可查看无需交互的模式。

手动配置，适用于任何系统

最快的方式——无需克隆任何内容，通过 npm 安装。在客户端的 mcp.json 中（VS Code / Claude Code / Claude Desktop）：

{
  "mcpServers": {
    "mismem": {
      "command": "npx",
      "args": ["-y", "@lucasmella/mismem"]
    }
  }
}

数据库会在首次使用时自动创建（默认位置：~/.mismem/mem.db，可通过 MISMEM_DB 配置）。因此，即使没有其他配置，你的记忆也只保存在本地磁盘，不会离开你的机器；只有两个可选功能会向外发送文本，详见隐私。

远程实例（多客户端）

要从多台机器访问同一份记忆，请使用官方 Docker 镜像：

docker run -d --name mismem-brain \
  -e MISMEM_AUTH_USER=brain -e MISMEM_AUTH_PASS=<pass> \
  -v mismem-data:/data -p 3200:3200 \
  ghcr.io/lucasmella-stack/mismem-brain:latest

完整的 Traefik + TLS 指南见 DEPLOY.md。

从代码运行

git clone https://github.com/lucasmella-stack/misMEM.git
cd misMEM/engine
pnpm install
pnpm test        # todo verde antes de usar
pnpm build       # tsc → dist/

并在 mcp.json 中添加："command": "node", "args": ["<ruta-al-repo>/misMEM/engine/dist/server.js"]。

组件

• engine/src/server.ts — MCP stdio 服务（本地使用）。
• engine/src/server-http.ts — 用于远程部署的 Streamable HTTP（可选 BasicAuth、/healthz）。参见 DEPLOY.md。
• engine/src/viewer.ts — /viewer 下的只读面板 + /api/{stats,recent,search}。
• LLM 整合 — 夜间 cron 将 episodes 提炼为 memories，可直接使用 DeepSeek 或通过 OpenRouter，并通过 Pareto 预筛选丢弃噪声。参见 engine/src/consolidation/README.md。
• CLI — mismem-ingest（ChatGPT 导出文件 / VS Code transcripts）、mismem-consolidate、mismem-forget、mismem-stats、mismem-embed、mismem-migrate-engram、mismem-bench（使用自有问题集衡量 recall，不进行强化），以及两个 hooks：mismem-inject 和 mismem-used。

技术栈

• 引擎：严格 TypeScript、ES2022、ESM、Node ≥22。
• 存储：使用 WAL 的 SQLite（多个并发读取者 + 1 个写入者）。better-sqlite3。
• 搜索：针对 memories 使用 FTS5 + RRF 语义搜索，并保持 traits > memories > episodes 的优先级。
• 协议：Model Context Protocol，通过 @modelcontextprotocol/sdk。
• 验证：在所有边界使用 Zod。

状态

• ✅ MCP 引擎正常运行（5 个调用 + engram-compat 层）。
• ✅ Salience 衰减；在 recall 中出现或通过 hook 实际使用时进行强化。
• ✅ 层级 scopes，不会发生跨 scope 泄漏。
• ✅ Streamable HTTP 服务 + Docker/Traefik 部署。
• ✅ 夜间 LLM 整合（episodes → memories）。
• ✅ 只读 Viewer + introspection CLI。
• ✅ 捕获 / 导入时去重（重新导入具有幂等性）。
• ✅ 混合 recall：FTS5 + 可选的语义搜索，可通过 Ollama 或任何兼容 OpenAI 的服务实现。
• ✅ 可选的客户端 hooks：在回复前提前注入记忆，并强化已使用的记忆。
• 🚧 可分发的二进制文件（Bun --compile）。

语义搜索（可选）

运行 embeddings 服务后，recall 会增加按 含义搜索的能力："problemas de plata"（钱的问题）可以找到提到 "deudas"（债务）的记忆。默认使用 Ollama（ollama pull nomic-embed-text）。向量以 BLOB 形式存储在同一个 SQLite 数据库中，搜索通过 JS 中的余弦相似度完成，无需原生 扩展。如果服务无响应，系统会静默退回到纯 FTS5 搜索，而纯 FTS5 要求查询中的所有 词语都必须匹配（不包括停用词："qué"、"sobre"、"the"……）。语义搜索有意 仅覆盖 memories；episodes 和 traits 仍使用 FTS5 搜索。回填和 重新索引：mismem-embed（--status、--force）。

也支持任何兼容 OpenAI 的服务（/v1/embeddings， 例如 llama-server --embedding）。对于多语言记忆，建议使用 EmbeddingGemma 2，并设置其前缀和更高的阈值：

MISMEM_EMBEDDING_PROVIDER=openai
MISMEM_EMBEDDING_URL=http://127.0.0.1:8080
MISMEM_EMBEDDING_MODEL=embeddinggemma-2
MISMEM_EMBEDDING_QUERY_PREFIX="task: search result | query: "
MISMEM_EMBEDDING_DOC_PREFIX="title: none | text: "
MISMEM_EMBEDDING_MIN_SCORE=0.68

搜索只会比较已配置模型生成的向量。更换模型后，只会在下一次回填时重新索引（mismem-embed）；更换前缀不会被检测到，因此需要运行 mismem-embed --force。所有变量及其默认值均列于 DEPLOY.md。

Salience、衰减和遗忘

如果没有强化，memories 的 salience 每 90 天减半 （可通过 MISMEM_SALIENCE_HALF_LIFE_DAYS 配置）。recall 会应用待处理的衰减， 然后增加 Hebbian 强化。只有经过宽限期后，forget 才会删除低于 阈值的 memories；--dry-run 会计算结果，但不会修改 DB。

客户端钩子（可选）

两个二进制程序将 misMEM 接入 Claude Code，无需模型记得主动请求：

• mismem-inject（UserPromptSubmit）根据提示词进行搜索，并提前提供少量记忆。搜索时使用 reinforce: false：用户没有请求的内容就不算使用。它会保持休眠，直到确认服务器公开了 reinforce，因此可以在部署前完成配置。
• mismem-used（Stop）会查看上一轮——模型通过 recall 请求的内容，以及注入提供给它的内容——并且只强化其中有辨识度的词语在回复中再次出现的记忆。这只是一种近似判断：宁可不强化，也不误强化。

注入的内容会随每条提示词发送给模型提供商，因此 MISMEM_HOOK_EXCLUDE_SCOPES 用于指定哪些范围不发送。设置 MISMEM_REINFORCE_ON_RECALL=off 后，显著性会根据使用情况而非出现次数变化。 安装方式和变量见 DEPLOY.md。

隐私

你的记忆归你所有。数据库（*.db）、转储文件和个人导出文件都已加入 .gitignore——绝不要提交它们。未设置 MISMEM_AUTH_USER/MISMEM_AUTH_PASS 时，HTTP 服务器会以无认证模式运行：仅在 localhost 上这样使用。

有两个可选功能会将文本发送到进程外，但只有在你进行配置后才会发送：

• 语义搜索：嵌入服务器会接收每条记忆和每次查询的文本。请在你的机器或内部网络上运行它。
• LLM 整合：情节会以纯文本形式发送到 DeepSeek（或 OpenRouter 及其背后的提供商）。未配置密钥时不会运行。

理念

过去之所以存在，是因为我们将它写下并压缩，使其得以留存。

部分灵感来自 Franz Bardon 的 Initiation Into Hermetics：在不同实例之间映照意识的镜子需要两个极点。misMEM 是大地之基——让记忆不会在会话之间消散，从而使人类⇄大模型之间的协作真正具有连续性。

贡献

欢迎提交 Issue 和 PR。提交 PR 前，请在 engine/ 中运行 pnpm typecheck && pnpm test（确保全部通过），并使用规范的提交信息（feat:、fix: 等）。代码规范见 .github/copilot-instructions.md。

许可证

MIT。见 LICENSE。