尧图网页设计 
claude-mem 工作原理深度解析跨会话记忆的采集、压缩与自动注入机制【免费下载链接】claude-memPersistent Context Across Sessions for Every Agent – Captures everything your agent does during sessions, compresses it with AI, and injects relevant context back into future sessions. Works with Claude Code, OpenClaw, Codex, Gemini, Hermes, Copilot, OpenCode More项目地址: https://gitcode.com/GitHub_Trending/cl/claude-mem本文档是 claude-mem 的官方入门说明对应仓库中的 onboarding-explainer.md 与 how-it-works 技能说明面向刚接触该项目的开发者。围绕这份说明本文将系统拆解 claude-mem 的三大核心机制——它采集什么、在什么时机生效、数据存储在哪里——并结合仓库源码逐层展开帮助你真正理解跨会话持久上下文这条流水线的工作原理以及如何安全地使用、卸载和按需深度加载记忆。核心机制一从 Read / Edit / Bash 到压缩观察记录Observationclaude-mem 的核心循环可以用一句话概括每一次 Read、Edit、Bash都会被转化为一条压缩后的 observation观察记录。会话结束时这些 observation 会被进一步总结summary在未来的会话中与当前工作相关的 observation 会被自动注入到提示词prompt中使下一个会话天然拥有上一个会话的上下文——无需重新解释代码库也无需重新发现已经做过的决策。这段话描述的链路在源码中有着清晰的落点。观察记录的数据结构定义在src/services/context/types.ts而真正把零散的观察记录 会话总结组装成一段可注入文本的逻辑位于 ContextBuilder.ts 中的buildContextOutput先调用queryObservationsMulti/querySummariesMulti从 SQLite 读取当前项目相关的 observation 与会话总结再用calculateTokenEconomics计算本次注入的 token 经济账对应结构体ContextInjectStats中的tokens_injected与tokens_saved_vs_naive见 ContextBuilder.ts随后依次渲染头部header、时间线timeline、最近的会话总结、之前会话的关键消息最后收尾footer拼成完整的上下文块。也就是说未来提示词自动带上过去上下文这一行为最终落地为generateContextWithStats生成的文本被 hook 在会话开始时写入模型上下文。它依赖的是本机 SQLite 中真实存在的、按项目隔离的 observation 数据而不是任何云端存储。observation 的类型与检索为了让自动注入只挑选相关的过去工作系统对 observation 做了类型标签化管理。可检索的类型包括decision决策、bugfix缺陷修复、feature功能、refactor重构、discovery发现与change变更等。这一事实可从多个入口印证ContextInjectStats中的类型分桶统计STAT_TYPE_BUCKETS new Set([bugfix, discovery, decision, refactor])见 ContextBuilder.tsmem-search 技能 中的obs_type过滤参数支持以逗号分隔传入bugfix, feature, decision, discovery, change。核心机制二何时生效——第二次会话即获得自动记忆注入记忆注入并非从第一个会话就开始而是在你进入某个项目的第二个会话时启动。其逻辑设计是首个会话冷启动在一个全新项目中的第一个会话负责播种记忆——即采集并沉淀 observation第二个及之后的会话系统检索此前沉淀的相关记忆把相关部分自动注入当前提示词实现跨会话连续可选的深度预载如果希望在单次会话中把整个代码库一次性灌入记忆可以运行/learn-codebase耗时约 5 分钟可选操作。关于/learn-codebase的语义可参考 learn-codebase 技能它要求 Agent 系统化、逐文件、完整地通读仓库中的每一个源文件对超大文件配合 Read 工具的offset/limit分页读取从而建立对代码库的深度理解作为后续开发的基础。这是一种用一次性 token 开销换取项目生命周期内认知缓存与更少试错成本的做法。值得注意的是本机 worker 进程的启动时机与该机制配合worker 由 hook、viewer、MCP 搜索以及后台 observation 生成共同使用端口默认取CLAUDE_MEM_WORKER_PORT未设置时为37700 (uid % 100)主机默认127.0.0.1详见 worker README。注入后的检索产物通过 worker 的/api/context/*、/api/search、/api/timeline等接口对外提供对应src/services/worker/http/routes/下的ContextRoutes与SearchRoutes。注入内容的可配置性为了让注入既够用又不淹没模型上下文ContextConfig由ContextConfigLoader加载控制着每次注入的规模与深度核心维度包括展示多少个会话总结sessionCount见buildContextOutput中summaries.slice(0, config.sessionCount)注入多少条完整 observationfullObservationCount对应getFullObservationIds时间线覆盖的历史深度等。而buildInjectStats中记录的tokens_injected与tokens_saved_vs_naive表明注入的并非过去所有原始记录而是经过 token 经济学裁剪后的压缩表示——这正是 onboarding 文档强调压缩后自动注入的源码级体现。核心机制三数据存放位置与隐私边界claude-mem 采用纯本地优先的存储模型所有数据都保留在当前机器的~/.claude-mem目录下除了调用你为压缩/总结环节配置的 AI 提供方Claude / OpenRouter / Gemini之外没有任何数据离开你的机器。目录内到底有什么paths.ts 的路径定义让这份说明变得可验证、可感知。数据目录的解析逻辑为数据根目录默认~/.claude-mem源码中resolveDataDir()决定可通过环境变量覆盖claude-mem.dbSQLite 数据库主文件DB_PATH存放 observation、总结、prompt 等结构化记录logs日志目录LOGS_DIRsettings.json用户设置文件USER_SETTINGS_PATHobserver-sessions会话采集器的原始会话数据目录OBSERVER_SESSIONS_DIR。onboarding 文档提到的vector index向量索引对应 Chroma 相关能力——worker 暴露了/api/chroma/status接口用于查看 Chroma 集成状态见 worker README向量化检索服务于语义搜索semantic search。由于一切均在本机目录内使用与排查都围绕该目录展开。数据生命周期干净卸载由于所有数据SQLite、向量索引、日志、设置都集中在~/.claude-mem单一目录下卸载时即可整体清理。文档明确执行npx claude-mem uninstall会将这些数据干净地移除不留残余。这是本地优先设计带来的一个重要运维优势——数据归你所有去留由你决定。实战视角注入之后如何主动检索记忆自动注入是被动的——它只把相关的过去工作带进提示词。若你在会话中途想主动回忆我们上次是怎么解决这个问题的仓库还提供了配套的 mem-search 技能其三层工作流与本文档描述的存储模型完全一致都基于本地 SQLite 中的 observationSearch用search(query..., limit..., project...)拿回带 ID 的索引表每条约 50–100 tokenTimeline用timeline(anchor...或 query..., depth_before..., depth_after...)查看目标 observation 周围的上下文Fetch只对筛选出的 ID 调用get_observations(ids[...])取全文每条约 500–1000 token。该技能明确要求先过滤再取全文禁止不经筛选直接抓取完整细节理由是 10 倍的 token 节省先看廉价的索引与标题再决定哪些值得展开。这与自动注入环节的 token 经济学tokens_saved_vs_naive遵循同一设计哲学——压缩、筛选、按需展开。如果你的需求是把过去某类经验合成可对话的知识库则可以进一步使用 knowledge-agent 技能基于 observation 历史构建聚焦的语料corpus支持按project、types、concepts、files、dateStart/dateEnd等条件过滤构建后 prime 进一个 AI 会话再以问答形式与之对话。它正是 onboarding 说明中过去工作会沉淀为可复用资产这一理念的自然延伸。总结一条数据两种消费方式可以把 onboarding 说明浓缩为一张心智图阶段发生什么落地位置源码/目录采集Read / Edit / Bash 被压缩为 observationSQLiteclaude-mem.db写入链路总结会话结束时 observation 被总结ContextBuilder读取 summaries 渲染注入第二个会话起相关记忆自动进入提示词ContextBuilder.tsgenerateContextWithStats主动检索search → timeline → fetch 三层过滤mem-search 技能存储全量数据在本机~/.claude-mempaths.ts 中的DATA_DIR及子项卸载npx claude-mem uninstall干净移除~/.claude-mem整目录清理对使用者而言理解 claude-mem 只需抓住三点它把动作压缩成记忆observation在第二个会话开始自动回放injection并把这些记忆全部留在你自己的机器上~/.claude-mem。想快速验证这套机制最简单的方式是在一个新项目里完成两个连续会话第一个会话做真实的代码修改与决策第二个会话观察提示词中自动出现的上文摘要与 timeline——这正是无需重新解释代码库的最直观演示。【免费下载链接】claude-memPersistent Context Across Sessions for Every Agent – Captures everything your agent does during sessions, compresses it with AI, and injects relevant context back into future sessions. Works with Claude Code, OpenClaw, Codex, Gemini, Hermes, Copilot, OpenCode More项目地址: https://gitcode.com/GitHub_Trending/cl/claude-mem创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 claude-mem 工作原理深度解析：跨会话记忆的采集、压缩与自动注入机制
claude-mem 工作原理深度解析跨会话记忆的采集、压缩与自动注入机制【免费下载链接】claude-memPersistent Context Across Sessions for Every Agent – Captures everything your agent does during sessions, compresses it with AI, and injects relevant context back into future sessions. Works with Claude Code, OpenClaw, Codex, Gemini, Hermes, Copilot, OpenCode More项目地址: https://gitcode.com/GitHub_Trending/cl/claude-mem本文档是 claude-mem 的官方入门说明对应仓库中的 onboarding-explainer.md 与 how-it-works 技能说明面向刚接触该项目的开发者。围绕这份说明本文将系统拆解 claude-mem 的三大核心机制——它采集什么、在什么时机生效、数据存储在哪里——并结合仓库源码逐层展开帮助你真正理解跨会话持久上下文这条流水线的工作原理以及如何安全地使用、卸载和按需深度加载记忆。核心机制一从 Read / Edit / Bash 到压缩观察记录Observationclaude-mem 的核心循环可以用一句话概括每一次 Read、Edit、Bash都会被转化为一条压缩后的 observation观察记录。会话结束时这些 observation 会被进一步总结summary在未来的会话中与当前工作相关的 observation 会被自动注入到提示词prompt中使下一个会话天然拥有上一个会话的上下文——无需重新解释代码库也无需重新发现已经做过的决策。这段话描述的链路在源码中有着清晰的落点。观察记录的数据结构定义在src/services/context/types.ts而真正把零散的观察记录 会话总结组装成一段可注入文本的逻辑位于 ContextBuilder.ts 中的buildContextOutput先调用queryObservationsMulti/querySummariesMulti从 SQLite 读取当前项目相关的 observation 与会话总结再用calculateTokenEconomics计算本次注入的 token 经济账对应结构体ContextInjectStats中的tokens_injected与tokens_saved_vs_naive见 ContextBuilder.ts随后依次渲染头部header、时间线timeline、最近的会话总结、之前会话的关键消息最后收尾footer拼成完整的上下文块。也就是说未来提示词自动带上过去上下文这一行为最终落地为generateContextWithStats生成的文本被 hook 在会话开始时写入模型上下文。它依赖的是本机 SQLite 中真实存在的、按项目隔离的 observation 数据而不是任何云端存储。observation 的类型与检索为了让自动注入只挑选相关的过去工作系统对 observation 做了类型标签化管理。可检索的类型包括decision决策、bugfix缺陷修复、feature功能、refactor重构、discovery发现与change变更等。这一事实可从多个入口印证ContextInjectStats中的类型分桶统计STAT_TYPE_BUCKETS new Set([bugfix, discovery, decision, refactor])见 ContextBuilder.tsmem-search 技能 中的obs_type过滤参数支持以逗号分隔传入bugfix, feature, decision, discovery, change。核心机制二何时生效——第二次会话即获得自动记忆注入记忆注入并非从第一个会话就开始而是在你进入某个项目的第二个会话时启动。其逻辑设计是首个会话冷启动在一个全新项目中的第一个会话负责播种记忆——即采集并沉淀 observation第二个及之后的会话系统检索此前沉淀的相关记忆把相关部分自动注入当前提示词实现跨会话连续可选的深度预载如果希望在单次会话中把整个代码库一次性灌入记忆可以运行/learn-codebase耗时约 5 分钟可选操作。关于/learn-codebase的语义可参考 learn-codebase 技能它要求 Agent 系统化、逐文件、完整地通读仓库中的每一个源文件对超大文件配合 Read 工具的offset/limit分页读取从而建立对代码库的深度理解作为后续开发的基础。这是一种用一次性 token 开销换取项目生命周期内认知缓存与更少试错成本的做法。值得注意的是本机 worker 进程的启动时机与该机制配合worker 由 hook、viewer、MCP 搜索以及后台 observation 生成共同使用端口默认取CLAUDE_MEM_WORKER_PORT未设置时为37700 (uid % 100)主机默认127.0.0.1详见 worker README。注入后的检索产物通过 worker 的/api/context/*、/api/search、/api/timeline等接口对外提供对应src/services/worker/http/routes/下的ContextRoutes与SearchRoutes。注入内容的可配置性为了让注入既够用又不淹没模型上下文ContextConfig由ContextConfigLoader加载控制着每次注入的规模与深度核心维度包括展示多少个会话总结sessionCount见buildContextOutput中summaries.slice(0, config.sessionCount)注入多少条完整 observationfullObservationCount对应getFullObservationIds时间线覆盖的历史深度等。而buildInjectStats中记录的tokens_injected与tokens_saved_vs_naive表明注入的并非过去所有原始记录而是经过 token 经济学裁剪后的压缩表示——这正是 onboarding 文档强调压缩后自动注入的源码级体现。核心机制三数据存放位置与隐私边界claude-mem 采用纯本地优先的存储模型所有数据都保留在当前机器的~/.claude-mem目录下除了调用你为压缩/总结环节配置的 AI 提供方Claude / OpenRouter / Gemini之外没有任何数据离开你的机器。目录内到底有什么paths.ts 的路径定义让这份说明变得可验证、可感知。数据目录的解析逻辑为数据根目录默认~/.claude-mem源码中resolveDataDir()决定可通过环境变量覆盖claude-mem.dbSQLite 数据库主文件DB_PATH存放 observation、总结、prompt 等结构化记录logs日志目录LOGS_DIRsettings.json用户设置文件USER_SETTINGS_PATHobserver-sessions会话采集器的原始会话数据目录OBSERVER_SESSIONS_DIR。onboarding 文档提到的vector index向量索引对应 Chroma 相关能力——worker 暴露了/api/chroma/status接口用于查看 Chroma 集成状态见 worker README向量化检索服务于语义搜索semantic search。由于一切均在本机目录内使用与排查都围绕该目录展开。数据生命周期干净卸载由于所有数据SQLite、向量索引、日志、设置都集中在~/.claude-mem单一目录下卸载时即可整体清理。文档明确执行npx claude-mem uninstall会将这些数据干净地移除不留残余。这是本地优先设计带来的一个重要运维优势——数据归你所有去留由你决定。实战视角注入之后如何主动检索记忆自动注入是被动的——它只把相关的过去工作带进提示词。若你在会话中途想主动回忆我们上次是怎么解决这个问题的仓库还提供了配套的 mem-search 技能其三层工作流与本文档描述的存储模型完全一致都基于本地 SQLite 中的 observationSearch用search(query..., limit..., project...)拿回带 ID 的索引表每条约 50–100 tokenTimeline用timeline(anchor...或 query..., depth_before..., depth_after...)查看目标 observation 周围的上下文Fetch只对筛选出的 ID 调用get_observations(ids[...])取全文每条约 500–1000 token。该技能明确要求先过滤再取全文禁止不经筛选直接抓取完整细节理由是 10 倍的 token 节省先看廉价的索引与标题再决定哪些值得展开。这与自动注入环节的 token 经济学tokens_saved_vs_naive遵循同一设计哲学——压缩、筛选、按需展开。如果你的需求是把过去某类经验合成可对话的知识库则可以进一步使用 knowledge-agent 技能基于 observation 历史构建聚焦的语料corpus支持按project、types、concepts、files、dateStart/dateEnd等条件过滤构建后 prime 进一个 AI 会话再以问答形式与之对话。它正是 onboarding 说明中过去工作会沉淀为可复用资产这一理念的自然延伸。总结一条数据两种消费方式可以把 onboarding 说明浓缩为一张心智图阶段发生什么落地位置源码/目录采集Read / Edit / Bash 被压缩为 observationSQLiteclaude-mem.db写入链路总结会话结束时 observation 被总结ContextBuilder读取 summaries 渲染注入第二个会话起相关记忆自动进入提示词ContextBuilder.tsgenerateContextWithStats主动检索search → timeline → fetch 三层过滤mem-search 技能存储全量数据在本机~/.claude-mempaths.ts 中的DATA_DIR及子项卸载npx claude-mem uninstall干净移除~/.claude-mem整目录清理对使用者而言理解 claude-mem 只需抓住三点它把动作压缩成记忆observation在第二个会话开始自动回放injection并把这些记忆全部留在你自己的机器上~/.claude-mem。想快速验证这套机制最简单的方式是在一个新项目里完成两个连续会话第一个会话做真实的代码修改与决策第二个会话观察提示词中自动出现的上文摘要与 timeline——这正是无需重新解释代码库的最直观演示。【免费下载链接】claude-memPersistent Context Across Sessions for Every Agent – Captures everything your agent does during sessions, compresses it with AI, and injects relevant context back into future sessions. Works with Claude Code, OpenClaw, Codex, Gemini, Hermes, Copilot, OpenCode More项目地址: https://gitcode.com/GitHub_Trending/cl/claude-mem创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考