Memknow 把飞书消息、Claude Code CLI、本地 workspace 和记忆检索层接成了一条稳定运行链路。 这页不是安装说明，而是一堂系统解剖课：从一条消息开始，看它如何穿过会话队列、上下文增强、Claude 执行器，再回到飞书卡片。
Memknow 不替代 Claude Code。它负责把飞书、会话管理、调度、记忆和本地工作区接起来，让 Claude Code 在一个可持续运行的系统里工作。
如果你只能记住一段内容，就记住这一章。Memknow 的价值首先不在“功能点”，而在它把一次飞书消息可靠地推进到了一个真实的本地 Agent 工作流里。
从 Feishu 到 Claude CLI，再回到卡片响应输入输出边界。接 WS，发卡片，不关心记忆细节。
对话编排核心。管理 Worker、session 生命周期、上下文注入。
把 prompt 和工作目录真正送给 Claude Code CLI。
存会话、消息、摘要、schedule 和日志。
负责 bot 住的地方：模板初始化、skills、memory、sessions。
Memknow 没有把所有职责堆进一个“智能 Agent 服务”里，而是把输入输出、会话编排、Claude 执行、工作区初始化拆清楚。这样调试和演进都更稳。
Feishu User
-> WebSocket Event
-> feishu.Receiver
-> session.Manager.Dispatch()
-> session.Worker
-> claude.Executor
-> feishu.Sender
-> Feishu Card / Text Reply很多“聊天机器人”只是在回调里拼一段 prompt 然后调用模型 API。Memknow 做得更深一层：它把每次消息都导向一个真实可持续的本地工作区，让 bot 具备编辑文件、执行命令、积累记忆和被系统定时唤醒的条件。
在 Memknow 里，bot 不是一组数据库字段，而是一个真正的目录树。你可以把它理解成“AI 的长期住处”：人格、记忆、技能和会话现场都放在这里。
app 级隔离，而不是 prompt 级临时拼装workspaces/<app-id>/
├── SOUL.md bot 的长期行为设定
├── IDENTITY.md 身份描述
├── USER.md 用户关系与约束
├── MEMORY.md 记忆使用规则
├── HEARTBEAT.md 心跳检查清单
├── skills/ 按需读取的能力说明
├── memory/ 长期知识沉淀
├── sessions/ 运行期会话现场
├── bin/web-search 本地统一搜索入口
└── .search.json 运行期搜索配置`internal/workspace/template/` 里的中英文模板会被嵌入到二进制里。新 workspace 初始化时，如果缺文件，就从模板生成默认内容。这意味着项目层面对“一个 bot 初始长什么样”有统一、可版本化的控制。
`HEARTBEAT.md` 是心跳运行器读取的工作清单，不是任务 YAML 模板。Memknow 明确把 heartbeat 设计成系统内建调度，而不是依赖 agent 自己写配置文件来伪造主动性。
这部分决定系统稳不稳。Memknow 没有让同一聊天上下文里的消息并发地撞进同一个 Claude session，而是用 `channel_key` 维持稳定的串行执行面。
稳定的会话键，比“谁先抢到 goroutine”更重要getOrCreateSession()
moveAttachments()
DB record
Retrieve()
Execute()
Claude session 本身就有上下文状态。如果同一会话边界里的消息并发进来，文件修改、上下文注入、回传卡片顺序都可能乱掉。Memknow 把并发留给不同 `channel_key`，把顺序保证留给同一个 `channel_key`。
channel_key
-> dedicated worker queue
-> active Memknow session_id
-> claude_session_id (--resume)
same channel_key: serial
different channel_key: concurrent“长期记忆”最容易被说虚。Memknow 这里做得相对务实：保留 Claude `--resume` 的连续上下文能力，同时在 session 维度做摘要归档和后续检索，把跨 session 的连续性补上。
resume 保留短中期上下文，summary + retrieve 补长期连续性直接把所有历史消息拼进 prompt，短期内看似简单，长期一定爆。Memknow 选择的是更像信息检索系统的做法：哪些历史值得带回来，由摘要与检索层决定，而不是由上下文窗口硬撑。
archived session
-> summarize
-> store in session_summaries
-> next user message arrives
-> retrieve relevant summaries
-> build ContextPayload
-> inject into prompt
-> execute in new or current session它依赖的是持续积累文件、结构化摘要和可检索历史，而不是假设模型自己永远记得一切。也正因为如此，它更接近一个真实可维护的 Agent 记忆层。
Memknow 不只支持“收到消息再回复”。它内建了两种主动触发机制，但两者职责完全不同：`heartbeat` 是系统维护循环，`schedule` 是业务提醒与计划执行。
主动性来自框架内建调度，不来自 prompt 里的自我幻想这是系统级自检和维护循环，由 `internal/heartbeat` 按 `config.yaml` 配置周期触发。它会读取 workspace 里的 `HEARTBEAT.md`，让 bot 定期检查自己该整理什么、更新什么、反思什么。
这是业务侧的自然语言调度能力，由 `internal/schedule` 负责。用户可以通过“每小时提醒我喝水”“明天 10 点提醒我回顾 PR”这类语言创建、查看、修改、删除定时任务。任务实体存数据库，由调度器直接执行。
heartbeat:
config.yaml -> heartbeat service
-> open workspace HEARTBEAT.md
-> run maintenance turn
schedule:
user natural language
-> schedule intent parser
-> schedules table
-> scheduler executes at trigger time不要把 heartbeat 实现成生成任务 YAML，也不要把 schedule 的创建依赖于 agent 去写 YAML 文件。主动执行必须是框架层确定的能力，而不是 prompt 层约定俗成的“假功能”。
理解 Memknow，不只要知道它能做什么，也要知道它刻意没有做什么。它是一个偏单机、偏本地、偏工作区编排的 Agent 平台，而不是一个大一统云原生控制平面。
边界讲清楚，场景判断才不会跑偏适合把一个飞书 bot 变成真正有 workspace、有文件系统、有长期记忆沉淀能力的数字同事。尤其适合私有部署、企业内网、工具链已经围绕 Claude Code 展开的场景。
它不是多租户云平台，不是无状态函数调用框架，也不是“接一下大模型 API 就自动拥有长期记忆”。它依赖本机 Claude Code、文件系统和本地持久化。
部署简单、状态清晰、调试路径短。SQLite WAL、workspace 目录、Claude CLI 都在一台机器上，很多复杂度被直接压平了。
前提是机器已经安装并登录 Claude Code；某些能力天然绑定本地环境；横向扩展、多机共享状态、统一集中调度不是当前设计重点。
它是一个把飞书接入、会话调度、本地工作区、Claude Code CLI、长期记忆和系统级主动执行接到一起的编排层。它让 bot 从“会回复消息的接口”升级成“在一个持续存在的目录里工作和成长的 agent”。
建议顺序是：先读 `README.md` 了解整体能力，再读 `docs/design.md` 看实现结构，最后回到代码中的 `internal/session`、`internal/claude`、`internal/workspace` 三个目录，把这页里的心智模型和实际实现一一对照起来。