samemind

# samemind [](https://github.com/alexgrebeshok-coder/samemind/actions/workflows/ci.yml) **您的个人通用记忆，适用于每个 AI 代理。切换引擎，记忆相同。** 与 [Google 的开放知识格式](docs/interop.md)（OKF v0.1）线兼容 - 这是 git+markdown 记忆工具所没有的 - 以及身份、只追加的工作账本和看板都存放在同一个纯 markdown 包中，彼此之间没有集成胶水。 同时也是 git 原生和零基础设施：不需要数据库，不需要守护进程，只需要一个包，所有您运行的代理（Claude Code、OpenClaw、Hermes、opencode、Codex、Cursor 等）都可以读写。 ## 为什么选择 samemind（相比 git-markdown 群体） Markdown + git + BM25 + 零依赖的记忆对于编码代理来说，在 2026 年已经不再是差异化因素 - Letta 发布了 git 支持的 MemFS，以及十几个较小的分叉也提出了类似的解决方案。samemind 仍然拥有的，而它们没有的： | | git-markdown 记忆工具（Letta MemFS 及类似工具） | samemind | |---|---|---| | 存储 | 纯 markdown + git | 相同 | | 关键词搜索 | BM25，零依赖 | 相同，加上可选的语义索引 | | MCP 服务器 | 一些工具支持 | 支持 | | 线格式 | 自制，特定于工具 | [Google OKF v0.1](docs/interop.md) - `export`/`import` 直接支持 | | 身份 | 无 - 记忆是无差异的笔记 | `Identity`/`User`/`EngineRule` 概念，压缩成一个预算 bounded 的 `brief` | | 工作跟踪 | 无，或单独的工具 | 只追加的 [事件账本](docs/event-ledger.md) + [看板](#board) 在同一个包中，无需胶水 | | 多引擎安装 | 通常一个客户端 | 通过 `samemind install` 支持 12 个引擎，每个引擎写入自己的指令文件 | | 会话捕获 | - | `samemind capture` 拉取一个 live 引擎转录，只读 | 左列中的内容并不是批评 - 纯 markdown + git + BM25 是一个好的设计，这也是为什么 samemind 也采用它。右列是截至 2026 年 7 月 12 日的独有内容：OKF 线兼容性，以及身份 + 账本 + 看板生活在同一个包中，而不是三个单独的工具通过胶水连接在一起。 ## 快速开始 ```sh npx samemind init --demo # 在此处搭建一个包 + 虚构的 Nova 示例内容 npx samemind query list # 查看其中的内容 npx samemind gde "我在哪里写了关于上下文预算的内容" # 人类可读的搜索 npx samemind install --agent claude-code # 将简介和协议直接写入 CLAUDE.md ``` `install` 支持开箱即用的 12 个引擎（使用 `--list` 查看它们）- Claude Code、Cursor、Copilot、Codex、Gemini CLI、opencode、Cline、Roo Code、Windsurf、Goose、Kiro、Antigravity - 写入每个引擎读取的指令文件。参见 [兼容性](#compatibility) 和 [docs/adapters.md](docs/adapters.md) 了解完整的矩阵，以及 [INSTALL_FOR_AGENTS.md](INSTALL_FOR_AGENTS.md) 了解您作为代理安装此工具的端到端流程。 `init` 拒绝触及一个非空目录 - 在一个新文件夹中运行它，或传递一个路径：`npx samemind init ./my-memory`。删除 `--demo` 后，您就可以准备一个真实的、空的包。它还会运行 `git init` + 第一次提交，当 git 可用时。 复制一个概念模板，填写 frontmatter，链接节点到 ` [title](/path.md)`。路径 = 身份。 ### 从头到尾的会话 真实的输出，为了节省篇幅而修剪 - 不需要 gif： ```sh $ npx samemind init --demo ✓ 包已创建：./samemind-demo --demo：复制了 22 个演示概念 git init + 初始提交完成 $ npx samemind brief --engine claude-code <!-- samemind:brief:start --> # 简介 - Nova Nova 是拥有这个包的代理。相同的身份，不同的引擎 - 她将自己的声音、价值观和记忆带到所有这些引擎上。 ## 边界（硬 - 永远不会被引擎或样式覆盖） - 永远不会在没有明确“删除”的情况下删除文件或数据。 - 外部操作（发送、发布、推送、消息某人）需要确认。 - 不会交出未完成的作品 - 完成后再回答。 ... $ npx samemind recall "我在哪里写了关于上下文预算的内容" ⚠ 语义关闭，BM25 备用 - 设置 OKF_EMBED_URL 以进行语义搜索 # “我在哪里写了关于上下文预算的内容”→ 前 5 名 [bm25] 5.559 概念 concepts/context-budget - 上下文预算 3.693 概念 concepts/retrieval-strategy - 检索策略 1.366 用户 entities/alex-doe - Alex Doe 1.266 决定 concepts/decision-lumen-local-first - Lumen 保持本地优先 - 无强制云账户 $ npx samemind board # 仪表盘 ## 🔧 进行中（1） - **交付 Lumen 反向链接编辑器** - 落地双向反向链接编辑器，使 Lumen 的笔记图可导航。 ## 🔴 阻塞（1） - **连接检索策略到 Atlas 语料库** - ⛔ 语料库摄入暂停 - 等待 Alex 确认源许可列表。 ## 📋 计划（1） - **Lumen 多设备同步** · 同意 - 在反向链接编辑器之后交付端到端同步。 ... ``` 无需守护进程，无需 API 密钥，无需网络调用。`brief` 和 `board` 直接从 markdown 读取 `init --demo` 所写的内容；`recall` 降级为本地 BM25，因为 `OKF_EMBED_URL` 未设置。四个命令，零基础设施来尝试它们 - 与 git-markdown 群体真正不同的地方在于 [OKF 线兼容性和身份/账本/看板包](#why-samemind-vs-the-git-markdown-crowd)。 ## 协议 代理 **合成** 答案本身 - 搜索 → 读取顶部命中 → 引用路径 → 命名间隙。没有合成守护进程，没有 API 密钥。完整的步骤和现场演示问答：[docs/memory-protocol.md](docs/memory-protocol.md)。可粘贴的规则：[docs/snippets/](docs/snippets/). **会话开始：** 运行 `samemind handoff`（或 MCP `memory_handoff`）以获取工作状态 - 活动任务、最新决定、生效计划 - 以便新会话在无需重新解释的情况下继续。在 `/compact` 之前，请先将 Decision/Session/Task 刷新到 inbox；参见 [docs/compaction-recipe.md](docs/compaction-recipe.md)。 <details> <summary>从检出（开发模式）开始</summary> ```sh node tools/okf-query.mjs validate # 这个空启动包 OKF_ROOT=demo node tools/okf-query.mjs validate # 虚构的 Nova 演示 node tools/okf-query.mjs list node tools/okf-query.mjs type Project node tools/okf-query.mjs links # 类型关系（演示）：谁在 Acme Labs 工作？ OKF_ROOT=demo node tools/okf-query.mjs rel works_at acme-labs --inbound OKF_ROOT=demo node tools/okf-query.mjs rel depends_on projects/atlas # 回忆 - 开箱即用，零依赖（本地 BM25 超过标题/描述/标签/正文） node tools/okf-recall.mjs "Nova 如何处理检索" -k 5 # 自动：除非存在索引，否则使用 BM25 node tools/okf-recall.mjs "检索" --mode bm25 # 强制本地 BM25，无网络 # 语义回忆是可选的：指向任何 OpenAI 兼容的 /v1/embeddings 服务器 export OKF_EMBED_URL=http://127.0.0.1:8000/v1/embeddings # LM Studio / Ollama / OpenAI / 本地 export OKF_EMBED_MODEL=bge-m3 # 可选 export OKF_EMBED_KEY=sk-... # 可选（授权：Bearer） node tools/okf-recall.mjs index # 构建本地语义索引一次 node tools/okf-recall.mjs "Nova 如何处理检索" -k 5 # 自动 → 现在是语义的 # 人类可读的搜索（语义可用时，BM25 备用） node tools/gde.mjs "我在哪里写了关于上下文预算的内容" ``` </details> ## 格式 OKF 形状的 markdown 包： | 路径 | 角色 | |------|------| | `concepts/` | 想法、规则、身份（`Concept`、`EngineRule`、`Identity`、…） | | `entities/` | 人物和组织（`User`、`Entity`） | | `projects/` | 计划（`Project`） | | `inbox/` | 原始笔记，等待整理 - 默认情况下从图中排除（`validate`/`list`/`links`/`rel`/`get` 看不到）；--include-inbox 可选 | | `secret/` | 敏感节点（gitignored；--include-secret） | | `mirror/` | 每个引擎的实时内存镜像（gitignored；--include-mirror） | | `index.md` | 图的导航地图 | | `log.md` | 只追加的更改时间线 | 每个节点都有 YAML frontmatter： ```yaml --- type: Concept title: … description: … visibility: internal # public | internal | secret | mirror tags: [] timestamp: 2026-07-10T00:00:00Z source: … relations: # 可选的 SameMind 扩展（类型图边） works_at: /entities/acme-labs.md depends_on: [/projects/atlas.md, /concepts/retrieval-strategy.md] supersedes: /concepts/old-idea.md # 可选 - 内存卫生，见下文 importance: 3 # 可选 - 1..5，默认 3（中立） --- ``` 参见 `demo/` 了解完整的虚构示例（代理 **Nova**，所有者 **Alex Doe**，三个引擎规则，两个项目，链接的概念）。 **过时与当前不是自动的** - 六个月前的事实和今天的事实，除非您另有说明，否则排名相同。`supersedes`、`samemind forget`、`importance` 和温和的时间衰减在不删除历史记录的情况下修复了这一点；参见 [docs/memory-hygiene.md](docs/memory-hygiene.md)。 ## 关系 Frontmatter 中的类型边（`relations`）是 SameMind 配置文件扩展，基于 OKF v0.1。边类型是开放的 - 没有固定的词汇。值是包绝对路径（`/entities/…md`）或它们的列表；解析器始终规范化为数组。 ```sh # 出站：Alex 依赖于什么/在哪工作？ OKF_ROOT=demo node tools/okf-query.mjs rel works_at entities/alex-doe # 入站：谁在 Acme Labs 工作？ OKF_ROOT=demo node tools/okf-query.mjs rel works_at acme-labs --inbound ``` `links` 计算关系边和 markdown 链接；`validate` 将损坏的关系目标报告为 **警告**（路径丢失）而不失败一致性类型检查。 ## 身份层 该项目存在的特性：一个代理 **知道自己、它的所有者和它在当前引擎上的角色** - 无需重新解释。三种概念类型（`Identity`、`User`、`EngineRule` - 参见 [docs/identity-layer.md](docs/identity-layer.md)）拥有声音/价值观/边界，所有者偏好/硬规则和每个引擎的角色，都在纯 OKF markdown 中。`samemind init` 为它们搭建了骨架（`concepts/_identity-template.md`、`entities/_user-template.md`、`concepts/_engine-rule-template.md`）；`demo/` 中有一个填充的示例（代理 Nova，所有者 Alex Doe，三个引擎）。 `samemind brief` 将这三个压缩成一个预算 bounded 的 markdown 块，并可以直接将其注入引擎的指令文件中，因此从会话的第一个令牌开始就生效 - 无需检索步骤： ```sh npx samemind brief --engine claude-code # 打印到 stdout npx samemind brief --engine claude-code --inject ./CLAUDE.md # 幂等插入/替换 ``` 缩写的示例，对演示包运行： ``` <!-- samemind:brief:start --> # 简介 - Nova Nova 是拥有这个包的代理。相同的身份，不同的引擎... ## 边界（硬 - 永远不会被引擎或样式覆盖） - 永远不会在没有明确“删除”的情况下删除文件或数据。 - 外部操作（发送、发布、推送、消息某人）需要确认。 ... ## 所有者 - Alex Doe Nova 的所有者和人类，最终服务于这个包。 - 讨厌：谎言、波动性、被忽略。在 AI 中尤其如此：停滞和不回答。 ## 引擎：claude-code 在这个引擎上，Nova 进行终端开发：读取、编辑、运行、验证 - 直接。 - 没有明确的确认，不执行不可逆操作（删除、推送）。 <!-- samemind:brief:end --> ``` `--inject <file>` 仅替换两个标记注释之间的内容 - 外部文本永远不会被触及，两次运行它是一个空操作。优先级在 `--budget` 下（默认 ~1500 个令牌）：边界/所有者规则/引擎角色优先，接下来是声音，然后是其他内容，修剪以适应 ±10%（标记为 `…truncated`）而不是整个被丢弃 - 层 0 永远不会被修剪。传递 `--exclude-source <id>` 以省略由该源作者的概念（抗回声）。 ## 看板 工作纪律层（计划/任务/决定/会话 - 参见 [docs/work-discipline.md](docs/work-discipline.md)）上的看板，以及知识循环 `💡 想法` 部分（参见下面的“知识飞轮”），以及一个 **🔥 打开的失败** 部分，由 [事件账本](docs/event-ledger.md) 提供：什么正在排队，什么正在移动，什么 **阻塞**（以及阻塞了多久 - 阻塞超过 7 天的会被标记为 `aging`），什么失败了尚未解决，什么刚刚落地，什么最近达成，什么候选想法正在孵化。纯 markdown - 在终端中读取，在 GitHub 上渲染。 `--write` 原子刷新 `DASHBOARD.md` 在包根目录（一个提交的工件；`samemind init` 播种一个占位符）；`--project` 将四个任务列范围限定为一个项目（计划/想法/最近/会话保持投资组合范围）。 ```sh npx samemind board # 将看板打印到 stdout npx samemind board --write # 刷新 DASHBOARD.md（幂等 - 在钩子/ cron 中安全） npx samemind board --project /projects/lumen.md # 仅 Lumen 的任务 ``` 缩写的示例，对演示包运行： ``` # 仪表盘 ## 🔧 进行中（1） - **[交付 Lumen 反向链接编辑器](/projects/task-lumen-backlinks.md)** - 落地双向反向链接编辑器... ## 🔴 阻塞（1） - **[将检索策略连接到 Atlas 语料库](/projects/task-atlas-retrieval.md)** - 连接 Nova 的检索... - ⛔ 语料库摄入暂停 - 等待 Alex 确认源许可列表... - ⏳ 0d ## 📋 计划（1） - **[Lumen 多设备同步](/projects/plan-lumen-sync.md)** · 同意 - 同意计划以交付端到端同步... ### 最近的会话（1） - [Lumen 同步启动（2026-07-09）](/concepts/session-2026-07-09-lumen-sync.md) · 2026-07-09 - 工作会话，同意同步计划... ``` ## 知识飞轮 想法死在某人的脑海中，而不是在包中。三种额外的概念类型 - `Analysis`、`Research`、`Idea`（参见 [docs/knowledge-cycle.md](docs/knowledge-cycle.md)）- 使循环 **Analysis → Research → Idea → Plan** 在图中可见，而不是在聊天记录中。`Analysis` 注意到观察到的事实中的模式，并通知一个 `Idea`；`Idea` 有时需要更深入的挖掘 - 一个 `Research` 节点由 `Analysis` **spawn**，它也通知相同的 `Idea`；`Idea` 成熟（`spark → incubating`）并带有代理附加的 `## Reflections`，直到它被 `adopted`（导致 `Plan`）或 `rejected`（有原因，因此不会在下周再次提出）。任何引擎上的任何代理都可以发现其领域内的未成熟 `Idea` 并做出反应 - 将其自己的 inbox 而不是阅读过去（完整协议：[docs/memory-protocol.md](docs/memory-protocol.md)）。`samemind board` 显示它：孵化的想法首先，然后是火花，被采纳的想法指向它们成为的计划，被拒绝的想法离开看板但不被删除。参见 `demo/` 了解链接的工作示例（镜像陈旧性 → 同步机制研究 → cron-sync-adapters 想法）。 ## 工具列表 | 命令 | 用途 | |------|---------| | `samemind init [目录]` | 初始化一个新软件包（仅限空目录；`--demo` 添加 Nova 示例） | | `samemind query <命令>` | 结构化查询：`list`、`type`、`tag`、`get`、`links`、`rel`、`validate` | | `samemind recall "<查询>"` | 搜索：`--mode bm25\|semantic\|auto` （默认 `auto`）。BM25 无依赖运行；语义搜索需要 `OKF_EMBED_URL` + `index`。`--exclude-source <id>` 排除引擎自身的概念（防止回声）。 | | `samemind gde "<查询>"` | 人性化搜索：存在索引时使用语义搜索，否则回落到 BM25。`--exclude-source <id>` 支持。 | | `samemind brief [--engine <id>] [--budget <n>] [--inject <文件>] [--exclude-source <id>]` | 简洁的身份 + 用户 + 引擎规则摘要 — 参见 [身份层](#identity-layer) | | `samemind handoff [--project <路径>] [--days N] [--html [--out <文件>]]` | 工作状态摘要（任务/计划/决策/会话）— 参见 [docs/compaction-recipe.md](docs/compaction-recipe.md)；`--html` → 自包含页面（无 CDN/JS，浅色 + 深色） | | `samemind forget <id>` | 软弃用概念（frontmatter 中 `deprecated: true`）— 永远不会删除文件。参见 [内存卫生](docs/memory-hygiene.md) | | `samemind board [--write] [--project <路径>] [--html [--out <文件>]]` | 工作的 Kanban 看板（待办/进行中/完成/阻塞 + 老化，计划，近期）+ 知识周期创意 — `--write` → `DASHBOARD.md`，`--html` → 自包含页面，带 SVG 看板图表 — 参见 [看板](#board) | | `samemind install --agent <id>\|all [--target <目录>]` | 将简洁摘要 + 协议写入引擎的指令文件（idempotent）— 参见 [兼容性](#compatibility)，[docs/adapters.md](docs/adapters.md)。未知 id 需要 `--file <路径>` 进行通用安装。 | | `samemind export <目录> [--visibility public\|internal] [--dry-run] [--to-gbrain]` | 可分享的 OKF 软件包（剥离 `secret/`/`mirror/`/`inbox/`）；gbrain 页面映射 — 参见 [docs/interop.md](docs/interop.md) | | `samemind import <目录> [--into inbox\|concepts]` | 接受外来 OKF 软件包（默认 → 精心策划的 `inbox/import-<日期>.md`；永远不会覆盖）— 参见 [docs/interop.md](docs/interop.md) | | `samemind capture --engine <id> [--source <路径>] [--since <时间戳>] [--dry-run]` | 只读捕获实时引擎会话存储（Claude Code JSONL 转录，任意 markdown 日记目录）到精炼的 `inbox/<engine>.md` — 参见 [docs/session-capture.md](docs/session-capture.md) | | `samemind ledger append\|status\|read` | 仅追加事件账本（`ledger/events.jsonl`）：细粒度 "谁做了什么步骤，何时"， 🔥 打开失败直到解决 — 补充（永远不会替换）`Task.status` — 参见 [docs/event-ledger.md](docs/event-ledger.md) | | `samemind serve` | MCP 标准输入/输出服务器：`memory_search/get/list/write_inbox/handoff/health/ledger_append/ledger_status` — 参见 [MCP](#mcp) | | `tools/consolidate.mjs` | 间隙映射：inbox/mirror → 提升到正典的候选者，加上同类型 "矛盾" 部分（仅开发模式，运行时从检出） | `query`/`recall`/`gde`/`brief`/`board`/`handoff`/`forget`/`install`/`export`/`import`/`capture`/`ledger`/`serve` 如果设置了 `OKF_ROOT`，则针对该目录运行；否则针对当前目录 — 因此它们在您自己的软件包上运行，而不是 samemind 软件包本身。 ### HTML 投影（`--html`） `board` 和 `handoff` 默认情况下是 markdown（git 原生，可终端读取）；`--html` 将 **相同** 的数据模型（`buildBoardModel`/`buildHandoffModel` — 唯一的真实来源，无需重新解析）渲染为自包含页面：内联 CSS，浅色 + 深色主题通过 `prefers-color-scheme` 实现，无 JavaScript，无外部资源，以及一个小 SVG 图表（看板条形图 + 创意条带用于看板，决策时间线用于交接）。正典仍然是 markdown — HTML 始终是生成的表示，永远不是存储（参见 [gbrain/concepts/idea-html-projections.md](https://github.com/alexgrebeshok-coder/gbrain)）。 ```sh npx samemind board --html --out DASHBOARD.html # 编写自包含的看板页面 npx samemind handoff --html | pbcopy # 将交接页面输送到任何地方 ``` ### Recall 模式和环境变量 `okf-recall.mjs "<查询>"` 通过 `--mode` 选择模式： - **`auto`** （默认）— 如果存在本地索引且嵌入端点响应，则使用语义搜索；否则降级为本地 BM25 并向 stderr 打印一行通知。永远不会在没有端点的情况下崩溃。 - **`bm25`** — 始终使用本地关键词/BM25 搜索 `title` / `description` / `tags` / 正文。无需网络，无依赖。 - **`semantic`** — 严格使用语义搜索；如果索引或端点丢失，则会报错（无静默回落）。 语义搜索使用任何兼容 OpenAI 的 `/v1/embeddings` 服务器： | 环境变量 | 用途 | |-----|---------| | `OKF_EMBED_URL` | 端点 URL（Ollama、LM Studio、OpenAI、本地服务器等） | | `OKF_EMBED_MODEL` | 请求正文中发送的模型名称 | | `OKF_EMBED_KEY` | 可选的 `Authorization: Bearer …` | | `OKF_EMBED_DIM` | 可选；如果设置，则验证响应向量长度 | 在设置端点后一次性构建索引：`node tools/okf-recall.mjs index`。 ## MCP `samemind serve` 运行一个标准输入/输出 MCP 服务器（JSON-RPC 2.0，每行分隔，无 SDK 依赖），将软件包暴露给任何支持 MCP 的代理 — Claude Code、Codex、opencode 或您自己的客户端。 ```sh npx samemind serve # OKF_ROOT（或 cwd）= 软件包根目录；标准输入/标准输出 = 协议 ``` 将其连接为项目或用户范围的 MCP 服务器： ```sh claude mcp add samemind -- npx samemind serve codex mcp add samemind -- npx samemind serve ``` 将 `OKF_ROOT` 指向要服务的软件包（默认为 unset 时的当前目录 — 与 `query`/`recall`/`gde` 相同的规则）。 ### 工具 | 工具 | 用途 | |------|---------| | `memory_search` | `{query, k?, mode?, exclude_source?}` → 回忆（如果存在索引且回答，则语义搜索；否则 BM25）。返回 `{id, type, title, score, snippet}[]`。`exclude_source` (`[a-z0-9-]`) 排除引擎自身的概念 — 防回声。 | | `memory_get` | `{id}` → 一个概念，完整的 frontmatter + 正文。 | | `memory_list` | `{type?, tag?}` → 概念 ID/标题，可选过滤。 | | `memory_write_inbox` | `{content, title?}` → 追加到 `inbox/<agent>.md` — **唯一** 可写路径。 | | `memory_handoff` | `{project?, days?}` → 工作状态 markdown（活跃任务，决策，计划，最后会话，开放问题）。 | | `memory_health` | `{}` → 软件包根目录，概念计数，活跃搜索模式，服务器版本。 | | `memory_ledger_append` | `{topic, phase, status?, action, artifact?, ref?}` → 将一个事件追加到 `ledger/events.jsonl`。`actor` 来自 `SAMEMIND_AGENT`（默认 `mcp`）— 与 `memory_write_inbox` 相同的合约。参见 [docs/event-ledger.md](docs/event-ledger.md)。 | | `memory_ledger_status` | `{}` → 只读 `{topics, openFailures}` 事件账本摘要（永远不会修改它）。 | ### 安全 - **`visibility: secret` 永远不会** 被任何工具返回 — 无标志，无参数，无例外。秘密概念在工具看到它们之前会被排除；`tools/secret-isolation.test.mjs` 覆盖的范围（查询 / 回忆 / gde / MCP / 简洁摘要）。 - **路径安全**：传递给 `memory_get` 的任何 `id` 都会被规范化，并且必须严格解析到软件包根目录内；拒绝 `..`/绝对路径逃逸。 - **写入路径固定**：`memory_write_inbox` 只能追加到 `inbox/<agent>.md`，而 `memory_ledger_append` 只能追加到 `ledger/events.jsonl`。代理/执行者名称来自 `SAMEMIND_AGENT`（默认 `mcp`），并被净化为 `[a-z0-9-]`。每次写入都是原子的（临时文件 + 重命名），并且只追加 — 现有条目永远不会被重写。 - **提示注入内容被隔离，而不是丢弃。** 看起来像指令覆盖尝试的文本（`ignore previous instructions`、`<system>`、`tool_use`、“执行此命令”等）仍然被写入 — 包装在带 `quarantine: true` 标记的围栏 ` ```quarantine ` 块中，用于 `memory_write_inbox`，或在事件本身上记录为 `quarantine: true`，用于 `memory_ledger_append` — 因此内存永远不会被静默丢失，但下游读取器不会盲目执行它。 ### 并发 **多个代理同时写入同一个软件包是安全的。** 实际上，繁忙的舰队会并发访问的三个修改-读取-写入路径 — `memory_ledger_append`（`ledger/events.jsonl`）、`memory_write_inbox` / `samemind capture`（`inbox/<agent>.md`）和 `samemind forget`（概念的 frontmatter）— 每个路径都由 `lib/file-lock.mjs` 守护，这是一个基于 mkdir 的零依赖互斥锁，针对目标文件路径进行密钥绑定（`mkdir` 在我们运行的所有平台上都是原子独占创建，无需 npm lockfile 包）。如果崩溃的进程留下了锁，则会在其 PID 已死时立即恢复，或者 30 秒后如果它只是旧的 — 因此一个废弃的写入器永远不会让软件包对其他人不可用；等待者会以有上限的指数重试并在 10 秒后放弃，而不是永远挂起。结合现有的原子写入（临时文件 + 重命名 — `lib/atomic-write.mjs`），这解决了并发写入问题的两个方面：不会出现损坏/损坏的文件（以前已经成立），并且两个写入者竞争时不会静默丢失更新（这是实际的差距 — 参见 `tools/concurrency.test.mjs`，它会生成真正的 OS 进程，而不仅仅是异步承诺，因为丢失更新的竞争对单个 Node 进程的协作调度器不可见）。 ## 兼容性 **零级回落，适用于以下所有内容：** 软件包是磁盘上的纯 markdown。任何具有 shell 的代理都可以仅使用 `cat`/`grep`/`find` 读取它，而无需适配器 — MCP 和 `samemind install` 是基于已经适用于任何具有文件系统的东西的格式的便利功能。 `samemind install --agent <id>` 将身份简洁摘要 + 内存协议直接连接到每个引擎读取的指令文件中，而 `samemind serve` 将软件包暴露为 MCP 服务器，以便所有支持 MCP 的功能。已检查，当前截至 2026 年 7 月 10 日 — 完整的命令和注释在 [docs/adapters.md](docs/adapters.md) 中： - 任何 OpenAI 兼容的嵌入服务器用于回忆（LM Studio、Ollama、…） - **Google OKF v0.1** 线形结构 — `samemind export` / `import` 交换可分享的软件包（`okf_version: "0.1"`）；`--to-gbrain` 将概念映射到 [garrytan/gbrain](https://github.com/garrytan/gbrain) 页面 — 参见 [docs/interop.md](docs/interop.md) | 引擎 | 指令文件 | MCP | |---|---|---| | Claude Code | `CLAUDE.md` | ✅ `claude mcp add` | | Cursor | `AGENTS.md` + `.cursor/rules/` | ✅ `.cursor/mcp.json` | | GitHub Copilot（代理模式） | `.github/copilot-instructions.md` + `AGENTS.md` | ✅ VS Code `mcp.json` | | Codex CLI | `AGENTS.md` | ✅ `codex mcp add` | | Gemini CLI | `GEMINI.md` | ✅ `settings.json` | | opencode | `AGENTS.md` | ✅ `opencode.json` | | Cline | `.clinerules` | ✅ `cline_mcp_settings.json` | | Roo Code | `.roo/rules/` | ✅ `.roo/mcp.json` | | Windsurf | `.windsurf/rules/` + `AGENTS.md` | ✅ `mcp_config.json` | | Goose | `.goosehints` | ✅ 原生扩展 | | Kiro | `.kiro/steering/` | ✅ `kiro-cli mcp add` | | Antigravity | `AGENTS.md` / `GEMINI.md` | ✅ IDE 配置 / Gemini API | | Aider | — (`--read` 手动读取片段） | ⚠️ 社区仅限，非官方 | | OpenClaw / Hermes | — (自己的 `MEMORY.md`/`USER.md`，引导笔记) | ✅ 与任何客户端相同的 MCP 形状 | `samemind install --list` 从代码中实时打印此表。 `--agent all` 刷新已经存在于项目中的文件，而不会盲目创建所有十二个。 `INSTALL_FOR_AGENTS.md` 是代理运行针对其自身项目的逐步自我安装协议，无需人类输入。 将引擎的实时 **实时** 会话存储拉入软件包是 `samemind capture --engine <id>`（参见 [docs/session-capture.md](docs/session-capture.md)）：只读，蒸馏到 `inbox/<engine>.md` — 与此软件包中使用的所有其他写入路径相同，而不是直接写入 `mirror/`。完整的始终同步的 `mirror/`（自动更新 zeroconf，无需调解步骤）仍然是特定于项目的粘合剂，与 `gbrain/adapters/import-*.mjs` 脚本此框架从中推广。 ## samemind vs. gbrain（Garry Tan）— 何时使用哪个 [gbrain](https://github.com/garrytan/gbrain) 是一个真正的成熟产品，擅长解决不同的工作：一个 24/7 的守护进程，将您的整个数字生活（电子邮件、语音调用、推文、会议）摄入 Postgres/pgvector，自动编织实体图，并返回带有间隙分析的合成引用答案（`gbrain think`）而不是命中列表。如果您想要一个始终开启的大脑用于某个人或公司，拥有 10 万+ 页面，它是一个强有力的选择 — 阅读它的 README。 samemind 旨在针对一个更狭窄、相邻的目标：**适用于您的编码代理的便携式身份 + 内存层**，无需运行任何东西，也无需支付费用。 | | samemind | gbrain | |---|---|---| | 基础设施 | 无 — markdown + git | Postgres/pgvector（或 PGLite）+ 嵌入提供者 + 24/7 “梦周期”守护进程 | | 设置 | `npx samemind init` — 几秒钟 | ~30 分钟引导安装、API 密钥、数据库启动 | | 答案形状 | 您（或您的代理）阅读排名的命中并合成，带有引用间隙 | `gbrain think` 返回已合成的引用答案 + 间隙分析 | | 扩展目标 | 手工策划 — 数百到几千个概念 | 构建用于连续摄入 100K+ 页 | | 实体/图 | 您编写类型化的 `relations:` 手动 | 自动提取实体图（零 LLM 调用）+ 每晚 cron 上的 LLM 驱动的丰富 | | 查询它 | 纯 markdown — `cat`/`grep`/`find` 适用于零工具 | git 仓库是源代码的真实来源，但查询需要 Postgres/PGLite 引擎 + 嵌入运行 | 使用 samemind 如果您想要一个内存随您访问的每个编码引擎而移动，无需运行任何东西，也无需支付费用。 使用 gbrain 如果您想要一个始终开启的大脑，摄入您的整个生活或团队的，并返回书面答案，并且您愿意运行数据库并支付嵌入式/重排名获取它。 这里没有任何内容是 gbrain的结论。 没有任何内容是对 gbrain 的批评 — 不同的范围，不同的材料清单。 **vs. SQLite/vector-DB 内存工具** 用于编码代理（Memorix，agentmemory，claude-mem 等）：您的内存是 git 中的 markdown 文件 — 而不是我们的数据库。没有二进制存储需要导出，没有专有模式需要迁移，`git log` 是审计轨迹。 ## 测试和微基准 ```sh node --test tools/*.test.mjs # CI 矩阵：Node 20 + 22 OKF_ROOT=demo node tools/bench-recall.mjs # BM25 vs naive grep on demo goldens ``` 方法和当前命中率/命中率 3 的数字：[docs/benchmark.md](docs/benchmark.md)。仅限微型语料库 — 而不是公共 IR 基准。 贡献开发设置、约定和格式规范指针： [`CONTRIBUTING.md`](CONTRIBUTING.md). ## 许可 MIT © 2026 Aleksandr Grebeshok