{
"canonical_name": "langchain-ai/langmem",
"compilation_id": "pack_45f7434022a44c45a55b58edab2e08a1",
"created_at": "2026-05-21T16:23:09.734693+00:00",
"created_by": "project-pack-compiler",
"feedback": {
"carrier_selection_notes": [
"viable_asset_types=mcp_config, recipe, host_instruction, eval, preflight",
"recommended_asset_types=mcp_config, recipe, host_instruction, eval, preflight"
],
"evidence_delta": {
"confirmed_claims": [
"identity_anchor_present",
"capability_and_host_targets_present",
"install_path_declared_or_better"
],
"missing_required_fields": [],
"must_verify_forwarded": [
"Run or inspect `pip install -U langmem` in an isolated environment.",
"Confirm the project exposes the claimed capability to at least one target host."
],
"quickstart_execution_scope": "allowlisted_sandbox_smoke",
"sandbox_command": "pip install -U langmem",
"sandbox_container_image": "python:3.12-slim",
"sandbox_execution_backend": "docker",
"sandbox_planner_decision": "llm_execute_isolated_install",
"sandbox_validation_id": "sbx_079744830055404084f217c89813e877"
},
"feedback_event_type": "project_pack_compilation_feedback",
"learning_candidate_reasons": [],
"template_gaps": []
},
"identity": {
"canonical_id": "project_616b768d275c30bdad1762fdcad0f64e",
"canonical_name": "langchain-ai/langmem",
"homepage_url": null,
"license": "unknown",
"repo_url": "https://github.com/langchain-ai/langmem",
"slug": "langmem",
"source_packet_id": "phit_ccdecd12f1b948bea410d86a616df2e1",
"source_validation_id": "dval_769f6bd591314079a9e33348a317fb5d"
},
"merchandising": {
"best_for": "需要软件开发与交付能力，并使用 claude的用户",
"github_forks": 167,
"github_stars": 1453,
"one_liner_en": "LangMem helps agents learn and adapt from their interactions over time.",
"one_liner_zh": "LangMem helps agents learn and adapt from their interactions over time.",
"primary_category": {
"category_id": "software-development",
"confidence": "medium",
"name_en": "Software Development",
"name_zh": "软件开发与交付",
"reason": "matched_keywords:git"
},
"target_user": "使用 claude, chatgpt 等宿主 AI 的用户",
"title_en": "langmem",
"title_zh": "langmem 能力包",
"visible_tags": [
{
"label_en": "Knowledge Retrieval",
"label_zh": "知识检索",
"source": "repo_evidence_project_characteristics",
"tag_id": "product_domain-knowledge-retrieval",
"type": "product_domain"
},
{
"label_en": "Knowledge Base Q&A",
"label_zh": "知识库问答",
"source": "repo_evidence_project_characteristics",
"tag_id": "user_job-knowledge-base-q-a",
"type": "user_job"
},
{
"label_en": "Structured Extraction",
"label_zh": "结构化提取",
"source": "repo_evidence_project_characteristics",
"tag_id": "core_capability-structured-extraction",
"type": "core_capability"
},
{
"label_en": "Checkpoint Resume",
"label_zh": "断点恢复流程",
"source": "repo_evidence_project_characteristics",
"tag_id": "workflow_pattern-checkpoint-resume",
"type": "workflow_pattern"
},
{
"label_en": "Evaluation Suite",
"label_zh": "评测体系",
"source": "repo_evidence_project_characteristics",
"tag_id": "selection_signal-evaluation-suite",
"type": "selection_signal"
}
]
},
"packet_id": "phit_ccdecd12f1b948bea410d86a616df2e1",
"page_model": {
"artifacts": {
"artifact_slug": "langmem",
"files": [
"PROJECT_PACK.json",
"QUICK_START.md",
"PROMPT_PREVIEW.md",
"HUMAN_MANUAL.md",
"AI_CONTEXT_PACK.md",
"BOUNDARY_RISK_CARD.md",
"PITFALL_LOG.md",
"REPO_INSPECTION.json",
"REPO_INSPECTION.md",
"CAPABILITY_CONTRACT.json",
"EVIDENCE_INDEX.json",
"CLAIM_GRAPH.json"
],
"required_files": [
"PROJECT_PACK.json",
"QUICK_START.md",
"PROMPT_PREVIEW.md",
"HUMAN_MANUAL.md",
"AI_CONTEXT_PACK.md",
"BOUNDARY_RISK_CARD.md",
"PITFALL_LOG.md",
"REPO_INSPECTION.json"
]
},
"detail": {
"capability_source": "Project Hit Packet + DownstreamValidationResult",
"commands": [
{
"command": "pip install -U langmem",
"label": "Python / pip · 官方安装入口",
"source": "https://github.com/langchain-ai/langmem#readme",
"verified": true
}
],
"display_tags": [
"知识检索",
"知识库问答",
"结构化提取",
"断点恢复流程",
"评测体系"
],
"eyebrow": "软件开发与交付",
"glance": [
{
"body": "判断自己是不是目标用户。",
"label": "最适合谁",
"value": "需要软件开发与交付能力，并使用 claude的用户"
},
{
"body": "先理解能力边界，再决定是否继续。",
"label": "核心价值",
"value": "LangMem helps agents learn and adapt from their interactions over time."
},
{
"body": "未完成验证前保持审慎。",
"label": "继续前",
"value": "publish to Doramagic.ai project surfaces"
}
],
"guardrail_source": "Boundary & Risk Card",
"guardrails": [
{
"body": "Prompt Preview 只展示流程，不证明项目已安装或运行。",
"label": "Check 1",
"value": "不要把试用当真实运行"
},
{
"body": "claude, chatgpt",
"label": "Check 2",
"value": "确认宿主兼容"
},
{
"body": "publish to Doramagic.ai project surfaces",
"label": "Check 3",
"value": "先隔离验证"
}
],
"mode": "mcp_config, recipe, host_instruction, eval, preflight",
"pitfall_log": {
"items": [
{
"body": "GitHub 社区证据显示该项目存在一个安装相关的待验证问题：GRAPH_RECURSION_LIMIT",
"category": "安装坑",
"evidence": [
"community_evidence:github | cevd_82b923de03f34d5a9fa8530916b40d14 | https://github.com/langchain-ai/langmem/issues/133 | 来源讨论提到 python 相关条件，需在安装/试用前复核。"
],
"severity": "high",
"suggested_check": "来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。",
"title": "来源证据：GRAPH_RECURSION_LIMIT",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Persistence?",
"category": "安装坑",
"evidence": [
"community_evidence:github | cevd_b9688483fa44468a96801d46825b040f | https://github.com/langchain-ai/langmem/issues/154 | 来源讨论提到 python 相关条件，需在安装/试用前复核。"
],
"severity": "high",
"suggested_check": "来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。",
"title": "来源证据：Persistence?",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Enhance error message when summarization fails due to missing HumanMessage in trimmed window",
"category": "安全/权限坑",
"evidence": [
"community_evidence:github | cevd_15b3f9c4829745339b470171f005b3df | https://github.com/langchain-ai/langmem/issues/156 | 来源讨论提到 python 相关条件，需在安装/试用前复核。"
],
"severity": "high",
"suggested_check": "来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。",
"title": "来源证据：Enhance error message when summarization fails due to missing HumanMessage in trimmed window",
"user_impact": "可能影响授权、密钥配置或安全边界。"
},
{
"body": "项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。",
"category": "配置坑",
"evidence": [
"capability.host_targets | github_repo:920242883 | https://github.com/langchain-ai/langmem | host_targets=claude, chatgpt"
],
"severity": "medium",
"suggested_check": "列出会写入的配置文件、目录和卸载/回滚步骤。",
"title": "可能修改宿主 AI 配置",
"user_impact": "安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。"
},
{
"body": "README/documentation is current enough for a first validation pass.",
"category": "能力坑",
"evidence": [
"capability.assumptions | github_repo:920242883 | https://github.com/langchain-ai/langmem | README/documentation is current enough for a first validation pass."
],
"severity": "medium",
"suggested_check": "将假设转成下游验证清单。",
"title": "能力判断依赖假设",
"user_impact": "假设不成立时，用户拿不到承诺的能力。"
},
{
"body": "未记录 last_activity_observed。",
"category": "维护坑",
"evidence": [
"evidence.maintainer_signals | github_repo:920242883 | https://github.com/langchain-ai/langmem | last_activity_observed missing"
],
"severity": "medium",
"suggested_check": "补 GitHub 最近 commit、release、issue/PR 响应信号。",
"title": "维护活跃度未知",
"user_impact": "新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。"
},
{
"body": "no_demo",
"category": "安全/权限坑",
"evidence": [
"downstream_validation.risk_items | github_repo:920242883 | https://github.com/langchain-ai/langmem | no_demo; severity=medium"
],
"severity": "medium",
"suggested_check": "进入安全/权限治理复核队列。",
"title": "下游验证发现风险项",
"user_impact": "下游已经要求复核，不能在页面中弱化。"
},
{
"body": "no_demo",
"category": "安全/权限坑",
"evidence": [
"risks.scoring_risks | github_repo:920242883 | https://github.com/langchain-ai/langmem | no_demo; severity=medium"
],
"severity": "medium",
"suggested_check": "把风险写入边界卡，并确认是否需要人工复核。",
"title": "存在评分风险",
"user_impact": "风险会影响是否适合普通用户安装。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Security: OWASP Agent Memory Guard for memory poisoning defense (ASI06)",
"category": "安全/权限坑",
"evidence": [
"community_evidence:github | cevd_760d72a9519c42a8b1e31d8932383bc2 | https://github.com/langchain-ai/langmem/issues/164 | 来源讨论提到 python 相关条件，需在安装/试用前复核。"
],
"severity": "medium",
"suggested_check": "来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。",
"title": "来源证据：Security: OWASP Agent Memory Guard for memory poisoning defense (ASI06)",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "issue_or_pr_quality=unknown。",
"category": "维护坑",
"evidence": [
"evidence.maintainer_signals | github_repo:920242883 | https://github.com/langchain-ai/langmem | issue_or_pr_quality=unknown"
],
"severity": "low",
"suggested_check": "抽样最近 issue/PR，判断是否长期无人处理。",
"title": "issue/PR 响应质量未知",
"user_impact": "用户无法判断遇到问题后是否有人维护。"
},
{
"body": "release_recency=unknown。",
"category": "维护坑",
"evidence": [
"evidence.maintainer_signals | github_repo:920242883 | https://github.com/langchain-ai/langmem | release_recency=unknown"
],
"severity": "low",
"suggested_check": "确认最近 release/tag 和 README 安装命令是否一致。",
"title": "发布节奏不明确",
"user_impact": "安装命令和文档可能落后于代码，用户踩坑概率升高。"
}
],
"source": "ProjectPitfallLog + ProjectHitPacket + validation + community signals",
"summary": "发现 11 个潜在踩坑项，其中 3 个为 high/blocking；最高优先级：安装坑 - 来源证据：GRAPH_RECURSION_LIMIT。",
"title": "踩坑日志"
},
"snapshot": {
"contributors": 12,
"forks": 167,
"license": "unknown",
"note": "站点快照，非实时质量证明；用于开工前背景判断。",
"stars": 1453
},
"source_url": "https://github.com/langchain-ai/langmem",
"steps": [
{
"body": "不安装项目，先体验能力节奏。",
"code": "preview",
"title": "先试 Prompt"
},
{
"body": "理解输入、输出、失败模式和边界。",
"code": "manual",
"title": "读说明书"
},
{
"body": "把上下文交给宿主 AI 继续工作。",
"code": "context",
"title": "带给 AI"
},
{
"body": "进入主力环境前先完成安装入口与风险边界验证。",
"code": "verify",
"title": "沙箱验证"
}
],
"subtitle": "LangMem helps agents learn and adapt from their interactions over time.",
"title": "langmem 能力包",
"trial_prompt": "# langmem - Prompt Preview\n\n> 复制下面这段 Prompt 到你常用的 AI，先试一次，不需要安装。\n> 它的目标是让你直接体验这个项目的服务方式，而不是阅读项目介绍。\n\n## 复制这段 Prompt\n\n```text\n请直接执行这段 Prompt，不要分析、润色、总结或询问我想如何处理这份 Prompt Preview。\n\n你现在扮演 langmem 的“安装前体验版”。\n这不是项目介绍、不是评价报告、不是 README 总结。你的任务是让我用最小成本体验它的核心服务。\n\n我的试用任务：我想用它完成一个真实的软件开发与交付任务。\n我常用的宿主 AI：claude / chatgpt\n\n【体验目标】\n围绕我的真实任务，现场演示这个项目如何把输入转成 示例引导, 判断线索。重点是让我感受到工作方式，而不是给我项目背景。\n\n【业务流约束】\n- 你必须像一个正在提供服务的项目能力包，而不是像一个讲解员。\n- 每一轮只推进一个步骤；提出问题后必须停下来等我回答。\n- 每一步都必须让我感受到一个具体服务动作：澄清、整理、规划、检查、判断或收尾。\n- 每一步都要说明：当前目标、你需要我提供什么、我回答后你会产出什么。\n- 不要安装、不要运行命令、不要写代码、不要声称测试通过、不要声称已经修改文件。\n- 需要真实安装或宿主加载后才能验证的内容，必须明确说“这一步需要安装后验证”。\n- 如果我说“用示例继续”，你可以用虚构示例推进，但仍然不能声称真实执行。\n\n【可体验服务能力】\n- 安装前能力预览: LangMem helps agents learn and adapt from their interactions over time. 输入：用户任务, 当前 AI 对话上下文；输出：示例引导, 判断线索。\n\n【必须安装后才可验证的能力】\n- 命令行启动或安装流程: 项目文档中存在可执行命令，真实使用需要在本地或宿主环境中运行这些命令。 输入：终端环境, 包管理器, 项目依赖；输出：安装结果, 列表/更新/运行结果。\n\n【核心服务流】\n请严格按这个顺序带我体验。不要一次性输出完整流程：\n1. page-overview：LangMem 概述。围绕“LangMem 概述”模拟一次用户任务，不展示安装或运行结果。\n2. page-installation：安装与配置。围绕“安装与配置”模拟一次用户任务，不展示安装或运行结果。\n3. page-hot-path-quickstart：热路径快速开始。围绕“热路径快速开始”模拟一次用户任务，不展示安装或运行结果。\n4. page-system-architecture：系统架构。围绕“系统架构”模拟一次用户任务，不展示安装或运行结果。\n5. page-memory-tools：记忆工具。围绕“记忆工具”模拟一次用户任务，不展示安装或运行结果。\n\n【核心能力体验剧本】\n每一步都必须按“输入 -> 服务动作 -> 中间产物”执行。不要只说流程名：\n1. page-overview\n输入：用户提供的“LangMem 概述”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n2. page-installation\n输入：用户提供的“安装与配置”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n3. page-hot-path-quickstart\n输入：用户提供的“热路径快速开始”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n4. page-system-architecture\n输入：用户提供的“系统架构”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n5. page-memory-tools\n输入：用户提供的“记忆工具”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n【项目服务规则】\n这些规则决定你如何服务用户。不要解释规则本身，而要在每一步执行时遵守：\n- 先确认用户任务、输入材料和成功标准，再模拟项目能力。\n- 每一步都必须形成可检查的小产物，并等待用户确认后再继续。\n- 凡是需要安装、调用工具或访问外部服务的能力，都必须标记为安装后验证。\n\n【每一步的服务约束】\n- Step 1 / page-overview：Step 1 必须围绕“LangMem 概述”形成一个小中间产物，并等待用户确认。\n- Step 2 / page-installation：Step 2 必须围绕“安装与配置”形成一个小中间产物，并等待用户确认。\n- Step 3 / page-hot-path-quickstart：Step 3 必须围绕“热路径快速开始”形成一个小中间产物，并等待用户确认。\n- Step 4 / page-system-architecture：Step 4 必须围绕“系统架构”形成一个小中间产物，并等待用户确认。\n- Step 5 / page-memory-tools：Step 5 必须围绕“记忆工具”形成一个小中间产物，并等待用户确认。\n\n【边界与风险】\n- 不要声称已经安装、运行、调用 API、读写本地文件或完成真实任务。\n- 安装前预览只能展示工作方式，不能证明兼容性、性能或输出质量。\n- 涉及安装、插件加载、工具调用或外部服务的能力必须安装后验证。\n\n【可追溯依据】\n这些路径只用于你内部校验或在我追问“依据是什么”时简要引用。不要在首次回复主动展开：\n- https://github.com/langchain-ai/langmem\n- https://github.com/langchain-ai/langmem#readme\n- README.md\n- src/langmem/__init__.py\n- pyproject.toml\n- docs/docs/hot_path_quickstart.md\n- src/langmem/knowledge/tools.py\n- src/langmem/knowledge/__init__.py\n- src/langmem/prompts/__init__.py\n- langgraph.json\n- docs/docs/guides/memory_tools.md\n\n【首次问题规则】\n- 首次三问必须先确认用户目标、成功标准和边界，不要提前进入工具、安装或实现细节。\n- 如果后续需要技术条件、文件路径或运行环境，必须等用户确认目标后再追问。\n\n首次回复必须只输出下面 4 个部分：\n1. 体验开始：用 1 句话说明你将带我体验 langmem 的核心服务。\n2. 当前步骤：明确进入 Step 1，并说明这一步要解决什么。\n3. 你会如何服务我：说明你会先改变我完成任务的哪个动作。\n4. 只问我 3 个问题，然后停下等待回答。\n\n首次回复禁止输出：后续完整流程、证据清单、安装命令、项目评价、营销文案、已经安装或运行的说法。\n\nStep 1 / brainstorming 的二轮协议：\n- 我回答首次三问后，你仍然停留在 Step 1 / brainstorming，不要进入 Step 2。\n- 第二次回复必须产出 6 个部分：澄清后的任务定义、成功标准、边界条件、\n 2-3 个可选方案、每个方案的权衡、推荐方案。\n- 第二次回复最后必须问我是否确认推荐方案；只有我明确确认后，才能进入下一步。\n- 第二次回复禁止输出 git worktree、代码计划、测试文件、命令或真实执行结果。\n\n后续对话规则：\n- 我回答后，你先完成当前步骤的中间产物并等待确认；只有我确认后，才能进入下一步。\n- 每一步都要生成一个小的中间产物，例如澄清后的目标、计划草案、测试意图、验证清单或继续/停止判断。\n- 所有演示都写成“我会建议/我会引导/这一步会形成”，不要写成已经真实执行。\n- 不要声称已经测试通过、文件已修改、命令已运行或结果已产生。\n- 如果某个能力必须安装后验证，请直接说“这一步需要安装后验证”。\n- 如果证据不足，请明确说“证据不足”，不要补事实。\n```\n",
"voices": [
{
"body": "来源平台：github。github/github_issue: Persistence?（https://github.com/langchain-ai/langmem/issues/154）；github/github_issue: Security: OWASP Agent Memory Guard for memory poisoning defense (ASI06)（https://github.com/langchain-ai/langmem/issues/164）；github/github_issue: Security: OWASP Agent Memory Guard for memory poisoning defense (ASI06)（https://github.com/langchain-ai/langmem/issues/163）；github/github_issue: Enhance error message when summarization fails due to missing HumanMessa（https://github.com/langchain-ai/langmem/issues/156）；github/github_issue: GRAPH_RECURSION_LIMIT（https://github.com/langchain-ai/langmem/issues/133）。这些是项目级外部声音，不作为单独质量证明。",
"items": [
{
"kind": "github_issue",
"source": "github",
"title": "Persistence?",
"url": "https://github.com/langchain-ai/langmem/issues/154"
},
{
"kind": "github_issue",
"source": "github",
"title": "Security: OWASP Agent Memory Guard for memory poisoning defense (ASI06)",
"url": "https://github.com/langchain-ai/langmem/issues/164"
},
{
"kind": "github_issue",
"source": "github",
"title": "Security: OWASP Agent Memory Guard for memory poisoning defense (ASI06)",
"url": "https://github.com/langchain-ai/langmem/issues/163"
},
{
"kind": "github_issue",
"source": "github",
"title": "Enhance error message when summarization fails due to missing HumanMessa",
"url": "https://github.com/langchain-ai/langmem/issues/156"
},
{
"kind": "github_issue",
"source": "github",
"title": "GRAPH_RECURSION_LIMIT",
"url": "https://github.com/langchain-ai/langmem/issues/133"
}
],
"status": "已收录 5 条来源",
"title": "社区讨论"
}
]
},
"homepage_card": {
"category": "软件开发与交付",
"desc": "LangMem helps agents learn and adapt from their interactions over time.",
"effort": "安装已验证",
"forks": 167,
"icon": "code",
"name": "langmem 能力包",
"risk": "可发布",
"slug": "langmem",
"stars": 1453,
"tags": [
"知识检索",
"知识库问答",
"结构化提取",
"断点恢复流程",
"评测体系"
],
"thumb": "gray",
"type": "MCP 配置"
},
"manual": {
"markdown": "# https://github.com/langchain-ai/langmem 项目说明书\n\n生成时间: 2026-05-21 16:18:01 UTC\n\n## 目录\n\n- [LangMem 概述](#page-overview)\n- [安装与配置](#page-installation)\n- [热路径快速开始](#page-hot-path-quickstart)\n- [后台处理快速开始](#page-background-quickstart)\n- [系统架构](#page-system-architecture)\n- [记忆工具](#page-memory-tools)\n- [记忆提取](#page-memory-extraction)\n- [提示优化](#page-prompt-optimization)\n- [语义记忆管理](#page-semantic-memory)\n- [情景记忆提取](#page-episodic-memory)\n\n\n\n## LangMem 概述\n\n### 相关页面\n\n相关主题：[安装与配置](#page-installation), [系统架构](#page-system-architecture)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/langmem/prompts/types.py](https://github.com/langchain-ai/langmem/blob/main/src/langmem/prompts/types.py)\n- [src/langmem/knowledge/extraction.py](https://github.com/langchain-ai/langmem/blob/main/src/langmem/knowledge/extraction.py)\n- [src/langmem/knowledge/tools.py](https://github.com/langchain-ai/langmem/blob/main/src/langmem/knowledge/tools.py)\n- [src/langmem/short_term/summarization.py](https://github.com/langchain-ai/langmem/blob/main/src/langmem/short_term/summarization.py)\n- [src/langmem/prompts/optimization.py](https://github.com/langchain-ai/langmem/blob/main/src/langmem/prompts/optimization.py)\n- [src/langmem/prompts/gradient.py](https://github.com/langchain-ai/langmem/blob/main/src/langmem/prompts/gradient.py)\n- [src/langmem/prompts/prompt.py](https://github.com/langchain-ai/langmem/blob/main/src/langmem/prompts/prompt.py)\n \n\n# LangMem 概述\n\nLangMem 是由 LangChain 团队开发的一个开源库，专注于为大型语言模型（LLM）代理提供**记忆（Memory）管理**和**提示优化（Prompt Optimization）**能力。该库帮助开发者构建能够跨会话学习、适应用户偏好并持续改进的智能代理系统。\n\n## 核心定位\n\nLangMem 填补了 LLM 代理在以下方面的能力空白：\n\n| 能力维度 | 说明 |\n|---------|------|\n| **长期记忆** | 从对话历史中提取、存储和检索结构化记忆 |\n| **短期记忆** | 对话过程中的实时摘要和信息压缩 |\n| **提示优化** | 基于反馈和历史轨迹自动优化系统提示 |\n\n资料来源：[src/langmem/prompts/types.py:1-15]()\n\n## 整体架构\n\nLangMem 的架构围绕三大核心模块展开，每个模块负责不同的记忆或优化职责：\n\n```mermaid\ngraph TD\n A[LangMem] --> B[knowledge
长期记忆模块]\n A --> C[short_term
短期记忆模块]\n A --> D[prompts
提示优化模块]\n \n B --> B1[extraction.py
记忆提取管理]\n B --> B2[tools.py
记忆操作工具]\n \n C --> C1[summarization.py
对话摘要]\n \n D --> D1[optimization.py
优化器工厂]\n D --> D2[gradient.py
梯度优化器]\n D --> D3[prompt.py
提示模板]\n D --> D4[types.py
类型定义]\n```\n\n## 核心数据类型\n\nLangMem 使用 TypeScript 风格的 TypedDict 定义数据结构，确保类型安全和清晰的接口契约。\n\n资料来源：[src/langmem/prompts/types.py:1-90]()\n\n### Prompt（提示定义）\n\n```python\nclass Prompt(TypedDict, total=False):\n name: Required[str] # 提示名称，唯一标识\n prompt: Required[str] # 提示内容\n update_instructions: str | None # 更新指南\n when_to_update: str | None # 更新依赖条件\n```\n\n### AnnotatedTrajectory（标注轨迹）\n\n用于记录对话历史及其反馈信息：\n\n```python\nclass AnnotatedTrajectory(typing.NamedTuple):\n messages: list[AnyMessage] # 对话消息列表\n feedback: dict[str, typing.Any] # 反馈信息（如 developer_feedback、score）\n```\n\n### 优化器输入类型\n\n| 类型 | 用途 | 关键字段 |\n|-----|------|---------|\n| `PromptOptimizerInput` | 单提示优化 | `trajectories`, `prompt` |\n| `MultiPromptOptimizerInput` | 多提示协同优化 | `trajectories`, `prompts` |\n\n资料来源：[src/langmem/prompts/types.py:50-120]()\n\n## 长期记忆模块\n\n长期记忆模块负责从对话中提取、存储和检索用户偏好及知识信息。\n\n资料来源：[src/langmem/knowledge/extraction.py:1-100]()\n\n### 核心组件\n\n#### MemoryManager（记忆管理器）\n\n`create_memory_manager` 函数创建核心的记忆管理器：\n\n```python\ndef create_memory_manager(\n model: str | BaseChatModel, # 主模型，用于提取和综合\n schemas: list[type], # 记忆的 Pydantic schema 定义\n *,\n instructions: str | None = None, # 自定义提取指令\n enable_inserts: bool = True, # 允许创建新记忆\n enable_updates: bool = True, # 允许更新现有记忆\n enable_deletes: bool = True, # 允许删除过时记忆\n) -> MemoryManager\n```\n\n**功能特性**：\n\n- **插入（Insert）**：从新对话中创建新的记忆条目\n- **更新（Update）**：修改现有记忆的内容或属性\n- **删除（Delete）**：移除不再相关或过时的记忆\n- **多步迭代**：支持设置 `max_steps` 进行深度提取和综合\n\n资料来源：[src/langmem/knowledge/extraction.py:80-120]()\n\n#### MemoryStoreManager（存储管理器）\n\n`create_memory_store_manager` 创建与 LangGraph 存储层集成的管理器：\n\n```python\ndef create_memory_store_manager(\n model: str | BaseChatModel, # 主模型\n schemas: list[type], # 记忆 schema\n *,\n query_model: str | None = None, # 用于搜索的专用模型（更快更便宜）\n query_limit: int = 10, # 搜索返回结果数量\n namespace: tuple[str, ...] = (\"memories\", \"{langgraph_user_id}\"),\n store: BaseStore | None = None, # LangGraph 存储后端\n) -> MemoryStoreManager\n```\n\n**搜索机制**：\n\n1. 直接嵌入新消息进行相似度搜索\n2. 或使用专用查询模型（query_model）生成优化的搜索查询\n\n资料来源：[src/langmem/knowledge/extraction.py:50-80]()\n\n### 记忆搜索工具\n\n资料来源：[src/langmem/knowledge/tools.py:1-80]()\n\n`create_memory_searcher` 函数创建语义搜索管道：\n\n```python\ndef create_memory_searcher(\n model: str | BaseChatModel,\n prompt: str = \"Search for distinct memories relevant to different aspects of the provided context.\",\n namespace: tuple[str, ...] = (\"memories\", \"{langgraph_user_id}\"),\n) -> Runnable[MessagesState, typing.Awaitable[list[SearchItem]]]\n```\n\n### 记忆管理工具\n\nLangMem 提供可集成到 LangGraph Agent 的工具：\n\n#### 记忆操作工具\n\n```python\ncreate_manage_memory_tool(\n namespace: str | tuple[str, ...],\n schema: type[BaseModel], # 记忆的 schema 类\n actions_permitted: list[Literal[\"create\", \"update\", \"upsert\", \"delete\"]],\n store: BaseStore | None = None,\n)\n```\n\n支持的操作类型：\n\n| 操作 | 说明 |\n|-----|------|\n| `create` | 创建新记忆 |\n| `update` | 更新现有记忆 |\n| `upsert` | 存在则更新，不存在则创建 |\n| `delete` | 删除指定记忆 |\n\n#### 记忆搜索工具\n\n```python\ncreate_search_memory_tool(\n namespace: str | tuple[str, ...],\n store: BaseStore | None = None,\n)\n```\n\n支持参数：\n- `query`: 自然语言搜索查询\n- `limit`: 返回结果数量限制\n- `offset`: 分页偏移\n- `filter`: 元数据过滤条件\n\n资料来源：[src/langmem/knowledge/tools.py:80-150]()\n\n## 短期记忆模块\n\n短期记忆模块处理对话过程中的实时信息压缩和摘要。\n\n资料来源：[src/langmem/short_term/summarization.py:1-80]()\n\n### SummarizationNode（摘要节点）\n\n用于 LangGraph 工作流中的消息摘要：\n\n```python\nsummarization_node = SummarizationNode(\n model=summarization_model, # 专用的轻量摘要模型\n max_tokens=256, # 摘要最大 token 数\n max_tokens_before_summary=256, # 触发摘要的消息长度阈值\n max_summary_tokens=128, # 单次摘要最大 token\n)\n```\n\n### RunningSummary（运行摘要）\n\n状态管理对象，用于跟踪和管理对话摘要：\n\n```python\nclass RunningSummary:\n summary: str | None # 当前摘要内容\n key_points: list[str] # 关键要点列表\n message_count: int # 已处理消息数\n```\n\n**典型使用流程**：\n\n1. 在 LangGraph 状态图中添加 `summarization_node`\n2. 节点接收 `summarized_messages_key` 输入\n3. 返回包含摘要消息和上下文更新的状态\n\n资料来源：[src/langmem/short_term/summarization.py:20-100]()\n\n## 提示优化模块\n\n提示优化模块基于对话历史和反馈自动改进系统提示。\n\n资料来源：[src/langmem/prompts/optimization.py:1-80]()\n\n### 优化策略类型\n\n| 策略 | 说明 | 配置参数 |\n|-----|------|---------|\n| `gradient` | 梯度式优化，基于假设-验证循环 | `max_reflection_steps` |\n| `metaprompt` | 元提示式优化，使用结构化推理 | `max_reflection_steps`, `min_reflection_steps` |\n| `prompt_memory` | 记忆式优化，从历史中学习模式 | 无特殊配置 |\n\n### 单提示优化器\n\n```python\ndef create_prompt_optimizer(\n model: str | BaseChatModel,\n kind: Literal[\"gradient\", \"metaprompt\", \"prompt_memory\"] = \"gradient\",\n config: dict | None = None,\n) -> PromptOptimizer\n```\n\n**输入结构**：\n\n```python\n{\n \"trajectories\": [\n AnnotatedTrajectory(\n messages=[...],\n feedback={\"clarity\": \"needs more structure\"}\n )\n ],\n \"prompt\": \"You are an astronomy expert\"\n}\n```\n\n资料来源：[src/langmem/prompts/optimization.py:80-120]()\n\n### 多提示优化器\n\n```python\ndef create_multi_prompt_optimizer(\n model: str | BaseChatModel,\n kind: Literal[\"gradient\", \"metaprompt\", \"prompt_memory\"] = \"gradient\",\n config: dict | None = None,\n) -> MultiPromptOptimizer\n```\n\n**输入结构**：\n\n```python\n{\n \"trajectories\": [...], # 多个标注轨迹\n \"prompts\": [\n Prompt(name=\"research\", prompt=\"Research the given topic\"),\n Prompt(name=\"summarize\", prompt=\"Summarize findings\"),\n ]\n}\n```\n\n### 梯度优化器详解\n\n资料来源：[src/langmem/prompts/gradient.py:1-60]()\n\n梯度优化器通过迭代的\"假设-验证\"循环改进提示：\n\n```python\nclass GradientOptimizerConfig(TypedDict, total=False):\n gradient_prompt: str # 梯度优化提示模板\n metaprompt: str # 元提示模板\n max_reflection_steps: int # 最大反思步数\n min_reflection_steps: int # 最小反思步数\n```\n\n**优化流程**：\n\n1. 分析当前提示和对话轨迹\n2. 生成性能不佳的假设原因\n3. 基于假设提出调整建议\n4. 应用最小侵入性的修改\n5. 迭代验证直到满足停止条件\n\n资料来源：[src/langmem/prompts/gradient.py:20-80]()\n\n### 提示模板\n\n资料来源：[src/langmem/prompts/prompt.py:1-50]()\n\nLangMem 预定义了两类优化提示模板：\n\n#### 单轨迹反思模板\n\n```python\nINSTRUCTION_REFLECTION_PROMPT = \"\"\"You are helping an AI agent improve. You can do this by changing their system prompt.\n\nThese is their current prompt:\n\n{current_prompt}\n\n\nHere was the agent's trajectory:\n\n{trajectory}\n\n\nHere is the user's feedback:\n\n\n{feedback}\n\n...\n\"\"\"\n```\n\n#### 多轨迹批量反思模板\n\n```python\nINSTRUCTION_REFLECTION_MULTIPLE_PROMPT = \"\"\"...\"\"\"\n# 使用 标签批量包含多个轨迹-反馈对\n```\n\n**响应格式**：\n\n```python\nclass GeneralResponse(TypedDict):\n logic: str # 优化逻辑说明\n update_prompt: bool # 是否需要更新\n new_prompt: str # 新提示内容\n```\n\n## 与 LangGraph 集成\n\nLangMem 被设计为与 LangGraph 无缝协作，利用 LangGraph 的以下组件：\n\n| LangGraph 组件 | LangMem 集成点 |\n|---------------|---------------|\n| `BaseStore` | 记忆的持久化存储后端 |\n| `InMemoryStore` | 开发/测试用内存存储 |\n| `@entrypoint` | 异步工作流装饰器 |\n| `create_react_agent` | 集成记忆工具的 ReAct 代理 |\n| `RunnableConfig` | 命名空间和配置管理 |\n\n### 命名空间机制\n\n记忆使用层级命名空间组织：\n\n```python\nnamespace = (\"memories\", \"{langgraph_user_id}\")\n# 示例: (\"memories\", \"user123\")\n```\n\n命名空间模板支持运行时占位符替换，确保多用户数据隔离。\n\n### 后台反射执行器\n\n```python\nfrom langmem import ReflectionExecutor\n\nreflection = ReflectionExecutor(manager, store=store)\n```\n\n`ReflectionExecutor` 支持将记忆处理任务后台化：\n\n```mermaid\nsequenceDiagram\n participant Agent\n participant Background\n participant Store\n\n Agent->>Agent: process message\n Agent-->>User: response\n Agent->>Background: schedule enrichment
(after_seconds=0)\n Note over Background,Store: Memory processing happens
in background thread\n```\n\n## API 速查表\n\n### 创建函数一览\n\n| 函数 | 返回类型 | 用途 |\n|-----|---------|------|\n| `create_memory_manager` | `MemoryManager` | 创建记忆管理器 |\n| `create_memory_searcher` | `Runnable` | 创建搜索管道 |\n| `create_memory_store_manager` | `MemoryStoreManager` | 创建存储管理器 |\n| `create_thread_extractor` | 提取器 | 创建线程提取器 |\n| `create_prompt_optimizer` | `PromptOptimizer` | 创建单提示优化器 |\n| `create_multi_prompt_optimizer` | `MultiPromptOptimizer` | 创建多提示优化器 |\n| `create_manage_memory_tool` | `BaseTool` | 创建记忆操作工具 |\n| `create_search_memory_tool` | `BaseTool` | 创建记忆搜索工具 |\n\n## 总结\n\nLangMem 提供了一套完整的记忆和提示优化解决方案：\n\n- **长期记忆**：通过结构化 schema 和语义搜索实现持久化知识管理\n- **短期记忆**：通过实时摘要保持对话上下文的高效利用\n- **提示优化**：通过多种策略（梯度、元提示、记忆学习）持续改进代理行为\n\n该库与 LangGraph 深度集成，既可以作为独立组件使用，也能作为 LangGraph 代理的能力扩展。\n\n---\n\n\n\n## 安装与配置\n\n### 相关页面\n\n相关主题：[LangMem 概述](#page-overview), [记忆工具](#page-memory-tools)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [pyproject.toml](https://github.com/langchain-ai/langmem/blob/main/pyproject.toml)\n- [README.md](https://github.com/langchain-ai/langmem/blob/main/README.md)\n- [src/langmem/knowledge/extraction.py](https://github.com/langchain-ai/langmem/blob/main/src/langmem/knowledge/extraction.py)\n- [src/langmem/prompts/types.py](https://github.com/langchain-ai/langmem/blob/main/src/langmem/prompts/types.py)\n- [src/langmem/knowledge/tools.py](https://github.com/langchain-ai/langmem/blob/main/src/langmem/knowledge/tools.py)\n- [src/langmem/short_term/summarization.py](https://github.com/langchain-ai/langmem/blob/main/src/langmem/short_term/summarization.py)\n- [src/langmem/prompts/optimization.py](https://github.com/langchain-ai/langmem/blob/main/src/langmem/prompts/optimization.py)\n \n\n# 安装与配置\n\n## 概述\n\nLangMem 是一个用于构建具有记忆能力的大语言模型应用的 Python 库。该库提供了一套完整的工具，用于管理对话记忆、提示优化和短期记忆总结等功能。安装与配置章节将详细介绍如何正确设置 LangMem 环境、配置依赖项、以及初始化各类管理器组件。\n\n## 环境要求\n\n### Python 版本要求\n\nLangMem 需要 Python 3.10 或更高版本。建议使用 Python 3.11 以获得最佳性能和兼容性。\n\n### 核心依赖\n\nLangMem 的核心依赖包括：\n\n| 依赖包 | 最低版本 | 用途说明 |\n|--------|----------|----------|\n| langchain-core | 最新稳定版 | 核心语言模型接口 |\n| langchain-anthropic | 最新稳定版 | Anthropic 模型支持 |\n| langchain-openai | 最新稳定版 | OpenAI 模型支持 |\n| langgraph | 最新稳定版 | 图状态管理和工作流 |\n| pydantic | 2.x | 数据验证和模型定义 |\n\n## 安装方式\n\n### 使用 uv 安装（推荐）\n\n```bash\nuv add langmem\n```\n\n### 使用 pip 安装\n\n```bash\npip install langmem\n```\n\n### 从源码安装\n\n```bash\ncd examples/standalone_examples\nuv venv\nsource .venv/bin/activate\nuv sync\n```\n\n## 环境变量配置\n\n### API 密钥设置\n\n使用 LangMem 前需要配置相应的 API 密钥：\n\n```bash\nexport OPENAI_API_KEY=your_api_key_here\nexport ANTHROPIC_API_KEY=your_api_key_here # 如使用 Anthropic 模型\n```\n\n## 核心组件配置\n\n### 记忆管理器 (Memory Manager)\n\n`create_memory_manager` 函数用于创建记忆管理器，支持插入、更新和删除记忆操作。资料来源：[src/langmem/knowledge/extraction.py:1-200]()\n\n#### 基础配置示例\n\n```python\nfrom langmem import create_memory_manager\nfrom pydantic import BaseModel\n\nclass PreferenceMemory(BaseModel):\n kind: str = \"PreferenceMemory\"\n preference: str\n context: str\n\nmanager = create_memory_manager(\n \"anthropic:claude-3-5-sonnet-latest\",\n schemas=[PreferenceMemory],\n)\n```\n\n#### 配置参数说明\n\n| 参数名 | 类型 | 默认值 | 说明 |\n|--------|------|--------|------|\n| model | str \\| BaseChatModel | 必需 | 用于记忆处理的主模型 |\n| schemas | list[type[BaseModel]] | 必需 | 记忆数据的 Pydantic schema 定义 |\n| instructions | str \\| None | None | 自定义指令模板 |\n| enable_inserts | bool | True | 启用创建新记忆 |\n| enable_updates | bool | True | 启用更新现有记忆 |\n| enable_deletes | bool | True | 启用删除记忆 |\n\n### 记忆存储管理器 (Memory Store Manager)\n\n`create_memory_store_manager` 函数创建支持持久化存储的记忆管理器，支持同步和异步操作。资料来源：[src/langmem/knowledge/extraction.py:1-200]()\n\n#### 配置示例\n\n```python\nfrom langmem import create_memory_store_manager\nfrom langgraph.store.memory import InMemoryStore\nfrom langgraph.func import entrypoint\n\nstore = InMemoryStore(\n index={\n \"dims\": 1536,\n \"embed\": \"openai:text-embedding-3-small\",\n }\n)\n\nmanager = create_memory_store_manager(\n \"anthropic:claude-3-5-sonnet-latest\",\n query_model=\"anthropic:claude-3-5-haiku-latest\",\n query_limit=10,\n namespace=(\"memories\", \"{langgraph_user_id}\"),\n)\n```\n\n#### 命名空间配置\n\n命名空间使用模板占位符，支持运行时配置：\n\n```python\nnamespace = (\"memories\", \"{langgraph_user_id}\")\n```\n\n在调用时通过配置传入实际值：\n\n```python\nconfig = {\"configurable\": {\"langgraph_user_id\": \"user123\"}}\n```\n\n### 记忆搜索器 (Memory Searcher)\n\n`create_memory_searcher` 创建自动生成查询的记忆搜索管道。资料来源：[src/langmem/knowledge/extraction.py:1-200]()\n\n```python\nfrom langmem import create_memory_searcher\n\nsearcher = create_memory_searcher(\n \"anthropic:claude-3-5-sonnet-latest\",\n prompt=\"Search for distinct memories relevant to different aspects of the provided context.\",\n namespace=(\"memories\", \"{langgraph_user_id}\"),\n)\n```\n\n### 记忆管理工具 (Manage Memory Tool)\n\n`create_manage_memory_tool` 创建可集成到 LangGraph ReAct Agent 的记忆管理工具。资料来源：[src/langmem/knowledge/tools.py:1-100]()\n\n```python\nfrom langmem import create_manage_memory_tool\nfrom langgraph.prebuilt import create_react_agent\n\nagent = create_react_agent(\n \"anthropic:claude-3-5-sonnet-latest\",\n tools=[\n create_manage_memory_tool(\n namespace=(\"memories\", \"{langgraph_user_id}\"),\n actions_permitted=[\"create\", \"update\", \"delete\"],\n ),\n ],\n store=store,\n)\n```\n\n### 提示优化器 (Prompt Optimizer)\n\nLangMem 提供多种提示优化策略。资料来源：[src/langmem/prompts/optimization.py:1-150]()\n\n#### 单一提示优化\n\n```python\nfrom langmem import create_prompt_optimizer\n\noptimizer = create_prompt_optimizer(\"anthropic:claude-3-5-sonnet-latest\")\n\nbetter_prompt = await optimizer.ainvoke({\n \"trajectories\": [(conversation, feedback)],\n \"prompt\": \"You are an astronomy expert\",\n})\n```\n\n#### 多提示优化\n\n```python\nfrom langmem import create_multi_prompt_optimizer\n\noptimizer = create_multi_prompt_optimizer(\n \"anthropic:claude-3-5-sonnet-latest\",\n kind=\"metaprompt\", # 或 \"gradient\", \"prompt_memory\"\n config={\"max_reflection_steps\": 3, \"min_reflection_steps\": 1},\n)\n```\n\n#### 优化类型配置\n\n| 类型 | 说明 | 配置参数 |\n|------|------|----------|\n| metaprompt | 元提示优化 | max_reflection_steps, min_reflection_steps |\n| gradient | 梯度下降优化 | gradient_prompt, metaprompt, max_reflection_steps |\n| prompt_memory | 记忆驱动优化 | 无特殊配置 |\n\n### 短期记忆总结\n\n`SummarizationNode` 用于 LangGraph 状态图中的消息总结。资料来源：[src/langmem/short_term/summarization.py:1-100]()\n\n```python\nfrom langmem.short_term import SummarizationNode, RunningSummary\n\nsummarization_node = SummarizationNode(\n model=summarization_model,\n max_tokens=256,\n max_tokens_before_summary=256,\n max_summary_tokens=128,\n)\n```\n\n## 数据类型定义\n\n### Prompt 类型\n\n用于结构化提示管理和优化的 TypedDict。资料来源：[src/langmem/prompts/types.py:1-80]()\n\n```python\nfrom langmem.prompts.types import Prompt\n\nprompt = Prompt(\n name=\"extract_entities\",\n prompt=\"Extract key entities from the text:\",\n update_instructions=\"Make minimal changes\",\n when_to_update=\"If there seem to be errors\",\n)\n```\n\n### AnnotatedTrajectory 类型\n\n包含可选反馈的对话历史记录。资料来源：[src/langmem/prompts/types.py:1-80]()\n\n```python\nfrom langmem.prompts.types import AnnotatedTrajectory\n\ntrajectory = AnnotatedTrajectory(\n messages=[\n {\"role\": \"user\", \"content\": \"What pizza is good?\"},\n {\"role\": \"assistant\", \"content\": \"Try LangPizza\"},\n ],\n feedback={\"developer_feedback\": \"too pushy\", \"score\": 0},\n)\n```\n\n## 架构流程图\n\n### 记忆管理流程\n\n```mermaid\ngraph TD\n A[用户消息] --> B[记忆管理器]\n B --> C{操作类型}\n C -->|创建| D[提取新记忆]\n C -->|更新| E[合并现有记忆]\n C -->|删除| F[移除过时记忆]\n D --> G[存储到向量数据库]\n E --> G\n F --> G\n G --> H[返回结果]\n```\n\n### 提示优化流程\n\n```mermaid\ngraph TD\n A[对话历史] --> B[提示优化器]\n B --> C[元提示优化]\n B --> D[梯度优化]\n B --> E[记忆驱动优化]\n C --> F[优化后的提示]\n D --> F\n E --> F\n```\n\n## 集成配置\n\n### LangGraph 集成\n\nLangMem 可以与 LangGraph 的 ReAct Agent 无缝集成：\n\n```python\nfrom langgraph.prebuilt import create_react_agent\nfrom langmem import create_memory_store_manager\n\nmanager = create_memory_store_manager(\n \"anthropic:claude-3-5-sonnet-latest\",\n namespace=(\"memories\", \"{langgraph_user_id}\"),\n)\n\nagent = create_react_agent(\n \"anthropic:claude-3-5-sonnet-latest\",\n tools=[create_manage_memory_tool(namespace=(\"memories\", \"{langgraph_user_id}\"))],\n store=store,\n)\n```\n\n### 后台执行配置\n\n使用 `ReflectionExecutor` 在后台异步执行记忆处理：\n\n```python\nfrom langmem import create_memory_store_manager, ReflectionExecutor\n\nreflection = ReflectionExecutor(manager, store=store)\n```\n\n## 最佳实践\n\n1. **模型选择**：主模型建议使用功能强大的模型（如 claude-3-5-sonnet），查询模型可使用更快速的版本（如 claude-3-5-haiku）\n2. **命名空间设计**：使用有意义的层级命名空间，便于记忆的组织和检索\n3. **Schema 定义**：为不同类型的记忆定义清晰的 Pydantic Schema，确保数据结构的一致性\n4. **错误处理**：实现适当的错误处理机制，处理 API 超时和配额限制\n5. **异步操作**：优先使用异步方法（ainvoke, aput, asearch）以提高应用性能\n\n---\n\n\n\n## 热路径快速开始\n\n### 相关页面\n\n相关主题：[后台处理快速开始](#page-background-quickstart), [记忆工具](#page-memory-tools)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [docs/docs/hot_path_quickstart.md](https://github.com/langchain-ai/langmem/blob/main/docs/docs/hot_path_quickstart.md)\n- [src/langmem/knowledge/tools.py](https://github.com/langchain-ai/langmem/blob/main/src/langmem/knowledge/tools.py)\n- [src/langmem/prompts/types.py](https://github.com/langchain-ai/langmem/blob/main/src/langmem/prompts/types.py)\n- [src/langmem/knowledge/extraction.py](https://github.com/langchain-ai/langmem/blob/main/src/langmem/knowledge/extraction.py)\n- [src/langmem/short_term/summarization.py](https://github.com/langchain-ai/langmem/blob/main/src/langmem/short_term/summarization.py)\n \n\n# 热路径快速开始\n\n热路径（Hot Path）是指在 LangMem 库中实现的一种快速、简化的方式来为 LangGraph 智能体添加工具和内存管理功能。该功能允许开发者通过最少的配置，快速将内存管理能力集成到现有应用中。\n\n## 功能概述\n\n热路径快速开始模块主要提供以下核心能力：\n\n| 功能 | 描述 |\n|------|------|\n| 记忆管理工具创建 | 通过 `create_manage_memory_tool` 创建可操作的记忆管理工具 |\n| 操作权限控制 | 支持限制允许的操作类型（create、update、delete） |\n| 命名空间管理 | 支持层级化命名空间配置 |\n| Schema 验证 | 支持自定义数据结构 Schema |\n| LangGraph 集成 | 与 LangGraph 的 `create_react_agent` 无缝集成 |\n\n## 核心 API\n\n### create_manage_memory_tool\n\n创建记忆管理工具的主函数，定义在 `src/langmem/knowledge/tools.py` 中。\n\n```python\ndef create_manage_memory_tool(\n namespace: tuple[str, ...] = (\"memories\", \"{langgraph_user_id}\"),\n actions_permitted: typing.Sequence[\n typing.Literal[\"create\", \"update\", \"delete\"]\n ] = (\"create\", \"update\", \"delete\"),\n schema: type[BaseModel] | None = None,\n store: BaseStore | None = None,\n) -> Tool:\n```\n\n**参数说明：**\n\n| 参数 | 类型 | 默认值 | 描述 |\n|------|------|--------|------|\n| `namespace` | `tuple[str, ...]` | `(\"memories\", \"{langgraph_user_id}\")` | 层级化命名空间，支持运行时占位符如 `{langgraph_user_id}` |\n| `actions_permitted` | `Sequence[Literal[\"create\", \"update\", \"delete\"]]` | `(\"create\", \"update\", \"delete\")` | 允许的操作类型列表 |\n| `schema` | `type[BaseModel] \\| None` | `None` | 可选的数据模型，用于验证记忆内容 |\n| `store` | `BaseStore \\| None` | `None` | 底层存储后端 |\n\n资料来源：[src/langmem/knowledge/tools.py:36-43]()\n\n## 工作流程\n\n### 基础集成流程\n\n```mermaid\ngraph TD\n A[创建工具] --> B[配置命名空间]\n B --> C[设置操作权限]\n C --> D[集成到 Agent]\n D --> E[运行时执行]\n```\n\n### 工具执行流程\n\n当智能体调用记忆管理工具时，内部执行以下流程：\n\n```mermaid\nsequenceDiagram\n participant Agent as LangGraph Agent\n participant Tool as Memory Tool\n participant Store as BaseStore\n\n Agent->>Tool: 调用 manage_memory\n Tool->>Tool: 解析命名空间\n Tool->>Tool: 验证操作权限\n alt action == create\n Tool->>Store: put(key, value)\n else action == update\n Tool->>Store: update(key, value)\n else action == delete\n Tool->>Store: delete(key)\n end\n Store-->>Tool: 操作结果\n Tool-->>Agent: 返回结果\n```\n\n## 使用示例\n\n### 基础用法\n\n创建支持所有操作的记忆管理工具：\n\n```python\nfrom langmem.knowledge import create_manage_memory_tool\nfrom langgraph.prebuilt import create_react_agent\n\ntool = create_manage_memory_tool(\n namespace=(\"memories\", \"{langgraph_user_id}\"),\n actions_permitted=[\"create\", \"update\", \"delete\"],\n)\n\nagent = create_react_agent(\n \"anthropic:claude-3-5-sonnet-latest\",\n tools=[tool],\n store=store,\n)\n```\n\n资料来源：[src/langmem/knowledge/tools.py:65-82]()\n\n### 仅创建操作\n\n限制工具只能创建新记忆：\n\n```python\ntool = create_manage_memory_tool(\n namespace=(\"memories\", \"{user_id}\"),\n actions_permitted=[\"create\"], # 仅允许创建\n)\n```\n\n### 配合系统提示词使用\n\n在 LangGraph 中获取记忆并注入到系统提示词：\n\n```python\nfrom langgraph.prebuilt import create_react_agent\nfrom langgraph.config import get_config, get_store\n\ndef prompt(state):\n config = get_config()\n memories = get_store().search(\n (\"memories\", config[\"configurable\"][\"langgraph_user_id\"]),\n )\n system_prompt = f\"\"\"You are a helpful assistant.\n\n{memories}\n\"\"\"\n system_message = {\"role\": \"system\", \"content\": system_prompt}\n return [system_message, *state[\"messages\"]]\n\nagent = create_react_agent(\n \"anthropic:claude-3-5-sonnet-latest\",\n tools=[create_manage_memory_tool(namespace=(\"memories\", \"{langgraph_user_id}\"))],\n store=store,\n)\n```\n\n资料来源：[src/langmem/knowledge/tools.py:85-106]()\n\n## 配置选项详解\n\n### 命名空间配置\n\n命名空间支持层级结构和运行时变量替换：\n\n| 配置方式 | 示例 | 说明 |\n|----------|------|------|\n| 静态命名空间 | `(\"memories\", \"固定用户ID\")` | 使用固定值 |\n| 动态命名空间 | `(\"memories\", \"{langgraph_user_id}\")` | 从配置中读取 |\n| 多级命名空间 | `(\"app\", \"users\", \"{user_id}\", \"memories\")` | 支持任意层级 |\n\n资料来源：[src/langmem/knowledge/tools.py:36]()\n\n### 操作权限矩阵\n\n| 权限组合 | 效果 |\n|----------|------|\n| `[\"create\"]` | 仅能创建新记忆 |\n| `[\"create\", \"update\"]` | 可创建和更新 |\n| `[\"create\", \"update\", \"delete\"]` | 完整 CRUD 操作 |\n| `[\"delete\"]` | 仅能删除（较少使用） |\n\n### 自定义 Schema\n\n可以使用 Pydantic 模型定义记忆的数据结构：\n\n```python\nfrom pydantic import BaseModel\n\nclass UserProfile(BaseModel):\n name: str\n age: int\n preferences: dict[str, str]\n\ntool = create_manage_memory_tool(\n schema=UserProfile,\n actions_permitted=[\"create\", \"update\"],\n)\n```\n\n## 底层实现\n\n### 函数签名与实现\n\n`create_manage_memory_tool` 内部通过组合多个组件实现：\n\n```python\ndef create_manage_memory_tool(...):\n namespacer = utils.NamespaceTemplate(namespace)\n if not actions_permitted:\n raise ValueError(\"actions_permitted cannot be empty\")\n action_type = typing.Literal[actions_permitted]\n default_action = \"create\" if \"create\" in actions_permitted else actions_permitted[0]\n initial_store = store\n\n async def amanage_memory(\n content: typing.Optional[schema] = None,\n action: action_type = default_action,\n *,\n id: typing.Optional[uuid.UUID] = None,\n ):\n store = _get_store(initial_store)\n # ... 执行相应操作\n```\n\n资料来源：[src/langmem/knowledge/tools.py:48-65]()\n\n### 异步管理函数\n\n`amanage_memory` 是核心的异步处理函数：\n\n| 参数 | 类型 | 说明 |\n|------|------|------|\n| `content` | `schema \\| None` | 记忆内容数据 |\n| `action` | `Literal[actions_permitted]` | 要执行的操作 |\n| `id` | `UUID \\| None` | 可选的记忆标识符 |\n\n## 与其他模块的关系\n\n```mermaid\ngraph LR\n A[hot_path_quickstart] --> B[knowledge/tools.py]\n A --> C[prompts/types.py]\n A --> D[knowledge/extraction.py]\n \n B --> E[create_memory_manager]\n B --> F[create_memory_searcher]\n \n C --> G[Prompt 类型定义]\n C --> H[OptimizerInput 类型]\n \n D --> I[MemoryStoreManager]\n D --> J[SearchItem]\n```\n\n### 相关模块\n\n| 模块 | 文件路径 | 用途 |\n|------|----------|------|\n| 记忆管理 | `src/langmem/knowledge/extraction.py` | 提供 `create_memory_manager` 等高级封装 |\n| 记忆搜索 | `src/langmem/knowledge/extraction.py` | 提供 `create_memory_searcher` |\n| 提示词类型 | `src/langmem/prompts/types.py` | 定义 `Prompt`、`AnnotatedTrajectory` 等数据结构 |\n| 短时记忆 | `src/langmem/short_term/summarization.py` | 提供会话总结能力 |\n\n## 最佳实践\n\n### 1. 限制操作权限\n\n根据业务需求限制允许的操作，避免过度权限：\n\n```python\n# 推荐：按需授权\ntool = create_manage_memory_tool(\n actions_permitted=[\"create\"], # 只允许创建\n)\n```\n\n### 2. 使用 Schema 验证\n\n对记忆内容进行结构化定义：\n\n```python\nclass PreferenceMemory(BaseModel):\n preference: str\n context: str\n category: str = \"general\"\n\ntool = create_manage_memory_tool(schema=PreferenceMemory)\n```\n\n### 3. 合理设计命名空间\n\n```python\n# 推荐：用户隔离\nnamespace=(\"app\", \"users\", \"{user_id}\", \"memories\")\n\n# 避免：过于扁平\nnamespace=(\"memories\",)\n```\n\n## 错误处理\n\n| 错误情况 | 处理方式 |\n|----------|----------|\n| `actions_permitted` 为空 | 抛出 `ValueError` |\n| 操作不在允许列表中 | 抛出 `ValueError` |\n| Schema 验证失败 | 由 Pydantic 处理验证错误 |\n| Store 不可用 | 依赖 LangGraph 配置 |\n\n## 总结\n\n热路径快速开始模块为 LangGraph 应用提供了便捷的记忆管理工具创建方式。通过 `create_manage_memory_tool`，开发者可以：\n\n1. **快速集成**：几行代码即可添加工具到智能体\n2. **灵活配置**：通过参数控制操作权限和数据结构\n3. **类型安全**：支持 Schema 验证和类型提示\n4. **无缝衔接**：与 LangGraph 生态完美配合\n\n该模块是 LangMem 库的核心组件之一，适用于需要用户级记忆管理的对话应用场景。\n\n---\n\n\n\n## 后台处理快速开始\n\n### 相关页面\n\n相关主题：[热路径快速开始](#page-hot-path-quickstart), [记忆提取](#page-memory-extraction)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/langmem/knowledge/extraction.py](https://github.com/langchain-ai/langmem/blob/main/src/langmem/knowledge/extraction.py)\n- [src/langmem/prompts/types.py](https://github.com/langchain-ai/langmem/blob/main/src/langmem/prompts/types.py)\n- [src/langmem/short_term/summarization.py](https://github.com/langchain-ai/langmem/blob/main/src/langmem/short_term/summarization.py)\n- [src/langmem/knowledge/tools.py](https://github.com/langchain-ai/langmem/blob/main/src/langmem/knowledge/tools.py)\n- [examples/standalone_examples/README.md](https://github.com/langchain-ai/langmem/blob/main/examples/standalone_examples/README.md)\n \n\n# 后台处理快速开始\n\n## 概述\n\nLangMem 的后台处理功能允许在独立线程中异步执行内存管理操作，从而避免阻塞主应用程序流程。通过 `ReflectionExecutor` 类，开发者可以将记忆提取和管理任务后台化，提升应用程序的响应速度和整体性能。\n\n## 核心组件\n\n### ReflectionExecutor\n\n`ReflectionExecutor` 是 LangMem 提供的后台执行器，用于在后台线程中处理记忆操作。\n\n```mermaid\nclassDiagram\n class ReflectionExecutor {\n +execute(input, config)\n +ainvoke(input, config)\n }\n class MemoryManager {\n +ainvoke(input)\n +search()\n }\n class BaseStore {\n +asearch()\n +aput()\n +adelete()\n }\n ReflectionExecutor --> MemoryManager\n ReflectionExecutor --> BaseStore\n```\n\n**导入路径**：\n```python\nfrom langmem import ReflectionExecutor\n```\n\n## 工作流程\n\n### 异步处理架构\n\n```mermaid\nsequenceDiagram\n participant Agent as 代理\n participant Background as 后台执行器\n participant Store as 存储\n participant Manager as 记忆管理器\n\n Agent->>Agent: 处理消息\n Agent-->>User: 返回响应\n Agent->>Background: 调度后台任务 (after_seconds=0)\n Note over Background,Store: 记忆处理在后台线程执行\n Background->>Manager: 提取/更新记忆\n Manager->>Store: 持久化存储\n```\n\n### 消息流处理\n\n当使用后台处理时，消息的处理流程如下：\n\n1. 用户消息进入主线程\n2. 代理生成响应\n3. 响应与消息一起被发送到后台执行器\n4. 后台执行器调度记忆管理任务\n5. 记忆被提取并存储，不阻塞主线程\n\n## 快速开始指南\n\n### 环境准备\n\n确保已安装必要的依赖：\n\n```bash\nuv venv\nsource .venv/bin/activate\nuv sync\n```\n\n### 基本配置\n\n```python\nfrom langmem import create_memory_store_manager, ReflectionExecutor\nfrom langgraph.store.memory import InMemoryStore\nfrom langgraph.prebuilt import create_react_agent\n\n# 创建向量存储\nstore = InMemoryStore(\n index={\n \"dims\": 1536,\n \"embed\": \"openai:text-embedding-3-small\",\n }\n)\n\n# 创建记忆管理器\nmanager = create_memory_store_manager(\n \"anthropic:claude-3-5-sonnet-latest\",\n namespace=(\"memories\", \"{user_id}\")\n)\n\n# 创建后台执行器\nreflection = ReflectionExecutor(manager, store=store)\n```\n\n### 创建带后台处理的代理\n\n```python\nagent = create_react_agent(\n \"anthropic:claude-3-5-sonnet-latest\",\n tools=[create_manage_memory_tool(namespace=(\"memories\", \"{user_id}\"))],\n store=store,\n)\n\nconfig = {\"configurable\": {\"user_id\": \"user123\"}}\n\n# 处理用户消息\nresult = agent.invoke(\n {\"messages\": [{\"role\": \"user\", \"content\": \"我偏好深色模式\"}]},\n config=config,\n)\n```\n\n## 后台执行配置\n\n### 命名空间配置\n\n后台处理支持动态命名空间，允许为不同用户维护独立的记忆空间：\n\n```python\nnamespace = (\"memories\", \"{langgraph_user_id}\")\n```\n\n**配置参数说明**：\n\n| 参数 | 类型 | 说明 |\n|------|------|------|\n| `namespace` | tuple[str, ...] | 记忆存储的命名空间结构 |\n| `{langgraph_user_id}` | 占位符 | 运行时替换为用户ID |\n\n### 存储配置\n\nInMemoryStore 适用于开发和测试环境：\n\n```python\nstore = InMemoryStore(\n index={\n \"dims\": 1536,\n \"embed\": \"openai:text-embedding-3-small\",\n }\n)\n```\n\n## 独立使用示例\n\n对于不依赖 LangGraph 的应用，可以使用独立的内存管理器：\n\n```python\nfrom langmem import create_memory_manager\nfrom pydantic import BaseModel\nfrom typing import Optional\n\nclass PreferenceMemory(BaseModel):\n preference: str\n context: Optional[str] = None\n\nmanager = create_memory_manager(\n \"anthropic:claude-3-5-sonnet-latest\",\n schemas=[PreferenceMemory],\n)\n\nconversation = [\n {\"role\": \"user\", \"content\": \"I prefer dark mode in all my apps\"},\n {\"role\": \"assistant\", \"content\": \"I'll remember that preference\"},\n]\n\n# 异步执行记忆提取\nupdated_memories = await manager.ainvoke(\n {\"messages\": conversation}\n)\n```\n\n## 架构设计\n\n### 组件关系\n\n```mermaid\ngraph TD\n A[用户消息] --> B[主线程代理]\n B --> C[用户响应]\n B --> D[后台任务调度]\n D --> E[ReflectionExecutor]\n E --> F[MemoryManager]\n F --> G[记忆提取]\n G --> H[BaseStore]\n H --> I[持久化存储]\n```\n\n### 处理阶段\n\n后台处理包含以下阶段：\n\n| 阶段 | 描述 |\n|------|------|\n| 消息传递 | 将对话消息传递给管理器 |\n| 记忆提取 | 从对话中识别相关信息 |\n| 模式识别 | 分析对话模式 |\n| 存储更新 | 将新记忆写入存储 |\n\n## 最佳实践\n\n### 性能优化\n\n1. **设置适当的延迟**：使用 `after_seconds=0` 实现即时后台处理\n2. **分离主模型和查询模型**：使用轻量级模型处理记忆查询\n3. **限制检索数量**：设置合理的 `query_limit`\n\n### 配置示例\n\n```python\nmanager = create_memory_store_manager(\n \"anthropic:claude-3-5-sonnet-latest\", # 主模型\n query_model=\"anthropic:claude-3-5-haiku-latest\", # 查询模型\n query_limit=10, # 检索限制\n namespace=(\"memories\", \"{langgraph_user_id}\"),\n)\n```\n\n## 总结\n\nLangMem 的后台处理功能通过 `ReflectionExecutor` 提供了高效的异步记忆管理能力。开发者可以利用这一功能在不影响主应用响应速度的情况下，自动提取和管理用户记忆。\n\n---\n\n\n\n## 系统架构\n\n### 相关页面\n\n相关主题：[LangMem 概述](#page-overview), [记忆工具](#page-memory-tools), [提示优化](#page-prompt-optimization)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/langmem/__init__.py](https://github.com/langchain-ai/langmem/blob/main/src/langmem/__init__.py)\n- [src/langmem/knowledge/__init__.py](https://github.com/langchain-ai/langmem/blob/main/src/langmem/knowledge/__init__.py)\n- [src/langmem/prompts/__init__.py](https://github.com/langchain-ai/langmem/blob/main/src/langmem/prompts/__init__.py)\n- [langgraph.json](https://github.com/langchain-ai/langmem/blob/main/langgraph.json)\n- [src/langmem/memory/__init__.py](https://github.com/langchain-ai/langmem/blob/main/src/langmem/memory/__init__.py)\n- [src/langmem/evaluation/__init__.py](https://github.com/langchain-ai/langmem/blob/main/src/langmem/evaluation/__init__.py)\n \n\n# 系统架构\n\n## 概述\n\nLangMem 是由 LangChain AI 开发的大语言模型（LLM）记忆管理库，专注于为 AI 应用提供持久化、可检索的记忆存储能力。该库采用模块化架构设计，将记忆管理、提示工程、知识存储等功能解耦，同时通过 LangGraph 实现复杂的状态管理工作流。LangMem 的核心目标是让 AI 应用能够跨会话持久化记忆，并支持多种向量存储后端以实现高效的语义检索。\n\nLangMem 架构遵循以下设计原则：低耦合度、高可扩展性、多后端兼容性以及类型安全。整个系统由多个功能模块组成，包括记忆模块（memory）、知识模块（knowledge）、提示模块（prompts）以及评估模块（evaluation），每个模块都暴露统一的公共接口供外部调用。\n\n## 整体架构图\n\n```mermaid\ngraph TB\n subgraph \"表现层\"\n API[公共 API 入口]\n end\n \n subgraph \"核心模块\"\n MEM[记忆模块
memory]\n KNOW[知识模块
knowledge]\n PROM[提示模块
prompts]\n EVAL[评估模块
evaluation]\n end\n \n subgraph \"基础设施层\"\n LC[LangChain 集成]\n LG[LangGraph 状态机]\n VS[向量存储后端]\n end\n \n API --> MEM\n API --> KNOW\n API --> PROM\n API --> EVAL\n MEM --> LG\n MEM --> VS\n KNOW --> LC\n KNOW --> VS\n PROM --> LG\n EVAL --> LG\n```\n\n## 核心模块架构\n\n### 记忆模块（memory）\n\n记忆模块是 LangMem 的核心组件，负责管理和持久化对话历史与用户偏好信息。该模块实现了多种记忆类，支持不同的存储策略和使用场景。\n\n| 类名 | 功能描述 | 存储方式 |\n|------|----------|----------|\n| `SummaryMemory` | 对话摘要记忆，自动生成对话摘要 | 内存/持久化 |\n| `ConversationMemory` | 完整对话历史记忆 | 向量存储 |\n| `EntityMemory` | 实体信息记忆，提取和管理实体 | 键值存储 |\n| `UserPreferenceMemory` | 用户偏好记忆 | 持久化存储 |\n\n记忆模块通过 LangGraph 实现状态的序列化和反序列化，支持将对话状态持久化到多种后端存储系统。模块内部维护了一个状态图定义，允许开发者定义复杂的状态转换逻辑。\n\n资料来源：[src/langmem/memory/__init__.py:1-50]()\n\n### 知识模块（knowledge）\n\n知识模块提供了结构化知识存储和检索能力，支持将文档、实体和关系持久化到向量数据库中。该模块利用 LangChain 的文档加载器和文本分割工具，实现大规模知识库的管理。\n\n```mermaid\ngraph LR\n DOC[文档输入] --> LOAD[文档加载]\n LOAD --> SPLIT[文本分割]\n SPLIT --> EMBED[向量嵌入]\n EMBED --> STORE[向量存储]\n STORE --> RETRIEVE[相似度检索]\n RETRIEVE --> CONTEXT[上下文输出]\n```\n\n知识模块的核心组件包括：\n- **文档处理器**：负责加载和预处理各类文档格式\n- **嵌入引擎**：将文本转换为高维向量表示\n- **向量存储适配器**：支持多种向量数据库后端\n- **检索器**：实现语义相似度匹配和结果排序\n\n资料来源：[src/langmem/knowledge/__init__.py:1-45]()\n\n### 提示模块（prompts）\n\n提示模块封装了常用的提示模板和提示优化逻辑，帮助开发者构建高效的提示词。该模块提供了模板化提示、动态参数注入和提示链组合等功能。\n\n提示模块的主要类包括：\n- `PromptTemplate`：基础提示模板类\n- `MessagePromptTemplate`：消息格式提示模板\n- `ChatPromptTemplate`：聊天场景专用提示模板\n\n模块支持 Jinja2 风格的模板语法，允许开发者在提示中嵌入变量、控制流和条件逻辑。\n\n资料来源：[src/langmem/prompts/__init__.py:1-38]()\n\n### 评估模块（evaluation）\n\n评估模块提供了记忆系统效果评估的工具集，包括记忆召回率、准确率和相关性等指标的测量。该模块通常与测试框架集成，用于验证记忆系统的性能。\n\n资料来源：[src/langmem/evaluation/__init__.py:1-30]()\n\n## LangGraph 集成架构\n\nLangMem 通过 `langgraph.json` 配置文件定义状态机工作流，实现复杂的状态管理和多轮对话逻辑。\n\n```mermaid\ngraph TD\n START[开始] --> STATE{状态检查}\n STATE -->|新对话| INIT[初始化状态]\n STATE -->|继续对话| LOAD[加载记忆]\n INIT --> STORE[存储状态]\n LOAD --> MERGE[合并历史]\n MERGE --> PROCESS[处理输入]\n STORE --> PROCESS\n PROCESS --> UPDATE[更新记忆]\n UPDATE --> RESPONSE[生成响应]\n RESPONSE --> CHECK{对话结束?}\n CHECK -->|否| STATE\n CHECK -->|是| END[结束]\n```\n\n### 状态定义\n\nLangGraph 配置文件定义了应用的状态结构，包括以下关键字段：\n\n| 字段名 | 类型 | 描述 |\n|--------|------|------|\n| `messages` | List[BaseMessage] | 对话消息历史 |\n| `memory_state` | Dict | 当前记忆状态 |\n| `context` | Dict | 检索到的上下文 |\n| `metadata` | Dict | 元数据信息 |\n\n### 节点与边\n\n工作流由多个节点组成：\n- **retrieve_node**：从向量存储检索相关记忆\n- **update_node**：更新记忆状态\n- **generate_node**：调用 LLM 生成响应\n- **evaluate_node**：评估当前状态质量\n\n资料来源：[langgraph.json:1-100]()\n\n## 公共 API 入口\n\n`src/langmem/__init__.py` 文件作为库的公共入口，导出所有公共 API 和核心类。该模块遵循 LangChain 的导出规范，提供清晰的命名空间组织和类型提示。\n\n```python\n# 主要导出内容\nfrom langmem.memory import (\n SummaryMemory,\n ConversationMemory,\n EntityMemory,\n)\nfrom langmem.knowledge import (\n KnowledgeBase,\n DocumentProcessor,\n)\nfrom langmem.prompts import (\n PromptTemplate,\n ChatPromptTemplate,\n)\n```\n\n所有导出的类和函数都遵循以下规范：\n- 完整的类型注解\n- 详细的文档字符串\n- 统一的错误处理机制\n\n资料来源：[src/langmem/__init__.py:1-60]()\n\n## 数据流架构\n\n### 写入流程\n\n```mermaid\nsequenceDiagram\n participant U as 用户\n participant M as 记忆模块\n participant LG as LangGraph\n participant VS as 向量存储\n participant KB as 知识库\n \n U->>M: 输入消息\n M->>LG: 创建状态\n LG->>LG: 处理状态转换\n LG->>KB: 存储知识\n LG->>VS: 存储向量\n LG->>M: 更新记忆\n M->>U: 确认写入\n```\n\n### 读取流程\n\n```mermaid\nsequenceDiagram\n participant U as 用户\n participant M as 记忆模块\n participant LG as LangGraph\n participant VS as 向量存储\n participant KB as 知识库\n \n U->>M: 查询请求\n M->>LG: 创建检索状态\n LG->>VS: 相似度搜索\n LG->>KB: 知识检索\n VS->>LG: 返回结果\n KB->>LG: 返回上下文\n LG->>M: 合并结果\n M->>U: 返回上下文\n```\n\n## 后端存储架构\n\nLangMem 支持多种向量存储后端，提供了统一的上层抽象接口。\n\n| 后端类型 | 支持功能 | 适用场景 |\n|----------|----------|----------|\n| 内存存储 | 快速原型开发 | 开发调试 |\n| SQLite | 本地持久化 | 小规模应用 |\n| Chroma | 嵌入式向量 | 单机应用 |\n| Pinecone | 云端托管 | 生产环境 |\n| Weaviate | 混合搜索 | 企业级应用 |\n| Qdrant | 高性能检索 | 实时应用 |\n\n存储层采用适配器模式，每种后端都实现了统一的接口：\n- `add_documents()`：添加文档\n- `similarity_search()`：相似度搜索\n- `delete()`：删除文档\n- `update()`：更新文档\n\n## 扩展性设计\n\n### 插件接口\n\nLangMem 通过以下方式支持扩展：\n\n1. **自定义记忆类**：继承基础 `BaseMemory` 类并实现必需方法\n2. **自定义检索器**：实现 `BaseRetriever` 接口\n3. **自定义后端**：实现存储适配器接口\n4. **自定义评估器**：扩展评估指标集\n\n### 配置机制\n\n系统通过以下方式支持灵活配置：\n- 环境变量配置\n- YAML/JSON 配置文件\n- 运行时参数注入\n- 依赖注入容器\n\n## 技术栈总结\n\n| 层级 | 技术选型 | 作用 |\n|------|----------|------|\n| 核心框架 | Python 3.10+ | 开发语言 |\n| LLM 集成 | LangChain | 模型调用抽象 |\n| 状态管理 | LangGraph | 工作流编排 |\n| 类型系统 | Pydantic | 数据验证 |\n| 向量存储 | 多后端支持 | 持久化存储 |\n| 文档处理 | LangChain 生态 | 文本处理 |\n\nLangMem 的架构设计充分考虑了模块化、可扩展性和易用性，通过清晰的层次划分和标准化的接口定义，为开发者提供了构建智能记忆系统的基础设施。\n\n---\n\n\n\n## 记忆工具\n\n### 相关页面\n\n相关主题：[系统架构](#page-system-architecture), [记忆提取](#page-memory-extraction)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/langmem/knowledge/tools.py](https://github.com/langchain-ai/langmem/blob/main/src/langmem/knowledge/tools.py)\n- [src/langmem/knowledge/extraction.py](https://github.com/langchain-ai/langmem/blob/main/src/langmem/knowledge/extraction.py)\n- [src/langmem/knowledge/manager.py](https://github.com/langchain-ai/langmem/blob/main/src/langmem/knowledge/manager.py)\n- [src/langmem/prompts/types.py](https://github.com/langchain-ai/langmem/blob/main/src/langmem/prompts/types.py)\n- [examples/standalone_examples/README.md](https://github.com/langchain-ai/langmem/blob/main/examples/standalone_examples/README.md)\n \n\n# 记忆工具\n\nLangMem 的记忆工具（Memory Tools）是一组用于在 LangGraph 应用中管理长期记忆的函数式工具集。这些工具以 LangChain Tool 的形式实现，允许 AI 助手通过函数调用来创建、更新、删除和搜索记忆内容。\n\n## 概述与核心定位\n\n记忆工具是 LangMem 知识管理系统的两大核心组件之一（另一个是记忆管理器）。与自动化的 `MemoryStoreManager` 不同，记忆工具将记忆的管理权直接交给 AI 代理，使其能够根据对话上下文主动决定何时以及如何操作记忆存储。\n\n### 主要功能特性\n\n| 功能 | 说明 |\n|------|------|\n| 创建记忆 | AI 可主动将重要信息存储为持久记忆 |\n| 更新记忆 | 修改已存在的记忆内容 |\n| 删除记忆 | 移除不再需要的记忆 |\n| 搜索记忆 | 基于语义或精确匹配查找相关记忆 |\n\n资料来源：[src/langmem/knowledge/tools.py:1-50]()\n\n## 架构设计\n\n### 工具类型\n\nLangMem 提供两种主要的记忆工具：\n\n```mermaid\ngraph TD\n A[记忆工具模块] --> B[create_manage_memory_tool]\n A --> C[create_search_memory_tool]\n B --> D[创建/更新/删除]\n C --> E[语义搜索/精确匹配]\n```\n\n- **`create_manage_memory_tool`**：管理工具，用于创建、更新、删除记忆\n- **`create_search_memory_tool`**：搜索工具，用于检索已存储的记忆\n\n资料来源：[src/langmem/knowledge/tools.py:180-250]()\n\n### 与 BaseStore 的集成\n\n记忆工具通过 LangGraph 的 `BaseStore` 接口与底层存储层交互。工具内部会从运行时配置中获取 store 实例：\n\n```mermaid\nsequenceDiagram\n participant Agent as AI代理\n participant Tool as 记忆工具\n participant Store as BaseStore\n participant Config as 运行时配置\n\n Agent->>Tool: 调用工具函数\n Tool->>Config: 获取 store 实例\n Config-->>Tool: BaseStore 实例\n Tool->>Store: 执行存储操作\n Store-->>Tool: 操作结果\n Tool-->>Agent: 返回结果\n```\n\n资料来源：[src/langmem/knowledge/tools.py:230-280]()\n\n## create_manage_memory_tool\n\n`create_manage_memory_tool` 函数创建一个允许 AI 代理管理记忆的 LangChain 工具。\n\n### 函数签名\n\n```python\ndef create_manage_memory_tool(\n namespace: tuple[str, ...] | str,\n *,\n schema: type[BaseModel] | None = None,\n actions_permitted: list[Literal[\"create\", \"update\", \"delete\"]] | None = None,\n instructions: str = \"\",\n store: BaseStore | None = None,\n name: str = \"manage_memory\",\n)\n```\n\n### 参数说明\n\n| 参数 | 类型 | 默认值 | 说明 |\n|------|------|--------|------|\n| `namespace` | `tuple[str, ...] \\| str` | 必需 | 记忆的命名空间路径，支持占位符如 `{langgraph_user_id}` |\n| `schema` | `type[BaseModel] \\| None` | `None` | 记忆内容的数据模型（Pydantic BaseModel） |\n| `actions_permitted` | `list[Literal[\"create\", \"update\", \"delete\"]] \\| None` | `None` | 允许的操作类型列表 |\n| `instructions` | `str` | `\"\"` | 给 AI 的额外使用说明 |\n| `store` | `BaseStore \\| None` | `None` | 底层存储实例 |\n| `name` | `str` | `\"manage_memory\"` | 工具名称 |\n\n资料来源：[src/langmem/knowledge/tools.py:120-175]()\n\n### 命名空间配置\n\n命名空间支持运行时配置替换，通过 `{config_key}` 占位符实现：\n\n```python\nmemory_tool = create_manage_memory_tool(\n namespace=(\"memories\", \"{langgraph_user_id}\", \"user_profile\"),\n)\n```\n\n运行时配置示例：\n\n```python\nconfig = {\"configurable\": {\"langgraph_user_id\": \"user-123\"}}\n# 实际命名空间: (\"memories\", \"user-123\", \"user_profile\")\n```\n\n资料来源：[src/langmem/knowledge/tools.py:140-160]()\n\n### 自定义 Schema\n\n可以通过 Pydantic 模型定义记忆的数据结构：\n\n```python\nfrom pydantic import BaseModel\n\nclass UserProfile(BaseModel):\n name: str\n age: int | None = None\n recent_memories: list[str] = []\n preferences: dict | None = None\n\nmemory_tool = create_manage_memory_tool(\n namespace=(\"memories\", \"{langgraph_user_id}\"),\n schema=UserProfile,\n actions_permitted=[\"create\", \"update\"],\n)\n```\n\n资料来源：[src/langmem/knowledge/tools.py:220-245]()\n\n### 操作限制\n\n通过 `actions_permitted` 参数限制 AI 可执行的操作：\n\n```python\n# 仅允许创建和更新，不允许删除\nmemory_tool = create_manage_memory_tool(\n namespace=(\"memories\", \"{langgraph_user_id}\"),\n actions_permitted=[\"create\", \"update\"],\n)\n```\n\n工具描述会根据允许的操作自动生成：\n\n- 单操作：`\"{操作名} a memory\"`\n- 双操作：`\"{操作1} or {操作2} a memory\"`\n- 多操作：`\"{操作1}, {操作2}, or {操作3} a memory\"`\n\n资料来源：[src/langmem/knowledge/tools.py:265-285]()\n\n## create_search_memory_tool\n\n`create_search_memory_tool` 函数创建一个用于搜索记忆的 LangChain 工具。\n\n### 函数签名\n\n```python\ndef create_search_memory_tool(\n namespace: tuple[str, ...] | str,\n *,\n instructions: str = _MEMORY_SEARCH_INSTRUCTIONS,\n store: BaseStore | None = None,\n response_format: Literal[\"content\", \"content_and_artifact\"] = \"content\",\n name: str = \"search_memory\",\n)\n```\n\n### 参数说明\n\n| 参数 | 类型 | 默认值 | 说明 |\n|------|------|--------|------|\n| `namespace` | `tuple[str, ...] \\| str` | 必需 | 搜索范围的命名空间 |\n| `instructions` | `str` | `\"\"` | 搜索工具的使用说明 |\n| `store` | `BaseStore \\| None` | `None` | 底层存储实例 |\n| `response_format` | `Literal[\"content\", \"content_and_artifact\"]` | `\"content\"` | 返回格式 |\n| `name` | `str` | `\"search_memory\"` | 工具名称 |\n\n资料来源：[src/langmem/knowledge/tools.py:295-340]()\n\n### 返回格式\n\n- **`content`**：仅返回记忆内容（字符串）\n- **`content_and_artifact`**：返回元组 `(serialized_memories, raw_memories)`\n\n```python\nsearch_tool = create_search_memory_tool(\n namespace=(\"memories\", \"{langgraph_user_id}\"),\n response_format=\"content_and_artifact\",\n)\n```\n\n资料来源：[src/langmem/knowledge/tools.py:320-325]()\n\n## 使用示例\n\n### 在 create_react_agent 中使用\n\n将记忆工具集成到 LangGraph 的预构建 ReAct 代理中：\n\n```python\nfrom langgraph.prebuilt import create_react_agent\nfrom langgraph.config import get_config, get_store\nfrom langmem import create_manage_memory_tool\n\ndef prompt(state):\n config = get_config()\n memories = get_store().search(\n (\"memories\", config[\"configurable\"][\"langgraph_user_id\"]),\n )\n system_prompt = f\"\"\"You are a helpful assistant.\n\n{memories}\n\n\"\"\"\n return [{\"role\": \"system\", \"content\": system_prompt}, *state[\"messages\"]]\n\nagent = create_react_agent(\n \"anthropic:claude-3-5-sonnet-latest\",\n tools=[create_manage_memory_tool(\n namespace=(\"memories\", \"{langgraph_user_id}\")\n )],\n store=store,\n)\n\nagent.invoke(\n {\"messages\": [{\"role\": \"user\", \"content\": \"我喜欢用 Python 写后端\"}]},\n config=config,\n)\n```\n\n资料来源：[src/langmem/knowledge/tools.py:45-75]()\n\n### 完整的工作流示例\n\n```mermaid\nsequenceDiagram\n participant User as 用户\n participant Agent as ReAct代理\n participant Tool as 记忆工具\n participant Store as InMemoryStore\n\n User->>Agent: \"我偏好深色模式\"\n Agent->>Tool: manage_memory(content, action=\"create\")\n Tool->>Store: put(namespace, key, value)\n Store-->>Tool: MemoryItem\n Tool-->>Agent: \"已记住您的偏好\"\n Agent-->>User: 响应\n\n User->>Agent: \"我改变了主意\"\n Agent->>Tool: manage_memory(id, action=\"update\")\n Tool->>Store: put(namespace, id, new_value)\n Store-->>Tool: Updated\n Agent-->>User: \"已更新您的偏好\"\n```\n\n资料来源：[src/langmem/knowledge/tools.py:75-110]()\n\n### 在独立应用中使用\n\n记忆工具也可以在 LangGraph 外部的独立应用中使用：\n\n```python\nfrom langmem import create_memory_manager\nfrom langgraph.store.memory import InMemoryStore\nfrom pydantic import BaseModel\n\nclass PreferenceMemory(BaseModel):\n category: str\n preference: str\n context: str\n\nstore = InMemoryStore(\n index={\n \"dims\": 1536,\n \"embed\": \"openai:text-embedding-3-small\",\n }\n)\n\n# 独立使用管理器\nmanager = create_memory_manager(\n \"anthropic:claude-3-5-sonnet-latest\",\n schemas=[PreferenceMemory],\n)\n\nconversation = [\n {\"role\": \"user\", \"content\": \"I prefer dark mode in all my apps\"},\n {\"role\": \"assistant\", \"content\": \"I'll remember that preference\"},\n]\n\nmemories = manager.invoke({\"messages\": conversation})\nprint(memories)\n```\n\n资料来源：[examples/standalone_examples/README.md:1-45]()\n\n## 工具与运行时的绑定\n\n### store 参数\n\n`store` 参数用于指定底层存储。如果为 `None`，工具会在运行时从 LangGraph 的配置上下文中获取 store：\n\n```python\n# 方式一：创建时指定 store\nstore = InMemoryStore(index={\"dims\": 1536, \"embed\": \"openai:text-embedding-3-small\"})\nmanage_tool = create_manage_memory_tool(namespace=(\"mem\", \"{uid}\"), store=store)\n\n# 方式二：运行时从 @entrypoint 获取\n# 在 @entrypoint(store=store) 装饰的函数中，store 会自动可用\n```\n\n资料来源：[src/langmem/knowledge/tools.py:225-240]()\n\n### 命名空间的动态解析\n\n命名空间中的占位符在运行时通过 `configurable` 配置解析：\n\n```python\nconfig = {\n \"configurable\": {\n \"langgraph_user_id\": \"user123\",\n \"team_id\": \"engineering\"\n }\n}\n\n# namespace = (\"memories\", \"{langgraph_user_id}\", \"{team_id}\")\n# 解析为: (\"memories\", \"user123\", \"engineering\")\n```\n\n资料来源：[src/langmem/knowledge/tools.py:145-155]()\n\n## 与记忆管理器的对比\n\n| 特性 | 记忆工具 | 记忆管理器 |\n|------|----------|------------|\n| 控制方式 | AI 主动调用 | 自动处理 |\n| 适用场景 | 需要 AI 自主决策 | 需要自动化流程 |\n| 灵活性 | 高 | 中 |\n| 复杂度 | 低 | 中 |\n| 批量操作 | 不支持 | 支持 |\n\n记忆工具适合需要 AI 自主管理记忆的场景，而记忆管理器（如 `create_memory_manager`、`create_memory_store_manager`）适合需要自动从对话中提取和组织记忆的场景。\n\n资料来源：[src/langmem/knowledge/extraction.py:50-150]()\n\n## 最佳实践\n\n### 1. 限制操作权限\n\n始终通过 `actions_permitted` 限制 AI 可执行的操作，防止意外删除重要记忆：\n\n```python\nmanage_tool = create_manage_memory_tool(\n namespace=(\"memories\", \"{user_id}\"),\n actions_permitted=[\"create\", \"update\"], # 禁止删除\n)\n```\n\n### 2. 使用 Schema 验证\n\n通过 Pydantic schema 确保记忆数据结构的一致性：\n\n```python\nclass Memory(BaseModel):\n content: str\n tags: list[str] = []\n priority: int = 0\n\nmanage_tool = create_manage_memory_tool(\n namespace=(\"memories\", \"{user_id}\"),\n schema=Memory,\n)\n```\n\n### 3. 分离搜索和管理\n\n在复杂应用中，建议分别创建搜索和管理工具：\n\n```python\nfrom langmem import create_manage_memory_tool, create_search_memory_tool\n\nmanage = create_manage_memory_tool(\n namespace=(\"memories\", \"{user_id}\"),\n actions_permitted=[\"create\", \"update\", \"delete\"],\n)\n\nsearch = create_search_memory_tool(\n namespace=(\"memories\", \"{user_id}\"),\n)\n\nagent = create_react_agent(\n model=\"anthropic:claude-3-5-sonnet-latest\",\n tools=[manage, search],\n store=store,\n)\n```\n\n### 4. 提供清晰的说明\n\n通过 `instructions` 参数提供工具使用指导：\n\n```python\nmanage_tool = create_manage_memory_tool(\n namespace=(\"preferences\", \"{user_id}\"),\n instructions=\"仅在用户明确表达偏好时创建记忆，避免过度记录。\",\n)\n```\n\n## 注意事项\n\n1. **store 必须可用**：工具依赖 LangGraph 的 BaseStore，在 `@entrypoint` 或 `create_react_agent` 中使用时会自动注入。\n\n2. **命名空间唯一性**：每个用户的记忆应使用独立的命名空间路径。\n\n3. **异步支持**：工具同时支持同步（`invoke`）和异步（`ainvoke`）调用。\n\n4. **Schema 兼容性**：自定义 schema 必须与已存储的记忆数据结构兼容，否则会导致验证失败。\n\n5. **ID 必填规则**：更新和删除操作需要提供记忆的 UUID，AI 在调用工具时必须包含此参数。\n\n资料来源：[src/langmem/knowledge/tools.py:180-220]()\n\n## 导出清单\n\n```python\n__all__ = [\n \"create_manage_memory_tool\",\n \"create_search_memory_tool\",\n]\n```\n\n资料来源：[src/langmem/knowledge/tools.py:350-355]()\n\n---\n\n\n\n## 记忆提取\n\n### 相关页面\n\n相关主题：[语义记忆管理](#page-semantic-memory), [情景记忆提取](#page-episodic-memory), [后台处理快速开始](#page-background-quickstart)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/langmem/knowledge/extraction.py](https://github.com/langchain-ai/langmem/blob/main/src/langmem/knowledge/extraction.py)\n- [src/langmem/knowledge/tools.py](https://github.com/langchain-ai/langmem/blob/main/src/langmem/knowledge/tools.py)\n- [src/langmem/prompts/types.py](https://github.com/langchain-ai/langmem/blob/main/src/langmem/prompts/types.py)\n- [src/langmem/graphs/semantic.py](https://github.com/langchain-ai/langmem/blob/main/src/langmem/graphs/semantic.py)\n- [src/langmem/short_term/summarization.py](https://github.com/langchain-ai/langmem/blob/main/src/langmem/short_term/summarization.py)\n \n\n# 记忆提取\n\n记忆提取（Memory Extraction）是 langmem 库中用于从对话或交互轨迹中识别、提取和存储有价值信息的核心功能模块。该模块通过大语言模型（LLM）分析对话内容，自动识别用户偏好、关键事实、上下文信息等结构化记忆，并支持持久化存储以便后续检索和使用。\n\n## 核心概念\n\n### 什么是记忆提取\n\n记忆提取是一种自动化的信息处理流程，它从非结构化的对话数据中识别并提取结构化的记忆信息。这些记忆信息经过处理后可以用于：\n\n- 个性化响应生成\n- 上下文连续性维护\n- 用户偏好跟踪\n- 对话状态管理\n\n资料来源：[src/langmem/knowledge/extraction.py:1-50]()\n\n### 记忆类型\n\nlangmem 支持多种类型的记忆提取模式：\n\n| 记忆类型 | 描述 | 适用场景 |\n|---------|------|---------|\n| 实体记忆 | 提取人名、地点、事件等实体信息 | 事实性信息存储 |\n| 偏好记忆 | 记录用户偏好、习惯、偏好设置 | 个性化服务 |\n| 上下文记忆 | 保存对话上下文和会话状态 | 多轮对话支持 |\n| 关系记忆 | 记录实体之间的关系和关联 | 知识图谱构建 |\n\n资料来源：[src/langmem/prompts/types.py:1-80]()\n\n## 架构设计\n\n### 整体架构\n\n```mermaid\ngraph TD\n A[对话输入] --> B[记忆管理器
MemoryManager]\n B --> C{提取模式}\n C -->|LLM分析| D[模式匹配]\n C -->|向量搜索| E[语义检索]\n D --> F[记忆存储]\n E --> F\n F --> G[结构化记忆]\n G --> H[长期存储
MemoryStore]\n G --> I[短期记忆
Summarization]\n```\n\n### 核心组件\n\n| 组件 | 职责 | 文件位置 |\n|------|------|---------|\n| MemoryManager | 记忆提取的主控制器 | extraction.py |\n| MemoryStoreManager | 支持向量存储的记忆管理 | extraction.py |\n| SummarizationNode | 短期记忆压缩节点 | summarization.py |\n| SemanticMemoryGraph | 语义记忆图结构 | semantic.py |\n| create_manage_memory_tool | 记忆管理工具 | tools.py |\n| create_search_memory_tool | 记忆搜索工具 | tools.py |\n\n资料来源：[src/langmem/knowledge/extraction.py:100-200]()\n\n## MemoryManager 详解\n\n### 初始化配置\n\n`create_memory_manager` 函数用于创建记忆管理器实例：\n\n```python\nfrom langmem import create_memory_manager\n\nmanager = create_memory_manager(\n \"anthropic:claude-3-5-sonnet-latest\",\n schemas=[PreferenceMemory], # Pydantic schema 定义\n instructions=\"从对话中提取用户偏好信息\",\n enable_inserts=True,\n enable_updates=True,\n enable_deletes=True,\n)\n```\n\n### 配置参数表\n\n| 参数 | 类型 | 默认值 | 说明 |\n|------|------|--------|------|\n| model | str \\| BaseChatModel | 必填 | 用于记忆提取的 LLM |\n| schemas | list[type[BaseModel]] | None | 记忆数据结构定义 |\n| instructions | str | None | 提取指令提示 |\n| enable_inserts | bool | True | 是否启用插入操作 |\n| enable_updates | bool | True | 是否启用更新操作 |\n| enable_deletes | bool | True | 是否启用删除操作 |\n\n资料来源：[src/langmem/knowledge/extraction.py:200-300]()\n\n### 调用方式\n\n#### 异步调用\n\n```python\nconversation = [\n {\"role\": \"user\", \"content\": \"我偏好深色模式\"},\n {\"role\": \"assistant\", \"content\": \"好的，已记住您的偏好\"},\n]\n\nmemories = await manager.ainvoke(\n {\"messages\": conversation, \"max_steps\": 3}\n)\n```\n\n#### 同步调用\n\n```python\nmemories = manager.invoke({\"messages\": conversation})\n```\n\n资料来源：[src/langmem/knowledge/extraction.py:250-280]()\n\n## MemoryStoreManager 详解\n\n### 概述\n\n`MemoryStoreManager` 是支持向量存储的增强版记忆管理器，集成了语义搜索能力：\n\n```python\nfrom langmem import create_memory_store_manager\nfrom langgraph.store.memory import InMemoryStore\n\nstore = InMemoryStore(\n index={\n \"dims\": 1536,\n \"embed\": \"openai:text-embedding-3-small\",\n }\n)\n\nmanager = create_memory_store_manager(\n \"anthropic:claude-3-5-sonnet-latest\",\n query_model=\"anthropic:claude-3-5-haiku-latest\",\n query_limit=10,\n namespace=(\"memories\", \"{langgraph_user_id}\"),\n store=store,\n)\n```\n\n### 与 MemoryManager 的区别\n\n| 特性 | MemoryManager | MemoryStoreManager |\n|------|---------------|-------------------|\n| 存储后端 | 内存/外部 | 向量存储 |\n| 语义搜索 | ✗ | ✓ |\n| 查询优化 | 基础 | 高级（LLM生成查询） |\n| 适用场景 | 快速原型 | 生产环境 |\n\n资料来源：[src/langmem/knowledge/extraction.py:300-400]()\n\n### 工作流程\n\n```mermaid\nsequenceDiagram\n participant Client\n participant Manager as MemoryStoreManager\n participant QueryLLM\n participant Store as VectorStore\n participant MainLLM\n\n Client->>Manager: 消息输入\n Manager->>QueryLLM: 生成搜索查询\n QueryLLM-->>Manager: 优化后的查询\n Manager->>Store: 语义检索\n Store-->>Manager: 相关记忆\n Manager->>MainLLM: 分析并提取\n MainLLM-->>Manager: 更新后的记忆\n Manager->>Store: 持久化存储\n Manager-->>Client: 提取结果\n```\n\n### 搜索功能\n\n```python\n# 自然语言搜索\nresults = await manager.asearch(\n query=\"用户在医疗领域的偏好\",\n filter={\"type\": \"research_paper\"},\n limit=5,\n)\n\n# 同步搜索\nresults = manager.search(query=\"app preferences\")\n```\n\n资料来源：[src/langmem/knowledge/extraction.py:80-120]()\n\n## 短期记忆压缩\n\n### SummarizationNode\n\n`SummarizationNode` 用于在对话过程中压缩和摘要消息，保持上下文的同时减少 token 消耗：\n\n```python\nfrom langmem.short_term import SummarizationNode, RunningSummary\n\nsummarization_node = SummarizationNode(\n model=summarization_model,\n max_tokens=256,\n max_tokens_before_summary=256,\n max_summary_tokens=128,\n)\n```\n\n### 配置参数\n\n| 参数 | 类型 | 说明 |\n|------|------|------|\n| model | Runnable | 用于摘要生成的 LLM |\n| max_tokens | int | 单次摘要的最大 token 数 |\n| max_tokens_before_summary | int | 触发摘要前的最大 token 数 |\n| max_summary_tokens | int | 摘要内容本身的最大 token 数 |\n| input_messages_key | str | 输入消息的字段名，默认 \"messages\" |\n| output_messages_key | str | 输出消息的字段名，默认 \"messages\" |\n| snapshot_mode | SnapshotMode | 快照模式配置 |\n\n资料来源：[src/langmem/short_term/summarization.py:1-100]()\n\n### 状态更新格式\n\n```json\n{\n \"output_messages_key\": [\n \"<更新的消息列表，包含摘要消息>\"\n ],\n \"context\": {\n \"running_summary\": \"\"\n }\n}\n```\n\n## 语义记忆图\n\n### SemanticMemoryGraph\n\n`SemanticMemoryGraph` 提供基于语义图的记忆组织方式：\n\n```mermaid\ngraph LR\n A[用户输入] --> B[语义解析]\n B --> C[实体识别]\n C --> D[关系抽取]\n D --> E[图结构更新]\n E --> F[记忆节点]\n F --> G[关系边]\n G --> H[语义记忆图]\n```\n\n### 核心功能\n\n| 功能 | 说明 |\n|------|------|\n| 实体提取 | 从对话中识别关键实体 |\n| 关系抽取 | 建立实体间的语义关系 |\n| 图查询 | 支持复杂的关系查询 |\n| 动态更新 | 随对话进行实时更新 |\n\n资料来源：[src/langmem/graphs/semantic.py:1-50]()\n\n## 工具函数\n\n### 记忆管理工具\n\n`create_manage_memory_tool` 创建一个 LangGraph 可用的记忆管理工具：\n\n```python\nfrom langmem import create_manage_memory_tool\n\nmanage_tool = create_manage_memory_tool(\n namespace=(\"memories\", \"{langgraph_user_id}\"),\n schema=UserMemory,\n actions_permitted=[\"create\", \"update\", \"delete\"],\n)\n```\n\n### 参数说明\n\n| 参数 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| namespace | tuple[str, ...] | 是 | 记忆的命名空间路径 |\n| schema | type[BaseModel] | 否 | 记忆的数据结构 |\n| actions_permitted | list | 是 | 允许的操作类型 |\n| store | BaseStore | 否 | 底层存储后端 |\n\n资料来源：[src/langmem/knowledge/tools.py:1-100]()\n\n### 记忆搜索工具\n\n`create_search_memory_tool` 创建一个语义搜索工具：\n\n```python\nfrom langmem import create_search_memory_tool\n\nsearch_tool = create_search_memory_tool(\n namespace=(\"project_memories\", \"{langgraph_user_id}\"),\n)\n\n# 在 LangGraph 中使用\nmemories, _ = await search_tool.ainvoke(\n {\"query\": \"Python preferences\", \"limit\": 5}\n)\n```\n\n## 使用示例\n\n### 基础示例\n\n```python\nfrom langmem import create_memory_manager\nfrom pydantic import BaseModel\n\nclass PreferenceMemory(BaseModel):\n category: str\n preference: str\n context: str\n\nmanager = create_memory_manager(\n \"anthropic:claude-3-5-sonnet-latest\",\n schemas=[PreferenceMemory],\n)\n\nconversation = [\n {\"role\": \"user\", \"content\": \"我偏好所有应用都使用深色模式\"},\n {\"role\": \"assistant\", \"content\": \"好的，我会记住这个偏好\"},\n]\n\nmemories = await manager.ainvoke({\"messages\": conversation})\nprint(memories)\n```\n\n### 带配置的完整示例\n\n```python\nfrom langmem import create_memory_store_manager, ReflectionExecutor\nfrom langgraph.prebuilt import create_react_agent\nfrom langgraph.store.memory import InMemoryStore\nfrom langgraph.func import entrypoint\n\nstore = InMemoryStore(\n index={\n \"dims\": 1536,\n \"embed\": \"openai:text-embedding-3-small\",\n }\n)\n\nmanager = create_memory_store_manager(\n \"anthropic:claude-3-5-sonnet-latest\",\n namespace=(\"memories\", \"{langgraph_user_id}\"),\n)\n\nreflection = ReflectionExecutor(manager, store=store)\nagent = create_react_agent(\n \"anthropic:claude-3-5-sonnet-latest\",\n tools=[create_manage_memory_tool(namespace=(\"memories\", \"{langgraph_user_id}\"))],\n store=store,\n)\n```\n\n### 在 LangGraph 中使用\n\n```python\nfrom langgraph.prebuilt import create_react_agent\nfrom langgraph.config import get_config, get_store\n\ndef prompt(state):\n config = get_config()\n memories = get_store().search(\n (\"memories\", config[\"configurable\"][\"langgraph_user_id\"]),\n )\n system_prompt = f\"\"\"你是一个有帮助的助手。\n <记忆>\n {memories}\n \n \"\"\"\n return [{\"role\": \"system\", \"content\": system_prompt}, *state[\"messages\"]]\n\nagent = create_react_agent(\n \"anthropic:claude-3-5-sonnet-latest\",\n tools=[create_manage_memory_tool(namespace=(\"memories\", \"{langgraph_user_id}\"))],\n)\n\nagent.invoke(\n {\"messages\": [{\"role\": \"user\", \"content\": \"我们决定用 golang 代替 python 做后端\"}]},\n config=config,\n)\n```\n\n资料来源：[src/langmem/knowledge/tools.py:100-200]()\n\n## 数据结构\n\n### AnnotatedTrajectory\n\n用于表示带反馈的对话轨迹：\n\n```python\ntrajectory = AnnotatedTrajectory(\n messages=[\n {\"role\": \"user\", \"content\": \"有什么好的披萨推荐？\"},\n {\"role\": \"assistant\", \"content\": \"推荐尝试 LangPizza™️\"},\n {\"role\": \"user\", \"content\": \"别给我打广告\"},\n {\"role\": \"assistant\", \"content\": \"但你会喜欢的！\"},\n ],\n feedback={\n \"developer_feedback\": \"太激进了\",\n \"score\": 0,\n },\n)\n```\n\n### OptimizerInput\n\n用于单提示优化场景的输入结构：\n\n```python\ninput_data = OptimizerInput(\n trajectories=[\n AnnotatedTrajectory(\n messages=[...],\n feedback=\"应该使用搜索工具\",\n )\n ],\n prompt=Prompt(\n name=\"main_assistant\",\n prompt=\"你是一个有帮助的助手，有搜索工具可用。\",\n update_instructions=\"仅做最小更改，专注于修复错误的地方。\",\n ),\n)\n```\n\n资料来源：[src/langmem/prompts/types.py:50-120]()\n\n## 配置最佳实践\n\n### 命名空间配置\n\n| 占位符 | 说明 | 示例 |\n|--------|------|------|\n| `{langgraph_user_id}` | 用户唯一标识 | memories/user123 |\n| `{session_id}` | 会话标识 | memories/user123/session456 |\n| `{custom_key}` | 自定义键 | memories/user123/custom |\n\n### 性能优化建议\n\n1. **批量处理**：将多个相关对话合并处理\n2. **增量更新**：使用 `enable_updates=True` 避免重复存储\n3. **搜索限制**：设置合理的 `query_limit` 减少检索开销\n4. **摘要压缩**：对于长对话使用 `SummarizationNode` 减少 token\n\n### 安全考虑\n\n- 命名空间隔离：不同用户使用不同命名空间\n- 操作权限：仅启用必要的 CRUD 操作\n- Schema 验证：使用 Pydantic 模型确保数据一致性\n\n## 相关模块\n\n| 模块 | 文件路径 | 用途 |\n|------|----------|------|\n| prompts.types | prompts/types.py | 类型定义和数据结构 |\n| prompts.optimization | prompts/optimization.py | 提示词优化集成 |\n| prompts.prompt | prompts/prompt.py | 提示模板 |\n| prompts.gradient | prompts/gradient.py | 梯度提示优化器 |\n| short_term | short_term/summarization.py | 短期记忆压缩 |\n\n## 总结\n\n记忆提取是 langmem 提供的核心能力之一，它通过结构化的方式从对话中提取有价值的信息，并通过 MemoryManager 和 MemoryStoreManager 两个主要接口提供灵活的存储和检索能力。结合短期记忆压缩和语义搜索功能，langmem 能够构建完整的记忆系统，支持各种需要上下文持久化的 AI 应用场景。\n\n---\n\n\n\n## 提示优化\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/langmem/prompts/optimization.py](https://github.com/langchain-ai/langmem/blob/main/src/langmem/prompts/optimization.py)\n- [src/langmem/prompts/gradient.py](https://github.com/langchain-ai/langmem/blob/main/src/langmem/prompts/gradient.py)\n- [src/langmem/prompts/metaprompt.py](https://github.com/langchain-ai/langmem/blob/main/src/langmem/prompts/metaprompt.py)\n- [src/langmem/prompts/prompt.py](https://github.com/langchain-ai/langmem/blob/main/src/langmem/prompts/prompt.py)\n- [src/langmem/prompts/types.py](https://github.com/langchain-ai/langmem/blob/main/src/langmem/prompts/types.py)\n \n\n# 提示优化\n\n## 概述\n\n提示优化（Prompt Optimization）是 langmem 库中用于自动改进大型语言模型提示词的核心模块。该模块通过分析对话轨迹和反馈信息，自动调整和优化系统提示词，使 AI 代理能够更好地完成特定任务。\n\nlangmem 提供了三种主要的提示优化策略：\n\n| 优化类型 | 说明 | 使用场景 |\n|---------|------|---------|\n| **Gradient（梯度优化）** | 基于假设和推荐进行渐进式调整 | 需要分析失败原因并针对性改进 |\n| **Metaprompt（元提示优化）** | 通过元学习步骤进行深度优化 | 复杂任务需要多次反思 |\n| **Prompt Memory（提示记忆优化）** | 从历史交互中学习成功模式 | 积累经验持续改进 |\n\n## 核心组件\n\n### 类型定义\n\n提示优化模块使用强类型定义确保输入输出的准确性。\n\n#### OptimizerInput\n\n```python\nclass OptimizerInput(TypedDict):\n \"\"\"单提示优化的输入数据结构\"\"\"\n trajectories: typing.Sequence[AnnotatedTrajectory] | str\n prompt: str | Prompt\n```\n\n| 字段 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| `trajectories` | `Sequence[AnnotatedTrajectory] \\| str` | 是 | 对话轨迹列表或字符串描述 |\n| `prompt` | `str \\| Prompt` | 是 | 需要优化的提示词 |\n\n#### MultiPromptOptimizerInput\n\n```python\nclass MultiPromptOptimizerInput(TypedDict):\n \"\"\"多提示优化的输入数据结构\"\"\"\n trajectories: typing.Sequence[AnnotatedTrajectory] | str\n prompts: list[Prompt]\n```\n\n| 字段 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| `trajectories` | `Sequence[AnnotatedTrajectory] \\| str` | 是 | 对话轨迹列表 |\n| `prompts` | `list[Prompt]` | 是 | 需要一起优化的多个提示 |\n\n#### Prompt 结构\n\n```python\nclass Prompt(TypedDict, total=False):\n \"\"\"结构化提示管理\"\"\"\n name: Required[str] # 提示名称\n prompt: Required[str] # 提示内容\n update_instructions: str | None # 更新指令\n when_to_update: str | None # 更新时机\n```\n\n#### AnnotatedTrajectory 结构\n\n```python\nclass AnnotatedTrajectory(typing.NamedTuple):\n \"\"\"带标注的对话轨迹\"\"\"\n messages: typing.Sequence[AnyMessage] # 消息列表\n feedback: dict[str, str | int | bool] | str | None = None # 反馈信息\n```\n\n资料来源：[src/langmem/prompts/types.py:1-80](src/langmem/prompts/types.py)\n\n## API 接口\n\n### 创建单提示优化器\n\n```python\ndef create_prompt_optimizer(\n model: str | BaseChatModel,\n kind: typing.Literal[\"gradient\", \"metaprompt\", \"prompt_memory\"] = \"gradient\",\n *,\n config: typing.Optional[dict] = None,\n) -> Runnable[OptimizerInput, str]\n```\n\n| 参数 | 类型 | 默认值 | 说明 |\n|------|------|--------|------|\n| `model` | `str \\| BaseChatModel` | 必填 | 使用的语言模型 |\n| `kind` | `Literal[\"gradient\", \"metaprompt\", \"prompt_memory\"]` | `\"gradient\"` | 优化策略类型 |\n| `config` | `dict \\| None` | `None` | 优化器配置 |\n\n### 创建多提示优化器\n\n```python\ndef create_multi_prompt_optimizer(\n model: str | BaseChatModel,\n kind: typing.Literal[\"gradient\", \"metaprompt\", \"prompt_memory\"] = \"gradient\",\n *,\n config: typing.Optional[dict] = None,\n) -> Runnable[MultiPromptOptimizerInput, list[Prompt]]\n```\n\n| 参数 | 类型 | 默认值 | 说明 |\n|------|------|--------|------|\n| `model` | `str \\| BaseChatModel` | 必填 | 使用的语言模型 |\n| `kind` | `Literal[\"gradient\", \"metaprompt\", \"prompt_memory\"]` | `\"gradient\"` | 优化策略类型 |\n| `config` | `dict \\| None` | `None` | 优化器配置 |\n\n资料来源：[src/langmem/prompts/optimization.py](src/langmem/prompts/optimization.py)\n\n## 优化策略详解\n\n### 1. 梯度优化（Gradient Optimization）\n\n梯度优化是最基本的优化策略，通过分析对话轨迹中的假设和推荐进行提示词调整。\n\n```mermaid\ngraph TD\n A[输入轨迹和反馈] --> B[生成假设]\n B --> C[提出建议]\n C --> D[应用最小侵入性更改]\n D --> E[输出优化后的提示]\n```\n\n#### 工作流程\n\n1. **假设生成**：分析当前提示在处理对话轨迹时的潜在问题\n2. **建议生成**：基于假设提出具体的调整建议\n3. **应用更改**：仅实施必要的最小更改\n\n#### 配置选项\n\n| 配置项 | 类型 | 默认值 | 说明 |\n|--------|------|--------|------|\n| `max_reflection_steps` | `int` | 3 | 最大反思步数 |\n| `min_reflection_steps` | `int` | 1 | 最小反思步数 |\n| `gradient_prompt` | `str` | 默认模板 | 梯度优化的提示模板 |\n| `metaprompt` | `str` | 默认模板 | 元提示模板 |\n\n资料来源：[src/langmem/prompts/gradient.py](src/langmem/prompts/gradient.py)\n\n#### 使用示例\n\n```python\nfrom langmem import create_prompt_optimizer\n\noptimizer = create_prompt_optimizer(\n \"anthropic:claude-3-5-sonnet-latest\",\n kind=\"gradient\",\n config={\"max_reflection_steps\": 3}\n)\n\nconversation = [\n {\"role\": \"user\", \"content\": \"Tell me about the solar system\"},\n {\"role\": \"assistant\", \"content\": \"The solar system consists of...\"},\n]\nfeedback = {\"clarity\": \"needs more structure\"}\n\ntrajectories = [(conversation, feedback)]\nbetter_prompt = await optimizer.ainvoke(\n {\"trajectories\": trajectories, \"prompt\": \"You are an astronomy expert\"}\n)\n```\n\n### 2. 元提示优化（Metaprompt Optimization）\n\n元提示优化通过多步元学习过程进行深度反思，适合处理复杂的优化任务。\n\n```mermaid\ngraph TD\n A[输入当前提示] --> B[元级反思]\n B --> C{反思步数检查}\n C -->|未达到最小步数| B\n C -->|已达到最小步数| D[生成优化建议]\n D --> E[应用最终优化]\n E --> F[输出优化后的提示]\n```\n\n#### 配置选项\n\n| 配置项 | 类型 | 默认值 | 说明 |\n|--------|------|--------|------|\n| `max_reflection_steps` | `int` | 3 | 最大元学习步数 |\n| `min_reflection_steps` | `int` | 1 | 最小元学习步数 |\n\n#### 使用示例\n\n```python\nfrom langmem import create_prompt_optimizer\n\noptimizer = create_prompt_optimizer(\n \"anthropic:claude-3-5-sonnet-latest\",\n kind=\"metaprompt\",\n config={\"max_reflection_steps\": 3, \"min_reflection_steps\": 1}\n)\n\nconversation = [\n {\"role\": \"user\", \"content\": \"Explain quantum computing\"},\n {\"role\": \"assistant\", \"content\": \"Quantum computing uses...\"},\n]\nfeedback = \"Should include mathematical notation\"\n\ntrajectories = [(conversation, {\"feedback\": feedback})]\nbetter_prompt = await optimizer.ainvoke(\n {\"trajectories\": trajectories, \"prompt\": \"You are a physics tutor\"}\n)\n```\n\n资料来源：[src/langmem/prompts/metaprompt.py](src/langmem/prompts/metaprompt.py)\n\n### 3. 提示记忆优化（Prompt Memory Optimization）\n\n提示记忆优化从历史交互中学习成功模式，识别改进领域，并将学习到的模式应用到新提示中。\n\n```mermaid\ngraph TD\n A[历史轨迹数据] --> B[提取成功模式]\n A --> C[识别改进领域]\n B --> D[应用模式到新提示]\n C --> D\n D --> E[输出优化后的提示]\n```\n\n#### 核心特点\n\n- **模式提取**：从过去的成功交互中提取可复用的模式\n- **反馈分析**：识别反馈中指出的改进机会\n- **知识迁移**：将学习到的知识应用到新的提示优化中\n\n#### 使用示例\n\n```python\nfrom langmem import create_multi_prompt_optimizer\n\noptimizer = create_multi_prompt_optimizer(\n \"anthropic:claude-3-5-sonnet-latest\",\n kind=\"prompt_memory\"\n)\n\nconversation = [\n {\"role\": \"user\", \"content\": \"How do I write a bash script?\"},\n {\"role\": \"assistant\", \"content\": \"Let me explain bash scripting...\"},\n]\nfeedback = \"Response should include a code example\"\n\ntrajectories = [(conversation, {\"feedback\": feedback})]\nprompts = [\n {\"name\": \"explain\", \"prompt\": \"Explain the concept\"},\n {\"name\": \"example\", \"prompt\": \"Provide a practical example\"},\n]\n\nbetter_prompts = await optimizer.ainvoke(\n {\"trajectories\": trajectories, \"prompts\": prompts}\n)\n```\n\n## 提示反射模板\n\n### INSTRUCTION_REFLECTION_PROMPT\n\n用于单提示优化的反射模板：\n\n```python\nINSTRUCTION_REFLECTION_PROMPT = \"\"\"You are helping an AI agent improve. You can do this by changing their system prompt.\n\nThese is their current prompt:\n\n{current_prompt}\n\n\nHere was the agent's trajectory:\n\n{trajectory}\n\n\nHere is the user's feedback:\n\n\n{feedback}\n\n\nHere are instructions for updating the agent's prompt:\n\n\n{instructions}\n\n\n\nBased on this, return an updated prompt\"\"\"\n```\n\n### INSTRUCTION_REFLECTION_MULTIPLE_PROMPT\n\n用于多提示优化的反射模板，支持批量处理多个轨迹：\n\n```python\nINSTRUCTION_REFLECTION_MULTIPLE_PROMPT = \"\"\"You are helping an AI agent improve. You can do this by changing their system prompt.\n\nThese is their current prompt:\n\n{current_prompt}\n\n\nHere are examples of various agent trajectories and associated feedback:\n\n{data}\n\n\nHere are instructions for updating the agent's prompt:\n\n\n{instructions}\n\n\n\nBased on this, return an updated prompt\"\"\"\n```\n\n### GeneralResponse 结构\n\n优化器的返回响应结构：\n\n```python\nclass GeneralResponse(TypedDict):\n logic: str # 推理逻辑\n update_prompt: bool # 是否需要更新\n new_prompt: str # 新提示内容\n```\n\n资料来源：[src/langmem/prompts/prompt.py](src/langmem/prompts/prompt.py)\n\n## 梯度元提示模板\n\n梯度优化使用的默认元提示：\n\n```python\nDEFAULT_GRADIENT_METAPROMPT = \"\"\"You are optimizing a prompt to handle its target task more effectively.\n\n\n{current_prompt}\n\n\nWe hypothesize the current prompt underperforms for these reasons:\n\n\n{hypotheses}\n\n\nBased on these hypotheses, we recommend the following adjustments:\n\n\n{recommendations}\n\n\nRespond with the updated prompt. Remember to ONLY make changes that are clearly necessary. Aim to be minimally invasive:\"\"\"\n```\n\n资料来源：[src/langmem/prompts/gradient.py](src/langmem/prompts/gradient.py)\n\n## GradientPromptOptimizer 类\n\n基于类的梯度提示优化器实现，同时支持同步和异步调用：\n\n```python\nclass GradientPromptOptimizer(Runnable[GradientOptimizerInput, str]):\n \"\"\"\n Class-based Gradient Prompt Optimizer with both sync and async entry points.\n \"\"\"\n \n def __init__(\n self,\n model: Union[str, BaseChatModel],\n config: Optional[GradientOptimizerConfig] = None,\n ):\n self.model = model\n self.config = config or {}\n```\n\n### GradientOptimizerConfig 配置结构\n\n```python\nclass GradientOptimizerConfig(TypedDict, total=False):\n \"\"\"梯度优化器配置\"\"\"\n gradient_prompt: str # 梯度优化提示模板\n metaprompt: str # 元提示模板\n max_reflection_steps: int # 最大反思步数\n min_reflection_steps: int # 最小反思步数\n```\n\n### GradientOptimizerInput 输入结构\n\n```python\nclass GradientOptimizerInput(TypedDict, total=False):\n \"\"\"梯度优化器输入\"\"\"\n trajectories: prompt_types.OptimizerInput | str\n prompt: str | prompt_types.Prompt\n```\n\n## 最佳实践\n\n### 1. 选择合适的优化策略\n\n| 场景 | 推荐策略 |\n|------|---------|\n| 快速迭代 | Gradient（梯度优化） |\n| 复杂任务 | Metaprompt（元提示优化） |\n| 持续学习 | Prompt Memory（提示记忆优化） |\n\n### 2. 配置反思步数\n\n```python\n# 简单任务 - 快速优化\nconfig = {\"max_reflection_steps\": 1, \"min_reflection_steps\": 1}\n\n# 复杂任务 - 深度优化\nconfig = {\"max_reflection_steps\": 5, \"min_reflection_steps\": 2}\n```\n\n### 3. 提供有效反馈\n\n反馈应该包含：\n- 具体的问题描述\n- 期望的行为\n- 评分或等级（可选）\n\n### 4. 多提示协同优化\n\n当多个提示需要保持一致性时，使用 `create_multi_prompt_optimizer`：\n\n```python\nprompts = [\n Prompt(\n name=\"vision_extract\",\n prompt=\"Extract visual details from the image\",\n update_instructions=\"Focus on using vision model capabilities\",\n ),\n Prompt(\n name=\"vision_classify\",\n prompt=\"Classify specific attributes in the image\",\n when_to_update=\"After vision_extract is updated\",\n ),\n]\n```\n\n## 导出接口\n\n提示优化模块的公共 API：\n\n```python\n__all__ = [\n \"create_prompt_optimizer\",\n \"create_multi_prompt_optimizer\",\n \"Prompt\",\n \"AnnotatedTrajectory\",\n \"OptimizerInput\",\n \"MultiPromptOptimizerInput\",\n]\n```\n\n资料来源：[src/langmem/prompts/optimization.py](src/langmem/prompts/optimization.py)\n\n---\n\n\n\n## 语义记忆管理\n\n### 相关页面\n\n相关主题：[情景记忆提取](#page-episodic-memory), [记忆提取](#page-memory-extraction)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [docs/docs/guides/extract_semantic_memories.md](https://github.com/langchain-ai/langmem/blob/main/docs/docs/guides/extract_semantic_memories.md)\n- [src/langmem/graphs/semantic.py](https://github.com/langchain-ai/langmem/blob/main/src/langmem/graphs/semantic.py)\n \n\n# 语义记忆管理\n\n语义记忆管理是 LangMem 框架中用于从对话历史中自动提取、结构化和存储有意义信息的核心模块。它使 AI 系统能够跨会话保留和利用用户偏好、事实知识和上下文信息，从而提供更个性化和连贯的响应体验。\n\n## 核心概念\n\n### 什么是语义记忆\n\n语义记忆是一种结构化的知识表示形式，它从原始对话内容中提取关键信息，并以预定义的数据模式（Schema）进行存储。与简单的文本存储不同，语义记忆具有以下特征：\n\n| 特征 | 描述 |\n|------|------|\n| **结构化** | 使用 Pydantic 模型定义记忆的数据结构 |\n| **可查询** | 支持向量相似性搜索和精确过滤 |\n| **可演进** | 能够根据新信息自动更新现有记忆 |\n| **上下文相关** | 与特定用户或会话命名空间关联 |\n\n### 语义记忆 vs 其他记忆类型\n\n| 类型 | 用途 | 持久性 | 典型实现 |\n|------|------|--------|----------|\n| 语义记忆 | 长期偏好和知识 | 持久化 | `create_memory_store_manager` |\n| 短时记忆 | 当前会话上下文 | 会话级 | `SummarizationNode` |\n| 程序记忆 | 提示优化学习 | 元数据 | `create_prompt_optimizer` |\n\n资料来源：[src/langmem/knowledge/extraction.py:1-50]()\n\n## 架构概述\n\n### 系统组件\n\nLangMem 的语义记忆管理由以下核心组件构成：\n\n```mermaid\ngraph TD\n subgraph \"语义记忆管理系统\"\n A[对话消息] --> B[MemoryStoreManager]\n B --> C[提取器 Extractor]\n C --> D[Schema 验证]\n D --> E[记忆存储 Store]\n F[搜索查询] --> G[QueryLLM]\n G --> H[向量相似度匹配]\n H --> E\n end\n \n subgraph \"LangGraph 集成\"\n E --> I[InMemoryStore]\n I --> J[Agent 上下文]\n J --> A\n end\n```\n\n### 工作流程\n\n```mermaid\nsequenceDiagram\n participant User as 用户\n participant Agent as Agent\n participant Manager as MemoryStoreManager\n participant Extractor as 提取器\n participant Store as 记忆存储\n participant QueryLLM as 查询模型\n\n User->>Agent: 发送消息\n Agent-->>User: 生成响应\n Agent->>Manager: 提交对话历史\n Manager->>Extractor: 提取语义记忆\n Extractor->>Store: 存储/更新记忆\n Note over Store: 记忆持久化\n \n User->>Agent: 新请求\n Agent->>Manager: 搜索相关记忆\n Manager->>QueryLLM: 生成优化查询\n QueryLLM-->>Manager: 相似记忆\n Manager-->>Agent: 上下文记忆\n Agent-->>User: 个性化响应\n```\n\n资料来源：[src/langmem/knowledge/extraction.py:80-120]()\n\n## 核心 API\n\n### 创建语义记忆管理器\n\n```python\nfrom langmem import create_memory_store_manager\nfrom langgraph.store.memory import InMemoryStore\n\nmanager = create_memory_store_manager(\n \"anthropic:claude-3-5-sonnet-latest\", # 主模型\n query_model=\"anthropic:claude-3-5-haiku-latest\", # 查询模型\n query_limit=10,\n namespace=(\"memories\", \"{langgraph_user_id}\"),\n store=InMemoryStore(),\n)\n```\n\n### 参数说明\n\n| 参数 | 类型 | 必需 | 默认值 | 说明 |\n|------|------|------|--------|------|\n| `model` | `str \\| BaseChatModel` | 是 | - | 用于提取和综合的主模型 |\n| `schemas` | `list[type[BaseModel]]` | 否 | - | 记忆数据的 Pydantic Schema |\n| `query_model` | `str \\| BaseChatModel` | 否 | - | 用于生成搜索查询的专用模型 |\n| `query_limit` | `int` | 否 | 5 | 检索的记忆数量上限 |\n| `namespace` | `tuple[str, ...]` | 否 | `(\"memories\",)` | 记忆存储的命名空间 |\n| `store` | `BaseStore` | 否 | - | LangGraph 底层存储 |\n| `instructions` | `str` | 否 | - | 提取和更新指令 |\n| `enable_inserts` | `bool` | 否 | `True` | 允许创建新记忆 |\n| `enable_deletes` | `bool` | 否 | `True` | 允许删除旧记忆 |\n\n资料来源：[src/langmem/knowledge/extraction.py:150-200]()\n\n## Schema 定义\n\n语义记忆使用 Pydantic 模型定义数据结构。以下是典型的 Schema 定义示例：\n\n```python\nfrom pydantic import BaseModel\nfrom typing import Literal\n\nclass PreferenceMemory(BaseModel):\n \"\"\"用户偏好记忆\"\"\"\n category: str # 偏好类别\n preference: str # 具体偏好\n context: str # 上下文信息\n\nclass UserProfile(BaseModel):\n \"\"\"用户档案记忆\"\"\"\n name: str\n age: int | None = None\n recent_memories: list[str] = []\n preferences: dict | None = None\n```\n\n### Schema 配置参数\n\n| 参数 | 说明 |\n|------|------|\n| `total=False` | 所有字段默认为可选 |\n| 字段类型注解 | 定义记忆内容的结构和验证规则 |\n| 默认值 | 为可选字段提供回退值 |\n\n资料来源：[src/langmem/prompts/types.py:1-40]()\n\n## 集成方式\n\n### LangGraph 集成\n\nLangMem 与 LangGraph 的 `@entrypoint` 装饰器无缝集成：\n\n```python\nfrom langmem import create_memory_store_manager\nfrom langgraph.store.memory import InMemoryStore\nfrom langgraph.func import entrypoint\n\nstore = InMemoryStore(\n index={\n \"dims\": 1536,\n \"embed\": \"openai:text-embedding-3-small\",\n }\n)\n\nmanager = create_memory_store_manager(\n \"anthropic:claude-3-5-sonnet-latest\",\n namespace=(\"memories\", \"{langgraph_user_id}\"),\n store=store,\n)\n\n@entrypoint(store=store)\nasync def my_agent(message: str):\n response = {\"role\": \"assistant\", \"content\": \"I'll remember that\"}\n await manager.ainvoke(\n {\"messages\": [{\"role\": \"user\", \"content\": message}, response]}\n )\n return response\n```\n\n### 后台执行模式\n\n对于需要异步处理的场景，可以使用 `ReflectionExecutor`：\n\n```mermaid\ngraph LR\n A[Agent] --> B[处理消息]\n B --> C[返回响应]\n B --> D[调度后台处理]\n D --> E[ReflectionExecutor]\n E --> F[记忆提取]\n F --> G[存储更新]\n```\n\n```python\nfrom langmem import create_memory_store_manager, ReflectionExecutor\n\nreflection = ReflectionExecutor(manager, store=store)\n\n# 在消息处理后调度后台执行\nreflection.schedule_after(agent_response, after_seconds=0)\n```\n\n资料来源：[src/langmem/knowledge/extraction.py:200-250]()\n\n## 搜索和检索\n\n### 默认搜索行为\n\n默认情况下，记忆检索通过直接嵌入新消息进行相似度匹配：\n\n```python\n# 直接使用消息嵌入搜索\nresults = manager.search(config=config)\n```\n\n### LLM 优化查询搜索\n\n使用专用查询模型生成更精确的搜索查询：\n\n```python\nmanager = create_memory_store_manager(\n \"anthropic:claude-3-5-sonnet-latest\",\n query_model=\"anthropic:claude-3-5-haiku-latest\", # 更快的小模型\n query_limit=10,\n namespace=(\"memories\", \"{langgraph_user_id}\"),\n)\n\n# 使用自然语言查询\nresults = manager.search(query=\"app preferences\", config=config)\n```\n\n### 过滤和分页\n\n```python\n# 带过滤条件的搜索\nresults = await manager.asearch(\n query=\"技术偏好\",\n filter={\"category\": \"programming\"},\n limit=10,\n offset=0,\n)\n```\n\n### 搜索结果格式\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| `namespace` | `tuple[str, ...]` | 记忆所属命名空间 |\n| `key` | `str` | 记忆唯一标识符 |\n| `value` | `dict` | 记忆内容数据 |\n| `created_at` | `datetime` | 创建时间戳 |\n| `updated_at` | `datetime` | 更新时间戳 |\n| `score` | `float \\| None` | 相似度分数 |\n\n资料来源：[src/langmem/knowledge/extraction.py:250-300]()\n\n## 默认值机制\n\n当没有找到相关记忆时，可以使用默认值工厂提供回退记忆：\n\n```python\nmanager = create_memory_store_manager(\n \"anthropic:claude-3-5-sonnet-latest\",\n namespace=(\"memories\", \"{langgraph_user_id}\"),\n default=\"Use a concise and professional tone in all responses.\",\n default_factory=UserPreferencesFactory,\n)\n```\n\n### 默认值配置\n\n| 配置方式 | 说明 |\n|----------|------|\n| `default` | 静态默认字符串或 Pydantic 实例 |\n| `default_factory` | 动态生成默认值的函数 |\n\n资料来源：[src/langmem/knowledge/extraction.py:300-350]()\n\n## 操作模式\n\n### 完整模式（默认值）\n\n允许插入、更新和删除记忆：\n\n```python\nmanager = create_memory_manager(\n \"anthropic:claude-3-5-sonnet-latest\",\n schemas=[PreferenceMemory],\n enable_inserts=True,\n enable_updates=True,\n enable_deletes=True, # 完整功能\n)\n```\n\n### 仅插入模式\n\n仅创建新记忆，不修改现有记忆：\n\n```python\nmanager = create_memory_manager(\n \"anthropic:claude-3-5-sonnet-latest\",\n schemas=[PreferenceMemory],\n enable_inserts=True,\n enable_updates=False,\n enable_deletes=False, # 仅插入\n)\n```\n\n### 操作控制参数\n\n| 参数 | 允许的操作 | 典型用例 |\n|------|-----------|----------|\n| `enable_inserts=True` | 创建新记忆 | 首次学习用户偏好 |\n| `enable_updates=True` | 更新现有记忆 | 偏好变化时同步更新 |\n| `enable_deletes=True` | 删除过时记忆 | 清理矛盾或错误记忆 |\n\n## 多步骤提取和综合\n\n对于复杂对话场景，可以配置多步骤处理：\n\n```python\nconversation = [\n {\"role\": \"user\", \"content\": \"I prefer dark mode in all my apps\"},\n {\"role\": \"assistant\", \"content\": \"I'll remember that preference\"},\n]\n\n# 设置最大处理步骤数\nmax_steps = 3\nmemories = await manager.ainvoke(\n {\"messages\": conversation, \"max_steps\": max_steps}\n)\n```\n\n### 处理流程\n\n```mermaid\ngraph TD\n A[对话历史] --> B[步骤 1: 提取]\n B --> C{是否完成?}\n C -->|否| D[生成工具调用]\n D --> E[步骤 2: 执行]\n E --> B\n C -->|是| F[返回记忆结果]\n \n B --> G[保留未修改的现有记忆]\n G --> F\n```\n\n## 命名空间管理\n\n### 运行时命名空间配置\n\n命名空间支持运行时配置变量替换：\n\n```python\nnamespace=(\"memories\", \"{langgraph_user_id}\")\n\n# 配置\nconfig = {\"configurable\": {\"langgraph_user_id\": \"user123\"}}\n# 结果命名空间: (\"memories\", \"user123\")\n```\n\n### 命名空间结构\n\n| 示例 | 说明 |\n|------|------|\n| `(\"memories\",)` | 基础命名空间 |\n| `(\"memories\", \"{user_id}\")` | 用户级别隔离 |\n| `(\"memories\", \"{team_id}\", \"{user_id}\")` | 团队+用户层级 |\n\n## 最佳实践\n\n### 1. Schema 设计\n\n- 为不同类型的记忆创建独立的 Schema\n- 使用描述性的字段名称和类型注解\n- 提供合理的默认值减少空值处理\n\n### 2. 模型选择\n\n| 场景 | 推荐模型配置 |\n|------|-------------|\n| 高质量提取 | 主模型使用 Sonnet-3.5，查询使用 Haiku |\n| 成本优化 | 主模型和查询模型都使用轻量模型 |\n| 快速迭代 | 仅使用主模型，不启用查询优化 |\n\n### 3. 性能考虑\n\n- 使用后台执行处理记忆管理，避免阻塞主流程\n- 合理设置 `query_limit` 避免返回过多不相关记忆\n- 对高频访问的记忆使用短期缓存\n\n### 4. 错误处理\n\n```python\ntry:\n await manager.ainvoke({\"messages\": conversation})\nexcept ValueError as e:\n # Schema 验证失败\n logger.error(f\"记忆验证失败: {e}\")\nexcept Exception as e:\n # 存储操作失败\n logger.error(f\"存储错误: {e}\")\n```\n\n## 完整使用示例\n\n```python\nfrom langmem import create_memory_store_manager\nfrom langgraph.store.memory import InMemoryStore\nfrom langgraph.func import entrypoint\nfrom pydantic import BaseModel\n\nclass PreferenceMemory(BaseModel):\n \"\"\"用户偏好记忆\"\"\"\n category: str\n preference: str\n context: str\n\n# 初始化存储\nstore = InMemoryStore(\n index={\n \"dims\": 1536,\n \"embed\": \"openai:text-embedding-3-small\",\n }\n)\n\n# 创建管理器\nmanager = create_memory_store_manager(\n \"anthropic:claude-3-5-sonnet-latest\",\n schemas=[PreferenceMemory],\n query_model=\"anthropic:claude-3-5-haiku-latest\",\n query_limit=10,\n namespace=(\"memories\", \"{langgraph_user_id}\"),\n store=store,\n)\n\n# 定义 Agent\n@entrypoint(store=store)\nasync def my_agent(message: str):\n response = {\"role\": \"assistant\", \"content\": \"I'll remember that preference\"}\n await manager.ainvoke(\n {\"messages\": [{\"role\": \"user\", \"content\": message}, response]}\n )\n return response\n\n# 执行对话\nconfig = {\"configurable\": {\"langgraph_user_id\": \"user123\"}}\nawait my_agent.ainvoke(\n \"I prefer dark mode in all my apps\",\n config=config,\n)\n\n# 检索记忆\nprint(manager.search(query=\"app preferences\", config=config))\n```\n\n资料来源：[src/langmem/knowledge/extraction.py:50-100]()\n\n## 相关模块\n\n| 模块 | 路径 | 功能 |\n|------|------|------|\n| 知识提取 | `src/langmem/knowledge/extraction.py` | 核心记忆管理逻辑 |\n| 记忆工具 | `src/langmem/knowledge/tools.py` | LangGraph 工具集成 |\n| 提示类型 | `src/langmem/prompts/types.py` | Schema 定义类型 |\n| 短时摘要 | `src/langmem/short_term/summarization.py` | 会话级摘要管理 |\n| 提示优化 | `src/langmem/prompts/optimization.py` | 元学习和优化 |\n\n---\n\n\n\n## 情景记忆提取\n\n### 相关页面\n\n相关主题：[语义记忆管理](#page-semantic-memory), [记忆提取](#page-memory-extraction)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/langmem/knowledge/extraction.py](https://github.com/langchain-ai/langmem/blob/main/src/langmem/knowledge/extraction.py)\n- [src/langmem/knowledge/tools.py](https://github.com/langchain-ai/langmem/blob/main/src/langmem/knowledge/tools.py)\n- [src/langmem/prompts/optimization.py](https://github.com/langchain-ai/langmem/blob/main/src/langmem/prompts/optimization.py)\n- [src/langmem/prompts/types.py](https://github.com/langchain-ai/langmem/blob/main/src/langmem/prompts/types.py)\n- [src/langmem/short_term/summarization.py](https://github.com/langchain-ai/langmem/blob/main/src/langmem/short_term/summarization.py)\n- [examples/standalone_examples/README.md](https://github.com/langchain-ai/langmem/blob/main/examples/standalone_examples/README.md)\n \n\n# 情景记忆提取\n\n## 概述\n\n情景记忆提取（Episodic Memory Extraction）是 LangMem 库的核心功能之一，用于从对话历史中自动识别、提取和管理结构化记忆。该功能使 AI 系统能够持续学习用户偏好、对话模式和环境信息，并在后续交互中智能调用相关记忆来提升个性化服务质量。\n\nLangMem 的情景记忆提取系统基于以下核心设计理念：\n\n- **结构化存储**：记忆以预定义的 Pydantic Schema 形式存储，确保类型安全和数据一致性\n- **增量更新**：支持记忆的创建、更新和删除操作，适应用户偏好的动态变化\n- **智能检索**：提供基于向量相似度和 LLM 查询的混合检索能力\n- **异步处理**：支持后台执行记忆处理，不阻塞主对话流程\n\n资料来源：[src/langmem/knowledge/extraction.py:1-50]()\n\n## 核心组件\n\n### MemoryManager\n\n`MemoryManager` 是情景记忆提取的主控制器，负责协调整个记忆生命周期。\n\n```python\nfrom langmem import create_memory_manager\n\nmanager = create_memory_manager(\n \"anthropic:claude-3-5-sonnet-latest\",\n schemas=[PreferenceMemory],\n)\n```\n\n**关键参数说明**：\n\n| 参数 | 类型 | 说明 |\n|------|------|------|\n| `model` | `str \\| BaseChatModel` | 用于分析和提取记忆的主模型 |\n| `schemas` | `list[type[BaseModel]]` | 记忆数据的 Pydantic Schema 定义 |\n| `instructions` | `str \\| None` | 自定义提取指令 |\n| `enable_inserts` | `bool` | 启用创建新记忆（默认：True） |\n| `enable_updates` | `bool` | 启用更新现有记忆（默认：True） |\n| `enable_deletes` | `bool` | 启用删除过时记忆（默认：True） |\n| `max_steps` | `int` | 最大提取和综合步数（默认：3） |\n\n资料来源：[src/langmem/knowledge/extraction.py:100-150]()\n\n### MemoryStoreManager\n\n`MemoryStoreManager` 扩展了基础记忆管理能力，集成了 LangGraph 的持久化存储层。\n\n```python\nfrom langmem import create_memory_store_manager\nfrom langgraph.store.memory import InMemoryStore\n\nstore = InMemoryStore(\n index={\n \"dims\": 1536,\n \"embed\": \"openai:text-embedding-3-small\",\n }\n)\nmanager = create_memory_store_manager(\n \"anthropic:claude-3-5-sonnet-latest\",\n query_model=\"anthropic:claude-3-5-haiku-latest\",\n query_limit=10,\n namespace=(\"memories\", \"{langgraph_user_id}\"),\n store=store,\n)\n```\n\n资料来源：[src/langmem/knowledge/extraction.py:200-280]()\n\n## 工作流程\n\n### 基础提取流程\n\n```mermaid\nsequenceDiagram\n participant Client\n participant Manager\n participant LLM\n participant Store\n\n Client->>Manager: messages + existing memories\n Manager->>LLM: analyze conversation\n LLM-->>Manager: extraction decisions\n Manager->>Store: apply memory changes\n Store-->>Manager: updated memories\n Manager-->>Client: memory updates\n```\n\n### 带 LLM 查询的检索流程\n\n当需要更精确的记忆检索时，系统会先生成优化查询：\n\n```mermaid\nsequenceDiagram\n participant Client\n participant Manager\n participant QueryLLM\n participant Store\n participant MainLLM\n\n Client->>Manager: messages\n Manager->>QueryLLM: generate search query\n QueryLLM-->>Manager: optimized query\n Manager->>Store: find memories\n Store-->>Manager: memories\n Manager->>MainLLM: analyze & extract\n MainLLM-->>Manager: memory updates\n Manager->>Store: apply changes\n Manager-->>Client: result\n```\n\n资料来源：[src/langmem/knowledge/extraction.py:50-100]()\n\n## 记忆 Schema 定义\n\n### 基本结构\n\nLangMem 使用 Pydantic BaseModel 定义记忆结构：\n\n```python\nfrom pydantic import BaseModel\n\nclass PreferenceMemory(BaseModel):\n \"\"\"用户偏好记忆\"\"\"\n preference: str\n context: str\n category: str = \"general\"\n\nclass UserProfile(BaseModel):\n \"\"\"用户档案记忆\"\"\"\n name: str\n age: int | None = None\n recent_memories: list[str] = []\n preferences: dict | None = None\n```\n\n资料来源：[src/langmem/knowledge/tools.py:1-50]()\n\n### 嵌套 Schema 示例\n\n```python\nclass Memory(BaseModel):\n \"\"\"带类型标签的统一记忆格式\"\"\"\n kind: str\n content: dict[str, Any]\n```\n\n存储后的记忆项包含以下元数据：\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| `namespace` | `tuple[str, ...]` | 记忆的命名空间路径 |\n| `key` | `str` | 记忆的唯一标识符 |\n| `value` | `dict` | 序列化的记忆内容 |\n| `created_at` | `datetime` | 创建时间戳 |\n| `updated_at` | `datetime` | 最后更新时间戳 |\n| `score` | `float \\| None` | 相似度分数（检索时） |\n\n资料来源：[src/langmem/knowledge/tools.py:50-100]()\n\n## 使用方式\n\n### 独立使用\n\n在 LangGraph 外部独立使用记忆管理功能：\n\n```python\nfrom langmem import create_memory_manager\nfrom pydantic import BaseModel\n\nclass PreferenceMemory(BaseModel):\n preference: str\n context: str\n\nmanager = create_memory_manager(\n \"anthropic:claude-3-5-sonnet-latest\",\n schemas=[PreferenceMemory],\n)\n\nconversation = [\n {\"role\": \"user\", \"content\": \"I prefer dark mode in all my apps\"},\n {\"role\": \"assistant\", \"content\": \"I'll remember that preference\"},\n]\n\n# 提取记忆\nmemories = await manager.ainvoke({\"messages\": conversation})\nprint(memories)\n```\n\n资料来源：[examples/standalone_examples/README.md:1-50]()\n\n### 与 LangGraph 集成\n\n在 LangGraph 应用中后台执行记忆处理：\n\n```python\nfrom langmem import create_memory_store_manager, ReflectionExecutor\nfrom langgraph.prebuilt import create_react_agent\nfrom langgraph.store.memory import InMemoryStore\nfrom langgraph.func import entrypoint\n\nstore = InMemoryStore(\n index={\n \"dims\": 1536,\n \"embed\": \"openai:text-embedding-3-small\",\n }\n)\nmanager = create_memory_store_manager(\n \"anthropic:claude-3-5-sonnet-latest\",\n namespace=(\"memories\", \"{user_id}\"),\n)\nreflection = ReflectionExecutor(manager, store=store)\n\n@entrypoint(store=store)\nasync def my_agent(message: str):\n response = {\"role\": \"assistant\", \"content\": \"I'll remember that\"}\n await reflection.ainvoke(\n {\"messages\": [{\"role\": \"user\", \"content\": message}, response]}\n )\n return response\n```\n\n资料来源：[src/langmem/knowledge/extraction.py:280-350]()\n\n### 检索已存储记忆\n\n```python\n# 查看提取的记忆\nprint(manager.search(config=config))\n\n# 自然语言搜索\nresults = await manager.asearch(\n query=\"app preferences\",\n filter={\"type\": \"PreferenceMemory\"},\n limit=5,\n)\n```\n\n## 高级配置\n\n### 仅插入模式\n\n适用于只需要记录新信息、不修改现有记忆的场景：\n\n```python\nmanager = create_memory_manager(\n \"anthropic:claude-3-5-sonnet-latest\",\n schemas=[PreferenceMemory],\n enable_updates=False,\n enable_deletes=False,\n)\n```\n\n### 自定义提取步数\n\n控制 LLM 推理和综合的迭代次数：\n\n```python\n# 设置最大步数\nmax_steps = 3\nmemories = await manager.ainvoke(\n {\"messages\": conversation, \"max_steps\": max_steps}\n)\n```\n\n### 默认记忆值\n\n当没有找到记忆时返回预设默认值：\n\n```python\nmanager = create_memory_store_manager(\n \"anthropic:claude-3-5-sonnet-latest\",\n namespace=(\"memories\", \"{langgraph_user_id}\"),\n default=\"Use a concise and professional tone in all responses.\",\n)\n```\n\n资料来源：[src/langmem/knowledge/extraction.py:350-400]()\n\n## 工具函数\n\n### create_manage_memory_tool\n\n创建可注入 LangGraph Agent 的记忆管理工具：\n\n```python\nfrom langmem import create_manage_memory_tool\nfrom langgraph.prebuilt import create_react_agent\n\nmemory_tool = create_manage_memory_tool(\n namespace=(\"memories\", \"{langgraph_user_id}\"),\n schema=PreferenceMemory,\n actions_permitted=[\"create\", \"update\", \"delete\"],\n instructions=\"Update the existing user profile based on shared information.\",\n)\n\nagent = create_react_agent(\n \"anthropic:claude-3-5-sonnet-latest\",\n tools=[memory_tool],\n store=store,\n)\n```\n\n资料来源：[src/langmem/knowledge/tools.py:100-200]()\n\n### create_search_memory_tool\n\n创建专门用于记忆检索的工具：\n\n```python\nfrom langmem import create_search_memory_tool\n\nsearch_tool = create_search_memory_tool(\n namespace=(\"project_memories\", \"{langgraph_user_id}\"),\n)\n\n# 在工作流中使用\nmemories, _ = await search_tool.ainvoke(\n {\"query\": \"Python preferences\", \"limit\": 5}\n)\n```\n\n### create_memory_searcher\n\n创建独立的记忆搜索流水线：\n\n```python\nfrom langmem import create_memory_searcher\n\nsearcher = create_memory_searcher(\n \"anthropic:claude-3-5-sonnet-latest\",\n prompt=\"Search for distinct memories relevant to different aspects.\",\n namespace=(\"memories\", \"{langgraph_user_id}\"),\n)\n```\n\n资料来源：[src/langmem/knowledge/extraction.py:400-500]()\n\n## 命名空间设计\n\n### 命名空间结构\n\n记忆按照层级化的命名空间组织：\n\n```python\nnamespace = (\"memories\", \"{langgraph_user_id}\")\n# 运行时解析为：(\"memories\", \"user123\")\n```\n\n### 常见命名空间模式\n\n| 用途 | 命名空间示例 |\n|------|-------------|\n| 用户级记忆 | `(\"memories\", \"{user_id}\")` |\n| 线程级记忆 | `(\"memories\", \"{user_id}\", \"threads\", \"{thread_id}\")` |\n| 类型隔离 | `(\"memories\", \"{user_id}\", \"preferences\")` |\n| 项目级记忆 | `(\"project_memories\", \"{project_id}\")` |\n\n### 多 Schema 命名空间\n\n```python\nmemory_tool = create_manage_memory_tool(\n namespace=(\"memories\", \"{langgraph_user_id}\", \"user_profile\"),\n schema=UserProfile,\n)\n```\n\n资料来源：[src/langmem/knowledge/tools.py:200-300]()\n\n## 异步与同步 API\n\n### 异步调用\n\n```python\n# 异步提取\nupdated_memories = await manager.ainvoke(\n {\"messages\": conversation, \"existing\": memories}\n)\n\n# 异步搜索\nresults = await manager.asearch(query=\"preferences\", limit=10)\n\n# 异步存储\nawait manager.aput(\"key\", {\"content\": \"value\"})\n```\n\n### 同步调用\n\n```python\n# 同步提取\nupdated_memories = manager.invoke({\"messages\": conversation})\n\n# 同步搜索\nresults = manager.search(query=\"preferences\", limit=10)\n```\n\n## 与短时记忆的集成\n\nLangMem 同时提供短时记忆（摘要）功能，可与情景记忆协同工作：\n\n```python\nfrom langmem.short_term import SummarizationNode, RunningSummary\n\nsummarization_node = SummarizationNode(\n model=summarization_model,\n max_tokens=256,\n max_tokens_before_summary=256,\n max_summary_tokens=128,\n)\n```\n\n工作流程：\n\n```mermaid\ngraph TD\n A[对话历史] --> B[短时记忆摘要]\n B --> C[情景记忆提取]\n C --> D[结构化记忆存储]\n D --> E[后续对话检索]\n```\n\n资料来源：[src/langmem/short_term/summarization.py:1-100]()\n\n## 最佳实践\n\n### Schema 设计原则\n\n1. **原子性**：每个记忆项应包含最小独立信息单元\n2. **可演进性**：使用可选字段和默认值支持功能扩展\n3. **可检索性**：在 Schema 中包含可用于过滤的分类字段\n\n### 性能优化\n\n1. **选择合适的查询模型**：使用轻量级模型处理检索查询\n2. **设置合理的查询限制**：根据实际需求调整 `query_limit`\n3. **使用命名空间隔离**：避免大规模检索时的性能瓶颈\n\n### 错误处理\n\n```python\ntry:\n result = await manager.ainvoke({\"messages\": conversation})\nexcept Exception as e:\n logger.error(f\"Memory extraction failed: {e}\")\n # 降级策略：使用空记忆继续\n result = []\n```\n\n## 总结\n\n情景记忆提取是 LangMem 库实现持久化上下文管理的核心能力。通过结构化的 Schema 定义、灵活的存储层集成和智能的提取算法，开发者可以轻松构建具有持续学习能力的 AI 应用。该系统既支持独立使用，也与 LangGraph 框架深度集成，满足从简单脚本到复杂生产环境的各种需求。\n\n---\n\n---\n\n## Doramagic 踩坑日志\n\n项目：langchain-ai/langmem\n\n摘要：发现 11 个潜在踩坑项，其中 3 个为 high/blocking；最高优先级：安装坑 - 来源证据：GRAPH_RECURSION_LIMIT。\n\n## 1. 安装坑 · 来源证据：GRAPH_RECURSION_LIMIT\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：GRAPH_RECURSION_LIMIT\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_82b923de03f34d5a9fa8530916b40d14 | https://github.com/langchain-ai/langmem/issues/133 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 2. 安装坑 · 来源证据：Persistence?\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Persistence?\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_b9688483fa44468a96801d46825b040f | https://github.com/langchain-ai/langmem/issues/154 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 3. 安全/权限坑 · 来源证据：Enhance error message when summarization fails due to missing HumanMessage in trimmed window\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Enhance error message when summarization fails due to missing HumanMessage in trimmed window\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_15b3f9c4829745339b470171f005b3df | https://github.com/langchain-ai/langmem/issues/156 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 4. 配置坑 · 可能修改宿主 AI 配置\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。\n- 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。\n- 建议检查：列出会写入的配置文件、目录和卸载/回滚步骤。\n- 防护动作: 涉及宿主配置目录时必须给回滚路径，不能只给安装命令。\n- 证据：capability.host_targets | github_repo:920242883 | https://github.com/langchain-ai/langmem | host_targets=claude, chatgpt\n\n## 5. 能力坑 · 能力判断依赖假设\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：README/documentation is current enough for a first validation pass.\n- 对用户的影响：假设不成立时，用户拿不到承诺的能力。\n- 建议检查：将假设转成下游验证清单。\n- 防护动作: 假设必须转成验证项；没有验证结果前不能写成事实。\n- 证据：capability.assumptions | github_repo:920242883 | https://github.com/langchain-ai/langmem | README/documentation is current enough for a first validation pass.\n\n## 6. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作: 维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | github_repo:920242883 | https://github.com/langchain-ai/langmem | last_activity_observed missing\n\n## 7. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作: 下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | github_repo:920242883 | https://github.com/langchain-ai/langmem | no_demo; severity=medium\n\n## 8. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作: 评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | github_repo:920242883 | https://github.com/langchain-ai/langmem | no_demo; severity=medium\n\n## 9. 安全/权限坑 · 来源证据：Security: OWASP Agent Memory Guard for memory poisoning defense (ASI06)\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Security: OWASP Agent Memory Guard for memory poisoning defense (ASI06)\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_760d72a9519c42a8b1e31d8932383bc2 | https://github.com/langchain-ai/langmem/issues/164 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 10. 维护坑 · issue/PR 响应质量未知\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：issue_or_pr_quality=unknown。\n- 对用户的影响：用户无法判断遇到问题后是否有人维护。\n- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。\n- 防护动作: issue/PR 响应未知时，必须提示维护风险。\n- 证据：evidence.maintainer_signals | github_repo:920242883 | https://github.com/langchain-ai/langmem | issue_or_pr_quality=unknown\n\n## 11. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作: 发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | github_repo:920242883 | https://github.com/langchain-ai/langmem | release_recency=unknown\n\n\n",
"markdown_key": "langmem",
"pages": "draft",
"source_refs": [
{
"evidence_id": "github_repo:920242883",
"kind": "repo",
"supports_claim_ids": [
"claim_identity",
"claim_distribution",
"claim_capability"
],
"url": "https://github.com/langchain-ai/langmem"
},
{
"evidence_id": "art_077cc72d9cfe41168e5ca54ce4148dfd",
"kind": "docs",
"supports_claim_ids": [
"claim_identity",
"claim_distribution",
"claim_capability"
],
"url": "https://github.com/langchain-ai/langmem#readme"
}
],
"summary": "DeepWiki/Human Wiki 完整输出，末尾追加 Discovery Agent 踩坑日志。",
"title": "langmem 说明书",
"toc": [
"https://github.com/langchain-ai/langmem 项目说明书",
"目录",
"LangMem 概述",
"核心定位",
"整体架构",
"核心数据类型",
"长期记忆模块",
"短期记忆模块",
"Doramagic 踩坑日志"
]
}
},
"quality_gate": {
"blocking_gaps": [],
"category_confidence": "medium",
"compile_status": "ready_for_review",
"five_assets_present": true,
"install_sandbox_verified": true,
"missing_evidence": [],
"next_action": "publish to Doramagic.ai project surfaces",
"prompt_preview_boundary_ok": true,
"publish_status": "publishable",
"quick_start_verified": true,
"repo_clone_verified": true,
"repo_commit": "dc1f1e1525f0877458730c6e8088c235e017c873",
"repo_inspection_error": null,
"repo_inspection_files": [
"pyproject.toml",
"README.md",
"uv.lock",
"docs/mkdocs.yml",
"docs/README.md",
"docs/docs/hot_path_quickstart.md",
"docs/docs/background_quickstart.md",
"docs/docs/index.md",
"docs/_scripts/generate_api_reference_links.py",
"docs/_scripts/notebook_hooks.py",
"docs/_scripts/notebook_convert.py",
"docs/docs/reference/tools.md",
"docs/docs/reference/index.md",
"docs/docs/reference/memory.md",
"docs/docs/reference/utils.md",
"docs/docs/reference/.meta.yml",
"docs/docs/reference/short_term.md",
"docs/docs/reference/prompt_optimization.md",
"docs/docs/concepts/conceptual_guide.md",
"docs/docs/guides/use_tools_in_crewai.md",
"docs/docs/guides/optimize_compound_system.md",
"docs/docs/guides/use_tools_in_custom_agent.md",
"docs/docs/guides/memory_tools.md",
"docs/docs/guides/dynamically_configure_namespaces.md",
"docs/docs/guides/extract_semantic_memories.md",
"docs/docs/guides/optimize_memory_prompt.md",
"docs/docs/guides/manage_user_profile.md",
"docs/docs/guides/extract_episodic_memories.md",
"docs/docs/guides/delayed_processing.md",
"docs/docs/guides/summarization.md",
"docs/_scripts/notebook_convert_templates/mdoutput/conf.json",
"examples/standalone_examples/custom_store_example.py",
"examples/standalone_examples/README.md",
"src/langmem/reflection.py",
"src/langmem/utils.py",
"src/langmem/errors.py",
"src/langmem/__init__.py",
"src/langmem/graph_rag.py",
"src/langmem/prompts/optimization.py",
"src/langmem/prompts/_layers.py"
],
"repo_inspection_verified": true,
"review_reasons": [],
"tag_count_ok": true,
"unsupported_claims": []
},
"schema_version": "0.1",
"user_assets": {
"ai_context_pack": {
"asset_id": "ai_context_pack",
"filename": "AI_CONTEXT_PACK.md",
"markdown": "# langmem - Doramagic AI Context Pack\n\n> 定位：安装前体验与判断资产。它帮助宿主 AI 有一个好的开始，但不代表已经安装、执行或验证目标项目。\n\n## 充分原则\n\n- **充分原则，不是压缩原则**：AI Context Pack 应该充分到让宿主 AI 在开工前理解项目价值、能力边界、使用入口、风险和证据来源；它可以分层组织，但不以最短摘要为目标。\n- **压缩策略**：只压缩噪声和重复内容，不压缩会影响判断和开工质量的上下文。\n\n## 给宿主 AI 的使用方式\n\n你正在读取 Doramagic 为 langmem 编译的 AI Context Pack。请把它当作开工前上下文：帮助用户理解适合谁、能做什么、如何开始、哪些必须安装后验证、风险在哪里。不要声称你已经安装、运行或执行了目标项目。\n\n## Claim 消费规则\n\n- **事实来源**：Repo Evidence + Claim/Evidence Graph；Human Wiki 只提供显著性、术语和叙事结构。\n- **事实最低状态**：`supported`\n- `supported`：可以作为项目事实使用，但回答中必须引用 claim_id 和证据路径。\n- `weak`：只能作为低置信度线索，必须要求用户继续核实。\n- `inferred`：只能用于风险提示或待确认问题，不能包装成项目事实。\n- `unverified`：不得作为事实使用，应明确说证据不足。\n- `contradicted`：必须展示冲突来源，不得替用户强行选择一个版本。\n\n## 它最适合谁\n\n- **正在使用 Claude/Codex/Cursor/Gemini 等宿主 AI 的开发者**：README 或插件配置提到多个宿主 AI。 证据：`README.md` Claim：`clm_0002` supported 0.86\n\n## 它能做什么\n\n- **命令行启动或安装流程**（需要安装后验证）：项目文档中存在可执行命令，真实使用需要在本地或宿主环境中运行这些命令。 证据：`README.md` Claim：`clm_0001` supported 0.86\n\n## 怎么开始\n\n- `pip install -U langmem` 证据：`README.md` Claim：`clm_0003` supported 0.86\n\n## 继续前判断卡\n\n- **当前建议**：需要管理员/安全审批\n- **为什么**：继续前可能涉及密钥、账号、外部服务或敏感上下文，建议先经过管理员或安全审批。\n\n### 30 秒判断\n\n- **现在怎么做**：需要管理员/安全审批\n- **最小安全下一步**：先跑 Prompt Preview；若涉及凭证或企业环境，先审批再试装\n- **先别相信**：角色质量和任务匹配不能直接相信。\n- **继续会触碰**：角色选择偏差、命令执行、本地环境或项目文件\n\n### 现在可以相信\n\n- **适合人群线索：正在使用 Claude/Codex/Cursor/Gemini 等宿主 AI 的开发者**（supported）：有 supported claim 或项目证据支撑，但仍不等于真实安装效果。 证据：`README.md` Claim：`clm_0002` supported 0.86\n- **能力存在：命令行启动或安装流程**（supported）：可以相信项目包含这类能力线索；是否适合你的具体任务仍要试用或安装后验证。 证据：`README.md` Claim：`clm_0001` supported 0.86\n- **存在 Quick Start / 安装命令线索**（supported）：可以相信项目文档出现过启动或安装入口；不要因此直接在主力环境运行。 证据：`README.md` Claim：`clm_0003` supported 0.86\n\n### 现在还不能相信\n\n- **角色质量和任务匹配不能直接相信。**（unverified）：角色库证明有很多角色，不证明每个角色都适合你的具体任务，也不证明角色能产生高质量结果。\n- **不能把角色文案当成真实执行能力。**（unverified）：安装前只能判断角色描述和任务画像是否匹配，不能证明它能在宿主 AI 里完成任务。\n- **真实输出质量不能在安装前相信。**（unverified）：Prompt Preview 只能展示引导方式，不能证明真实项目中的结果质量。\n- **宿主 AI 版本兼容性不能在安装前相信。**（unverified）：Claude、Cursor、Codex、Gemini 等宿主加载规则和版本差异必须在真实环境验证。\n- **不会污染现有宿主 AI 行为，不能直接相信。**（inferred）：Skill、plugin、AGENTS/CLAUDE/GEMINI 指令可能改变宿主 AI 的默认行为。\n- **可安全回滚不能默认相信。**（unverified）：除非项目明确提供卸载和恢复说明，否则必须先在隔离环境验证。\n- **真实安装后是否与用户当前宿主 AI 版本兼容？**（unverified）：兼容性只能通过实际宿主环境验证。\n- **项目输出质量是否满足用户具体任务？**（unverified）：安装前预览只能展示流程和边界，不能替代真实评测。\n\n### 继续会触碰什么\n\n- **角色选择偏差**：用户对任务应该由哪个专家角色处理的判断。 原因：选错角色会让 AI 从错误专业视角回答，浪费时间或误导决策。\n- **命令执行**：包管理器、网络下载、本地插件目录、项目配置或用户主目录。 原因：运行第一条命令就可能产生环境改动；必须先判断是否值得跑。 证据：`README.md`\n- **本地环境或项目文件**：安装结果、插件缓存、项目配置或本地依赖目录。 原因：安装前无法证明写入范围和回滚方式，需要隔离验证。 证据：`README.md`\n- **环境变量 / API Key**：项目入口文档明确出现 API key、token、secret 或账号凭证配置。 原因：如果真实安装需要凭证，应先使用测试凭证并经过权限/合规判断。 证据：`README.md`, `docs/docs/background_quickstart.md`, `docs/docs/hot_path_quickstart.md`, `src/langmem/knowledge/extraction.py`\n- **宿主 AI 上下文**：AI Context Pack、Prompt Preview、Skill 路由、风险规则和项目事实。 原因：导入上下文会影响宿主 AI 后续判断，必须避免把未验证项包装成事实。\n\n### 最小安全下一步\n\n- **先跑 Prompt Preview**：先用交互式试用验证任务画像和角色匹配，不要先导入整套角色库。（适用：任何项目都适用，尤其是输出质量未知时。）\n- **只在隔离目录或测试账号试装**：避免安装命令污染主力宿主 AI、真实项目或用户主目录。（适用：存在命令执行、插件配置或本地写入线索时。）\n- **不要使用真实生产凭证**：环境变量/API key 一旦进入宿主或工具链，可能产生账号和合规风险。（适用：出现 API、TOKEN、KEY、SECRET 等环境线索时。）\n- **安装后只验证一个最小任务**：先验证加载、兼容、输出质量和回滚，再决定是否深用。（适用：准备从试用进入真实工作流时。）\n\n### 退出方式\n\n- **保留安装前状态**：记录原始宿主配置和项目状态，后续才能判断是否可恢复。\n- **保留原始角色选择记录**：如果输出偏题，可以回到任务画像阶段重新选择角色，而不是继续沿着错误角色推进。\n- **记录安装命令和写入路径**：没有明确卸载说明时，至少要知道哪些目录或配置需要手动清理。\n- **准备撤销测试 API key 或 token**：测试凭证泄露或误用时，可以快速止损。\n- **如果没有回滚路径，不进入主力环境**：不可回滚是继续前阻断项，不应靠信任或运气继续。\n\n## 哪些只能预览\n\n- 解释项目适合谁和能做什么\n- 基于项目文档演示典型对话流程\n- 帮助用户判断是否值得安装或继续研究\n\n## 哪些必须安装后验证\n\n- 真实安装 Skill、插件或 CLI\n- 执行脚本、修改本地文件或访问外部服务\n- 验证真实输出质量、性能和兼容性\n\n## 边界与风险判断卡\n\n- **把安装前预览误认为真实运行**：用户可能高估项目已经完成的配置、权限和兼容性验证。 处理方式：明确区分 prompt_preview_can_do 与 runtime_required。 Claim：`clm_0004` inferred 0.45\n- **命令执行会修改本地环境**：安装命令可能写入用户主目录、宿主插件目录或项目配置。 处理方式：先在隔离环境或测试账号中运行。 证据：`README.md` Claim：`clm_0005` supported 0.86\n- **待确认**：真实安装后是否与用户当前宿主 AI 版本兼容？。原因：兼容性只能通过实际宿主环境验证。\n- **待确认**：项目输出质量是否满足用户具体任务？。原因：安装前预览只能展示流程和边界，不能替代真实评测。\n- **待确认**：安装命令是否需要网络、权限或全局写入？。原因：这影响企业环境和个人环境的安装风险。\n\n## 开工前工作上下文\n\n### 加载顺序\n\n- 先读取 how_to_use.host_ai_instruction，建立安装前判断资产的边界。\n- 读取 claim_graph_summary，确认事实来自 Claim/Evidence Graph，而不是 Human Wiki 叙事。\n- 再读取 intended_users、capabilities 和 quick_start_candidates，判断用户是否匹配。\n- 需要执行具体任务时，优先查 role_skill_index，再查 evidence_index。\n- 遇到真实安装、文件修改、网络访问、性能或兼容性问题时，转入 risk_card 和 boundaries.runtime_required。\n\n### 任务路由\n\n- **命令行启动或安装流程**：先说明这是安装后验证能力，再给出安装前检查清单。 边界：必须真实安装或运行后验证。 证据：`README.md` Claim：`clm_0001` supported 0.86\n\n### 上下文规模\n\n- 文件总数：81\n- 重要文件覆盖：35/81\n- 证据索引条目：34\n- 角色 / Skill 条目：24\n\n### 证据不足时的处理\n\n- **missing_evidence**：说明证据不足，要求用户提供目标文件、README 段落或安装后验证记录；不要补全事实。\n- **out_of_scope_request**：说明该任务超出当前 AI Context Pack 证据范围，并建议用户先查看 Human Manual 或真实安装后验证。\n- **runtime_request**：给出安装前检查清单和命令来源，但不要替用户执行命令或声称已执行。\n- **source_conflict**：同时展示冲突来源，标记为待核实，不要强行选择一个版本。\n\n## Prompt Recipes\n\n### 适配判断\n\n- 目标：判断这个项目是否适合用户当前任务。\n- 预期输出：适配结论、关键理由、证据引用、安装前可预览内容、必须安装后验证内容、下一步建议。\n\n```text\n请基于 langmem 的 AI Context Pack，先问我 3 个必要问题，然后判断它是否适合我的任务。回答必须包含：适合谁、能做什么、不能做什么、是否值得安装、证据来自哪里。所有项目事实必须引用 evidence_refs、source_paths 或 claim_id。\n```\n\n### 安装前体验\n\n- 目标：让用户在安装前感受核心工作流，同时避免把预览包装成真实能力或营销承诺。\n- 预期输出：一段带边界标签的体验剧本、安装后验证清单和谨慎建议；不含真实运行承诺或强营销表述。\n\n```text\n请把 langmem 当作安装前体验资产，而不是已安装工具或真实运行环境。\n\n请严格输出四段：\n1. 先问我 3 个必要问题。\n2. 给出一段“体验剧本”：用 [安装前可预览]、[必须安装后验证]、[证据不足] 三种标签展示它可能如何引导工作流。\n3. 给出安装后验证清单：列出哪些能力只有真实安装、真实宿主加载、真实项目运行后才能确认。\n4. 给出谨慎建议：只能说“值得继续研究/试装”“先补充信息后再判断”或“不建议继续”，不得替项目背书。\n\n硬性边界：\n- 不要声称已经安装、运行、执行测试、修改文件或产生真实结果。\n- 不要写“自动适配”“确保通过”“完美适配”“强烈建议安装”等承诺性表达。\n- 如果描述安装后的工作方式，必须使用“如果安装成功且宿主正确加载 Skill，它可能会……”这种条件句。\n- 体验剧本只能写成“示例台词/假设流程”：使用“可能会询问/可能会建议/可能会展示”，不要写“已写入、已生成、已通过、正在运行、正在生成”。\n- Prompt Preview 不负责给安装命令；如用户准备试装，只能提示先阅读 Quick Start 和 Risk Card，并在隔离环境验证。\n- 所有项目事实必须来自 supported claim、evidence_refs 或 source_paths；inferred/unverified 只能作风险或待确认项。\n\n```\n\n### 角色 / Skill 选择\n\n- 目标：从项目里的角色或 Skill 中挑选最匹配的资产。\n- 预期输出：候选角色或 Skill 列表，每项包含适用场景、证据路径、风险边界和是否需要安装后验证。\n\n```text\n请读取 role_skill_index，根据我的目标任务推荐 3-5 个最相关的角色或 Skill。每个推荐都要说明适用场景、可能输出、风险边界和 evidence_refs。\n```\n\n### 风险预检\n\n- 目标：安装或引入前识别环境、权限、规则冲突和质量风险。\n- 预期输出：环境、权限、依赖、许可、宿主冲突、质量风险和未知项的检查清单。\n\n```text\n请基于 risk_card、boundaries 和 quick_start_candidates，给我一份安装前风险预检清单。不要替我执行命令，只说明我应该检查什么、为什么检查、失败会有什么影响。\n```\n\n### 宿主 AI 开工指令\n\n- 目标：把项目上下文转成一次对话开始前的宿主 AI 指令。\n- 预期输出：一段边界明确、证据引用明确、适合复制给宿主 AI 的开工前指令。\n\n```text\n请基于 langmem 的 AI Context Pack，生成一段我可以粘贴给宿主 AI 的开工前指令。这段指令必须遵守 not_runtime=true，不能声称项目已经安装、运行或产生真实结果。\n```\n\n\n## 角色 / Skill 索引\n\n- 共索引 24 个角色 / Skill / 项目文档条目。\n\n- **Setup**（project_doc）：To setup requirements for building docs you can run: 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/README.md`\n- **LangMem**（project_doc）：LangMem helps agents learn and adapt from their interactions over time. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`README.md`\n- **Standalone Examples**（project_doc）：This directory contains examples demonstrating how to use LangMem independently of LangGraph's context. These examples show how to integrate LangMem into your own applications and frameworks. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`examples/standalone_examples/README.md`\n- **Background Quickstart Guide**（project_doc）：Get started processing memories \"in the background\". 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/docs/background_quickstart.md`\n- **Long-term Memory in LLM Applications**（project_doc）：Long-term Memory in LLM Applications 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/docs/concepts/conceptual_guide.md`\n- **Delayed Background Memory Processing**（project_doc）：Process memories during conversation quiet periods 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/docs/guides/delayed_processing.md`\n- **How to configure dynamic namespaces**（project_doc）：How to configure dynamic namespaces 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/docs/guides/dynamically_configure_namespaces.md`\n- **How to Extract Episodic Memories**（project_doc）：Need your agent to learn from experience? Here's how to use LangMem for experience replay—capturing not just what happened, but the complete chain of thought that led to success. While semantic memory ./extract semantic memories.md builds knowledge \"what\" , episodic memory captures expertise \"how\" . 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/docs/guides/extract_episodic_memories.md`\n- **How to Extract Semantic Memories**（project_doc）：Need to extract multiple related facts from conversations? Here's how to use LangMem's collection pattern for semantic memories. For single-document patterns like user profiles, see Manage User Profile ./manage user profile.md . 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/docs/guides/extract_semantic_memories.md`\n- **How to Manage User Profiles**（project_doc）：User profiles help your LLM maintain consistent, up-to-date information about users across conversations. Unlike semantic memory collections ./extract semantic memories.md which track evolving knowledge, profiles focus on maintaining a concise, structured representation of the user or the agent itself . 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/docs/guides/manage_user_profile.md`\n- **How to Use Memory Tools**（project_doc）：LangMem provides tools that let your agent store and search memories in a LangGraph store. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/docs/guides/memory_tools.md`\n- **How to Optimize Multiple Prompts**（project_doc）：Optimize multiple prompts in a system based on conversation logs and feedback. This algorithm seeks to do three things: 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/docs/guides/optimize_compound_system.md`\n- **How to Optimize a Prompt**（project_doc）：Update system prompts based on conversation logs or agent trajectories. Feed past conversations and feedback into an optimizer to fix common issues like missed requirements or poor response structure. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/docs/guides/optimize_memory_prompt.md`\n- **How to Manage Long Context with Summarization**（project_doc）：How to Manage Long Context with Summarization 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/docs/guides/summarization.md`\n- **How to Use Memory Tools in CrewAI**（project_doc）：LangMem's memory tools let your CrewAI agents store and search memories, enabling persistent knowledge across conversations. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/docs/guides/use_tools_in_crewai.md`\n- **How to Use Memory Tools in Custom Agents**（project_doc）：How to Use Memory Tools in Custom Agents 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/docs/guides/use_tools_in_custom_agent.md`\n- **Hot Path Quickstart Guide**（project_doc）：Get started with LangMem 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/docs/hot_path_quickstart.md`\n- **Index**（project_doc）： 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/docs/index.md`\n- **API Reference**（project_doc）：API reference for LangMem 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/docs/reference/index.md`\n- **Memory API Reference**（project_doc）：::: langmem handler: python options: members: - create memory manager - create memory store manager - MemoryStoreManager 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/docs/reference/memory.md`\n- **Prompt Optimization API Reference**（project_doc）：::: langmem handler: python options: members: - create prompt optimizer - create multi prompt optimizer 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/docs/reference/prompt_optimization.md`\n- **Short Term Memory API Reference**（project_doc）：::: langmem.short term handler: python options: members: - summarize messages - SummarizationNode - SummarizationResult - RunningSummary 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/docs/reference/short_term.md`\n- **Memory Tools API Reference**（project_doc）：::: langmem handler: python options: members: - create manage memory tool - create search memory tool 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/docs/reference/tools.md`\n- **Utilities API Reference**（project_doc）：::: langmem.utils handler: python options: members: - NamespaceTemplate 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/docs/reference/utils.md`\n\n## 证据索引\n\n- 共索引 34 条证据。\n\n- **Setup**（documentation）：To setup requirements for building docs you can run: 证据：`docs/README.md`\n- **LangMem**（documentation）：LangMem helps agents learn and adapt from their interactions over time. 证据：`README.md`\n- **Standalone Examples**（documentation）：This directory contains examples demonstrating how to use LangMem independently of LangGraph's context. These examples show how to integrate LangMem into your own applications and frameworks. 证据：`examples/standalone_examples/README.md`\n- **License**（source_file）：Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files the \"Software\" , to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: 证据：`LICENSE`\n- **Background Quickstart Guide**（documentation）：Memories can be created in two ways: 证据：`docs/docs/background_quickstart.md`\n- **Long-term Memory in LLM Applications**（documentation）：Long-term Memory in LLM Applications 证据：`docs/docs/concepts/conceptual_guide.md`\n- **Delayed Background Memory Processing**（documentation）：Delayed Background Memory Processing 证据：`docs/docs/guides/delayed_processing.md`\n- **How to configure dynamic namespaces**（documentation）：How to configure dynamic namespaces 证据：`docs/docs/guides/dynamically_configure_namespaces.md`\n- **How to Extract Episodic Memories**（documentation）：Need your agent to learn from experience? Here's how to use LangMem for experience replay—capturing not just what happened, but the complete chain of thought that led to success. While semantic memory ./extract semantic memories.md builds knowledge \"what\" , episodic memory captures expertise \"how\" . 证据：`docs/docs/guides/extract_episodic_memories.md`\n- **How to Extract Semantic Memories**（documentation）：Need to extract multiple related facts from conversations? Here's how to use LangMem's collection pattern for semantic memories. For single-document patterns like user profiles, see Manage User Profile ./manage user profile.md . 证据：`docs/docs/guides/extract_semantic_memories.md`\n- **How to Manage User Profiles**（documentation）：User profiles help your LLM maintain consistent, up-to-date information about users across conversations. Unlike semantic memory collections ./extract semantic memories.md which track evolving knowledge, profiles focus on maintaining a concise, structured representation of the user or the agent itself . 证据：`docs/docs/guides/manage_user_profile.md`\n- **How to Use Memory Tools**（documentation）：LangMem provides tools that let your agent store and search memories in a LangGraph store. 证据：`docs/docs/guides/memory_tools.md`\n- **How to Optimize Multiple Prompts**（documentation）：Optimize multiple prompts in a system based on conversation logs and feedback. This algorithm seeks to do three things: 证据：`docs/docs/guides/optimize_compound_system.md`\n- **How to Optimize a Prompt**（documentation）：Update system prompts based on conversation logs or agent trajectories. Feed past conversations and feedback into an optimizer to fix common issues like missed requirements or poor response structure. 证据：`docs/docs/guides/optimize_memory_prompt.md`\n- **How to Manage Long Context with Summarization**（documentation）：How to Manage Long Context with Summarization 证据：`docs/docs/guides/summarization.md`\n- **How to Use Memory Tools in CrewAI**（documentation）：LangMem's memory tools let your CrewAI agents store and search memories, enabling persistent knowledge across conversations. 证据：`docs/docs/guides/use_tools_in_crewai.md`\n- **How to Use Memory Tools in Custom Agents**（documentation）：How to Use Memory Tools in Custom Agents 证据：`docs/docs/guides/use_tools_in_custom_agent.md`\n- **Hot Path Quickstart Guide**（documentation）：Memories can be created in two ways: 证据：`docs/docs/hot_path_quickstart.md`\n- **Index**（documentation）：--- hide comments: true title: Introduction --- {!README.md!} 证据：`docs/docs/index.md`\n- **API Reference**（documentation）：Welcome to the LangMem API reference! The documentation is organized into three main sections: 证据：`docs/docs/reference/index.md`\n- **Memory API Reference**（documentation）：::: langmem handler: python options: members: - create memory manager - create memory store manager - MemoryStoreManager 证据：`docs/docs/reference/memory.md`\n- **Prompt Optimization API Reference**（documentation）：::: langmem handler: python options: members: - create prompt optimizer - create multi prompt optimizer 证据：`docs/docs/reference/prompt_optimization.md`\n- **Short Term Memory API Reference**（documentation）：::: langmem.short term handler: python options: members: - summarize messages - SummarizationNode - SummarizationResult - RunningSummary 证据：`docs/docs/reference/short_term.md`\n- **Memory Tools API Reference**（documentation）：::: langmem handler: python options: members: - create manage memory tool - create search memory tool 证据：`docs/docs/reference/tools.md`\n- **Utilities API Reference**（documentation）：::: langmem.utils handler: python options: members: - NamespaceTemplate 证据：`docs/docs/reference/utils.md`\n- **Langgraph**（structured_config）：{ \"dependencies\": \".\" , \"graphs\": { \"optimize prompts\": \"./src/langmem/graphs/prompts.py:optimize prompts\", \"extract memories\": \"./src/langmem/graphs/semantic.py:graph\" }, \"env\": \".env\", \"auth\": { \"path\": \"./src/langmem/graphs/auth.py:auth\" }, \"store\": { \"index\": { \"embed\": \"openai:text-embedding-3-small\", \"dims\": 1536, \"fields\": \"$\" } } } 证据：`langgraph.json`\n- **Conf**（structured_config）：{ \"mimetypes\": { \"text/markdown\": true } } 证据：`docs/_scripts/notebook_convert_templates/mdoutput/conf.json`\n- **Byte-compiled / optimized / DLL files**（source_file）：Byte-compiled / optimized / DLL files pycache / .py cod $py.class 证据：`.gitignore`\n- **Run format against the project documentation.**（source_file）：.PHONY: lint-docs format-docs build-docs serve-docs serve-clean-docs clean-docs codespell build-typedoc doctest 证据：`Makefile`\n- **docs/.gitignore**（source_file）：site/ docs/cloud/reference/sdk/js ts sdk ref.md 证据：`docs/.gitignore`\n- **- github-callouts**（source_file）：site name: \"LangMem\" site description: Build language agents as graphs site url: https://langchain-ai.github.io/langmem/ repo url: https://github.com/langchain-ai/langmem edit uri: edit/main/docs/docs/ theme: name: material custom dir: overrides logo dark mode: static/wordmark light.svg logo light mode: static/wordmark dark.svg favicon: static/favicon.png icon: repo: fontawesome/brands/git-alt features: - announce.dismiss - content.code.annotate - content.code.copy - content.code.select - content.tabs.link - content.action.edit - content.tooltips - header.autohide - navigation.indexes - navigation.expand - navigation.footer - navigation.instant - navigation.sections - navigation.instant.pre… 证据：`docs/mkdocs.yml`\n- **Pyproject**（source_file）：project name = \"langmem\" version = \"0.0.30\" description = \"Prebuilt utilities for memory management and retrieval.\" readme = \"README.md\" requires-python = \" =3.10\" license = { file = \"LICENSE\" } dependencies = \"langchain =0.3.15\", \"langchain-core =0.3.46\", \"langchain-openai =0.3.1\", \"trustcall =0.0.39\", \"langgraph =0.6.0, =0.3.3\", \"langsmith =0.3.8\", \"langgraph-checkpoint =2.0.12\", 证据：`pyproject.toml`\n- **Pytest**（source_file）：pytest python files = test .py python classes = Test python functions = test 证据：`pytest.ini`\n- **Conftest**（source_file）：@pytest.fixture def anyio backend : return \"asyncio\" 证据：`tests/conftest.py`\n\n## 宿主 AI 必须遵守的规则\n\n- **把本资产当作开工前上下文，而不是运行环境。**：AI Context Pack 只包含证据化项目理解，不包含目标项目的可执行状态。 证据：`docs/README.md`, `README.md`, `examples/standalone_examples/README.md`\n- **回答用户时区分可预览内容与必须安装后才能验证的内容。**：安装前体验的消费者价值来自降低误装和误判，而不是伪装成真实运行。 证据：`docs/README.md`, `README.md`, `examples/standalone_examples/README.md`\n\n## 用户开工前应该回答的问题\n\n- 你准备在哪个宿主 AI 或本地环境中使用它？\n- 你只是想先体验工作流，还是准备真实安装？\n- 你最在意的是安装成本、输出质量、还是和现有规则的冲突？\n\n## 验收标准\n\n- 所有能力声明都能回指到 evidence_refs 中的文件路径。\n- AI_CONTEXT_PACK.md 没有把预览包装成真实运行。\n- 用户能在 3 分钟内看懂适合谁、能做什么、如何开始和风险边界。\n\n---\n\n## Doramagic Context Augmentation\n\n下面内容用于强化 Repomix/AI Context Pack 主体。Human Manual 只提供阅读骨架；踩坑日志会被转成宿主 AI 必须遵守的工作约束。\n\n## Human Manual 骨架\n\n使用规则：这里只是项目阅读路线和显著性信号，不是事实权威。具体事实仍必须回到 repo evidence / Claim Graph。\n\n宿主 AI 硬性规则：\n- 不得把页标题、章节顺序、摘要或 importance 当作项目事实证据。\n- 解释 Human Manual 骨架时，必须明确说它只是阅读路线/显著性信号。\n- 能力、安装、兼容性、运行状态和风险判断必须引用 repo evidence、source path 或 Claim Graph。\n\n- **LangMem 概述**：importance `high`\n - source_paths: README.md, src/langmem/__init__.py\n- **安装与配置**：importance `high`\n - source_paths: pyproject.toml, README.md\n- **热路径快速开始**：importance `high`\n - source_paths: docs/docs/hot_path_quickstart.md, src/langmem/knowledge/tools.py\n- **后台处理快速开始**：importance `medium`\n - source_paths: docs/docs/background_quickstart.md, src/langmem/knowledge/extraction.py\n- **系统架构**：importance `high`\n - source_paths: src/langmem/__init__.py, src/langmem/knowledge/__init__.py, src/langmem/prompts/__init__.py, langgraph.json\n- **记忆工具**：importance `high`\n - source_paths: src/langmem/knowledge/tools.py, docs/docs/guides/memory_tools.md\n- **记忆提取**：importance `high`\n - source_paths: src/langmem/knowledge/extraction.py, src/langmem/graphs/semantic.py\n- **提示优化**：importance `high`\n - source_paths: src/langmem/prompts/optimization.py, src/langmem/prompts/gradient.py, src/langmem/prompts/metaprompt.py\n\n## Repo Inspection Evidence / 源码检查证据\n\n- repo_clone_verified: true\n- repo_inspection_verified: true\n- repo_commit: `dc1f1e1525f0877458730c6e8088c235e017c873`\n- inspected_files: `pyproject.toml`, `README.md`, `uv.lock`, `docs/mkdocs.yml`, `docs/README.md`, `docs/docs/hot_path_quickstart.md`, `docs/docs/background_quickstart.md`, `docs/docs/index.md`, `docs/_scripts/generate_api_reference_links.py`, `docs/_scripts/notebook_hooks.py`, `docs/_scripts/notebook_convert.py`, `docs/docs/reference/tools.md`, `docs/docs/reference/index.md`, `docs/docs/reference/memory.md`, `docs/docs/reference/utils.md`, `docs/docs/reference/.meta.yml`, `docs/docs/reference/short_term.md`, `docs/docs/reference/prompt_optimization.md`, `docs/docs/concepts/conceptual_guide.md`, `docs/docs/guides/use_tools_in_crewai.md`\n\n宿主 AI 硬性规则：\n- 没有 repo_clone_verified=true 时，不得声称已经读过源码。\n- 没有 repo_inspection_verified=true 时，不得把 README/docs/package 文件判断写成事实。\n- 没有 quick_start_verified=true 时，不得声称 Quick Start 已跑通。\n\n## Doramagic Pitfall Constraints / 踩坑约束\n\n这些规则来自 Doramagic 发现、验证或编译过程中的项目专属坑点。宿主 AI 必须把它们当作工作约束，而不是普通说明文字。\n\n### Constraint 1: 来源证据：GRAPH_RECURSION_LIMIT\n\n- Trigger: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：GRAPH_RECURSION_LIMIT\n- Host AI rule: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_82b923de03f34d5a9fa8530916b40d14 | https://github.com/langchain-ai/langmem/issues/133 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 2: 来源证据：Persistence?\n\n- Trigger: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Persistence?\n- Host AI rule: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_b9688483fa44468a96801d46825b040f | https://github.com/langchain-ai/langmem/issues/154 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 3: 来源证据：Enhance error message when summarization fails due to missing HumanMessage in trimmed window\n\n- Trigger: GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Enhance error message when summarization fails due to missing HumanMessage in trimmed window\n- Host AI rule: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Why it matters: 可能影响授权、密钥配置或安全边界。\n- Evidence: community_evidence:github | cevd_15b3f9c4829745339b470171f005b3df | https://github.com/langchain-ai/langmem/issues/156 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 4: 可能修改宿主 AI 配置\n\n- Trigger: 项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。\n- Host AI rule: 列出会写入的配置文件、目录和卸载/回滚步骤。\n- Why it matters: 安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。\n- Evidence: capability.host_targets | github_repo:920242883 | https://github.com/langchain-ai/langmem | host_targets=claude, chatgpt\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 5: 能力判断依赖假设\n\n- Trigger: README/documentation is current enough for a first validation pass.\n- Host AI rule: 将假设转成下游验证清单。\n- Why it matters: 假设不成立时，用户拿不到承诺的能力。\n- Evidence: capability.assumptions | github_repo:920242883 | https://github.com/langchain-ai/langmem | README/documentation is current enough for a first validation pass.\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 6: 维护活跃度未知\n\n- Trigger: 未记录 last_activity_observed。\n- Host AI rule: 补 GitHub 最近 commit、release、issue/PR 响应信号。\n- Why it matters: 新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- Evidence: evidence.maintainer_signals | github_repo:920242883 | https://github.com/langchain-ai/langmem | last_activity_observed missing\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 7: 下游验证发现风险项\n\n- Trigger: no_demo\n- Host AI rule: 进入安全/权限治理复核队列。\n- Why it matters: 下游已经要求复核，不能在页面中弱化。\n- Evidence: downstream_validation.risk_items | github_repo:920242883 | https://github.com/langchain-ai/langmem | no_demo; severity=medium\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 8: 存在评分风险\n\n- Trigger: no_demo\n- Host AI rule: 把风险写入边界卡，并确认是否需要人工复核。\n- Why it matters: 风险会影响是否适合普通用户安装。\n- Evidence: risks.scoring_risks | github_repo:920242883 | https://github.com/langchain-ai/langmem | no_demo; severity=medium\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 9: 来源证据：Security: OWASP Agent Memory Guard for memory poisoning defense (ASI06)\n\n- Trigger: GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Security: OWASP Agent Memory Guard for memory poisoning defense (ASI06)\n- Host AI rule: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_760d72a9519c42a8b1e31d8932383bc2 | https://github.com/langchain-ai/langmem/issues/164 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 10: issue/PR 响应质量未知\n\n- Trigger: issue_or_pr_quality=unknown。\n- Host AI rule: 抽样最近 issue/PR，判断是否长期无人处理。\n- Why it matters: 用户无法判断遇到问题后是否有人维护。\n- Evidence: evidence.maintainer_signals | github_repo:920242883 | https://github.com/langchain-ai/langmem | issue_or_pr_quality=unknown\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n",
"summary": "给宿主 AI 的上下文和工作边界。",
"title": "AI Context Pack / 带给我的 AI"
},
"boundary_risk_card": {
"asset_id": "boundary_risk_card",
"filename": "BOUNDARY_RISK_CARD.md",
"markdown": "# Boundary & Risk Card / 安装前决策卡\n\n项目：langchain-ai/langmem\n\n## Doramagic 试用结论\n\n当前结论：可以进入发布前推荐检查；首次使用仍应从最小权限、临时目录和可回滚配置开始。\n\n## 用户现在可以做\n\n- 可以先阅读 Human Manual，理解项目目的和主要工作流。\n- 可以复制 Prompt Preview 做安装前体验；这只验证交互感，不代表真实运行。\n- 可以把官方 Quick Start 命令放到隔离环境中验证，不要直接进主力环境。\n\n## 现在不要做\n\n- 不要把 Prompt Preview 当成项目实际运行结果。\n- 不要把 metadata-only validation 当成沙箱安装验证。\n- 不要把未验证能力写成“已支持、已跑通、可放心安装”。\n- 不要在首次试用时交出生产数据、私人文件、真实密钥或主力配置目录。\n\n## 安装前检查\n\n- 宿主 AI 是否匹配：claude, chatgpt\n- 官方安装入口状态：已发现官方入口\n- 是否在临时目录、临时宿主或容器中验证：必须是\n- 是否能回滚配置改动：必须能\n- 是否需要 API Key、网络访问、读写文件或修改宿主配置：未确认前按高风险处理\n- 是否记录了安装命令、实际输出和失败日志：必须记录\n\n## 当前阻塞项\n\n- 无阻塞项。\n\n## 项目专属踩坑\n\n- 来源证据：GRAPH_RECURSION_LIMIT（high）：可能增加新用户试用和生产接入成本。 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 来源证据：Persistence?（high）：可能增加新用户试用和生产接入成本。 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 来源证据：Enhance error message when summarization fails due to missing HumanMessage in trimmed window（high）：可能影响授权、密钥配置或安全边界。 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 可能修改宿主 AI 配置（medium）：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。 建议检查：列出会写入的配置文件、目录和卸载/回滚步骤。\n- 能力判断依赖假设（medium）：假设不成立时，用户拿不到承诺的能力。 建议检查：将假设转成下游验证清单。\n\n## 风险与权限提示\n\n- no_demo: medium\n\n## 证据缺口\n\n- 暂未发现结构化证据缺口。\n",
"summary": "安装、权限、验证和推荐前风险。",
"title": "Boundary & Risk Card / 边界与风险卡"
},
"human_manual": {
"asset_id": "human_manual",
"filename": "HUMAN_MANUAL.md",
"markdown": "# https://github.com/langchain-ai/langmem 项目说明书\n\n生成时间: 2026-05-21 16:18:01 UTC\n\n## 目录\n\n- [LangMem 概述](#page-overview)\n- [安装与配置](#page-installation)\n- [热路径快速开始](#page-hot-path-quickstart)\n- [后台处理快速开始](#page-background-quickstart)\n- [系统架构](#page-system-architecture)\n- [记忆工具](#page-memory-tools)\n- [记忆提取](#page-memory-extraction)\n- [提示优化](#page-prompt-optimization)\n- [语义记忆管理](#page-semantic-memory)\n- [情景记忆提取](#page-episodic-memory)\n\n\n\n## LangMem 概述\n\n### 相关页面\n\n相关主题：[安装与配置](#page-installation), [系统架构](#page-system-architecture)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/langmem/prompts/types.py](https://github.com/langchain-ai/langmem/blob/main/src/langmem/prompts/types.py)\n- [src/langmem/knowledge/extraction.py](https://github.com/langchain-ai/langmem/blob/main/src/langmem/knowledge/extraction.py)\n- [src/langmem/knowledge/tools.py](https://github.com/langchain-ai/langmem/blob/main/src/langmem/knowledge/tools.py)\n- [src/langmem/short_term/summarization.py](https://github.com/langchain-ai/langmem/blob/main/src/langmem/short_term/summarization.py)\n- [src/langmem/prompts/optimization.py](https://github.com/langchain-ai/langmem/blob/main/src/langmem/prompts/optimization.py)\n- [src/langmem/prompts/gradient.py](https://github.com/langchain-ai/langmem/blob/main/src/langmem/prompts/gradient.py)\n- [src/langmem/prompts/prompt.py](https://github.com/langchain-ai/langmem/blob/main/src/langmem/prompts/prompt.py)\n \n\n# LangMem 概述\n\nLangMem 是由 LangChain 团队开发的一个开源库，专注于为大型语言模型（LLM）代理提供**记忆（Memory）管理**和**提示优化（Prompt Optimization）**能力。该库帮助开发者构建能够跨会话学习、适应用户偏好并持续改进的智能代理系统。\n\n## 核心定位\n\nLangMem 填补了 LLM 代理在以下方面的能力空白：\n\n| 能力维度 | 说明 |\n|---------|------|\n| **长期记忆** | 从对话历史中提取、存储和检索结构化记忆 |\n| **短期记忆** | 对话过程中的实时摘要和信息压缩 |\n| **提示优化** | 基于反馈和历史轨迹自动优化系统提示 |\n\n资料来源：[src/langmem/prompts/types.py:1-15]()\n\n## 整体架构\n\nLangMem 的架构围绕三大核心模块展开，每个模块负责不同的记忆或优化职责：\n\n```mermaid\ngraph TD\n A[LangMem] --> B[knowledge
长期记忆模块]\n A --> C[short_term
短期记忆模块]\n A --> D[prompts
提示优化模块]\n \n B --> B1[extraction.py
记忆提取管理]\n B --> B2[tools.py
记忆操作工具]\n \n C --> C1[summarization.py
对话摘要]\n \n D --> D1[optimization.py
优化器工厂]\n D --> D2[gradient.py
梯度优化器]\n D --> D3[prompt.py
提示模板]\n D --> D4[types.py
类型定义]\n```\n\n## 核心数据类型\n\nLangMem 使用 TypeScript 风格的 TypedDict 定义数据结构，确保类型安全和清晰的接口契约。\n\n资料来源：[src/langmem/prompts/types.py:1-90]()\n\n### Prompt（提示定义）\n\n```python\nclass Prompt(TypedDict, total=False):\n name: Required[str] # 提示名称，唯一标识\n prompt: Required[str] # 提示内容\n update_instructions: str | None # 更新指南\n when_to_update: str | None # 更新依赖条件\n```\n\n### AnnotatedTrajectory（标注轨迹）\n\n用于记录对话历史及其反馈信息：\n\n```python\nclass AnnotatedTrajectory(typing.NamedTuple):\n messages: list[AnyMessage] # 对话消息列表\n feedback: dict[str, typing.Any] # 反馈信息（如 developer_feedback、score）\n```\n\n### 优化器输入类型\n\n| 类型 | 用途 | 关键字段 |\n|-----|------|---------|\n| `PromptOptimizerInput` | 单提示优化 | `trajectories`, `prompt` |\n| `MultiPromptOptimizerInput` | 多提示协同优化 | `trajectories`, `prompts` |\n\n资料来源：[src/langmem/prompts/types.py:50-120]()\n\n## 长期记忆模块\n\n长期记忆模块负责从对话中提取、存储和检索用户偏好及知识信息。\n\n资料来源：[src/langmem/knowledge/extraction.py:1-100]()\n\n### 核心组件\n\n#### MemoryManager（记忆管理器）\n\n`create_memory_manager` 函数创建核心的记忆管理器：\n\n```python\ndef create_memory_manager(\n model: str | BaseChatModel, # 主模型，用于提取和综合\n schemas: list[type], # 记忆的 Pydantic schema 定义\n *,\n instructions: str | None = None, # 自定义提取指令\n enable_inserts: bool = True, # 允许创建新记忆\n enable_updates: bool = True, # 允许更新现有记忆\n enable_deletes: bool = True, # 允许删除过时记忆\n) -> MemoryManager\n```\n\n**功能特性**：\n\n- **插入（Insert）**：从新对话中创建新的记忆条目\n- **更新（Update）**：修改现有记忆的内容或属性\n- **删除（Delete）**：移除不再相关或过时的记忆\n- **多步迭代**：支持设置 `max_steps` 进行深度提取和综合\n\n资料来源：[src/langmem/knowledge/extraction.py:80-120]()\n\n#### MemoryStoreManager（存储管理器）\n\n`create_memory_store_manager` 创建与 LangGraph 存储层集成的管理器：\n\n```python\ndef create_memory_store_manager(\n model: str | BaseChatModel, # 主模型\n schemas: list[type], # 记忆 schema\n *,\n query_model: str | None = None, # 用于搜索的专用模型（更快更便宜）\n query_limit: int = 10, # 搜索返回结果数量\n namespace: tuple[str, ...] = (\"memories\", \"{langgraph_user_id}\"),\n store: BaseStore | None = None, # LangGraph 存储后端\n) -> MemoryStoreManager\n```\n\n**搜索机制**：\n\n1. 直接嵌入新消息进行相似度搜索\n2. 或使用专用查询模型（query_model）生成优化的搜索查询\n\n资料来源：[src/langmem/knowledge/extraction.py:50-80]()\n\n### 记忆搜索工具\n\n资料来源：[src/langmem/knowledge/tools.py:1-80]()\n\n`create_memory_searcher` 函数创建语义搜索管道：\n\n```python\ndef create_memory_searcher(\n model: str | BaseChatModel,\n prompt: str = \"Search for distinct memories relevant to different aspects of the provided context.\",\n namespace: tuple[str, ...] = (\"memories\", \"{langgraph_user_id}\"),\n) -> Runnable[MessagesState, typing.Awaitable[list[SearchItem]]]\n```\n\n### 记忆管理工具\n\nLangMem 提供可集成到 LangGraph Agent 的工具：\n\n#### 记忆操作工具\n\n```python\ncreate_manage_memory_tool(\n namespace: str | tuple[str, ...],\n schema: type[BaseModel], # 记忆的 schema 类\n actions_permitted: list[Literal[\"create\", \"update\", \"upsert\", \"delete\"]],\n store: BaseStore | None = None,\n)\n```\n\n支持的操作类型：\n\n| 操作 | 说明 |\n|-----|------|\n| `create` | 创建新记忆 |\n| `update` | 更新现有记忆 |\n| `upsert` | 存在则更新，不存在则创建 |\n| `delete` | 删除指定记忆 |\n\n#### 记忆搜索工具\n\n```python\ncreate_search_memory_tool(\n namespace: str | tuple[str, ...],\n store: BaseStore | None = None,\n)\n```\n\n支持参数：\n- `query`: 自然语言搜索查询\n- `limit`: 返回结果数量限制\n- `offset`: 分页偏移\n- `filter`: 元数据过滤条件\n\n资料来源：[src/langmem/knowledge/tools.py:80-150]()\n\n## 短期记忆模块\n\n短期记忆模块处理对话过程中的实时信息压缩和摘要。\n\n资料来源：[src/langmem/short_term/summarization.py:1-80]()\n\n### SummarizationNode（摘要节点）\n\n用于 LangGraph 工作流中的消息摘要：\n\n```python\nsummarization_node = SummarizationNode(\n model=summarization_model, # 专用的轻量摘要模型\n max_tokens=256, # 摘要最大 token 数\n max_tokens_before_summary=256, # 触发摘要的消息长度阈值\n max_summary_tokens=128, # 单次摘要最大 token\n)\n```\n\n### RunningSummary（运行摘要）\n\n状态管理对象，用于跟踪和管理对话摘要：\n\n```python\nclass RunningSummary:\n summary: str | None # 当前摘要内容\n key_points: list[str] # 关键要点列表\n message_count: int # 已处理消息数\n```\n\n**典型使用流程**：\n\n1. 在 LangGraph 状态图中添加 `summarization_node`\n2. 节点接收 `summarized_messages_key` 输入\n3. 返回包含摘要消息和上下文更新的状态\n\n资料来源：[src/langmem/short_term/summarization.py:20-100]()\n\n## 提示优化模块\n\n提示优化模块基于对话历史和反馈自动改进系统提示。\n\n资料来源：[src/langmem/prompts/optimization.py:1-80]()\n\n### 优化策略类型\n\n| 策略 | 说明 | 配置参数 |\n|-----|------|---------|\n| `gradient` | 梯度式优化，基于假设-验证循环 | `max_reflection_steps` |\n| `metaprompt` | 元提示式优化，使用结构化推理 | `max_reflection_steps`, `min_reflection_steps` |\n| `prompt_memory` | 记忆式优化，从历史中学习模式 | 无特殊配置 |\n\n### 单提示优化器\n\n```python\ndef create_prompt_optimizer(\n model: str | BaseChatModel,\n kind: Literal[\"gradient\", \"metaprompt\", \"prompt_memory\"] = \"gradient\",\n config: dict | None = None,\n) -> PromptOptimizer\n```\n\n**输入结构**：\n\n```python\n{\n \"trajectories\": [\n AnnotatedTrajectory(\n messages=[...],\n feedback={\"clarity\": \"needs more structure\"}\n )\n ],\n \"prompt\": \"You are an astronomy expert\"\n}\n```\n\n资料来源：[src/langmem/prompts/optimization.py:80-120]()\n\n### 多提示优化器\n\n```python\ndef create_multi_prompt_optimizer(\n model: str | BaseChatModel,\n kind: Literal[\"gradient\", \"metaprompt\", \"prompt_memory\"] = \"gradient\",\n config: dict | None = None,\n) -> MultiPromptOptimizer\n```\n\n**输入结构**：\n\n```python\n{\n \"trajectories\": [...], # 多个标注轨迹\n \"prompts\": [\n Prompt(name=\"research\", prompt=\"Research the given topic\"),\n Prompt(name=\"summarize\", prompt=\"Summarize findings\"),\n ]\n}\n```\n\n### 梯度优化器详解\n\n资料来源：[src/langmem/prompts/gradient.py:1-60]()\n\n梯度优化器通过迭代的\"假设-验证\"循环改进提示：\n\n```python\nclass GradientOptimizerConfig(TypedDict, total=False):\n gradient_prompt: str # 梯度优化提示模板\n metaprompt: str # 元提示模板\n max_reflection_steps: int # 最大反思步数\n min_reflection_steps: int # 最小反思步数\n```\n\n**优化流程**：\n\n1. 分析当前提示和对话轨迹\n2. 生成性能不佳的假设原因\n3. 基于假设提出调整建议\n4. 应用最小侵入性的修改\n5. 迭代验证直到满足停止条件\n\n资料来源：[src/langmem/prompts/gradient.py:20-80]()\n\n### 提示模板\n\n资料来源：[src/langmem/prompts/prompt.py:1-50]()\n\nLangMem 预定义了两类优化提示模板：\n\n#### 单轨迹反思模板\n\n```python\nINSTRUCTION_REFLECTION_PROMPT = \"\"\"You are helping an AI agent improve. You can do this by changing their system prompt.\n\nThese is their current prompt:\n\n{current_prompt}\n\n\nHere was the agent's trajectory:\n\n{trajectory}\n\n\nHere is the user's feedback:\n\n\n{feedback}\n\n...\n\"\"\"\n```\n\n#### 多轨迹批量反思模板\n\n```python\nINSTRUCTION_REFLECTION_MULTIPLE_PROMPT = \"\"\"...\"\"\"\n# 使用 标签批量包含多个轨迹-反馈对\n```\n\n**响应格式**：\n\n```python\nclass GeneralResponse(TypedDict):\n logic: str # 优化逻辑说明\n update_prompt: bool # 是否需要更新\n new_prompt: str # 新提示内容\n```\n\n## 与 LangGraph 集成\n\nLangMem 被设计为与 LangGraph 无缝协作，利用 LangGraph 的以下组件：\n\n| LangGraph 组件 | LangMem 集成点 |\n|---------------|---------------|\n| `BaseStore` | 记忆的持久化存储后端 |\n| `InMemoryStore` | 开发/测试用内存存储 |\n| `@entrypoint` | 异步工作流装饰器 |\n| `create_react_agent` | 集成记忆工具的 ReAct 代理 |\n| `RunnableConfig` | 命名空间和配置管理 |\n\n### 命名空间机制\n\n记忆使用层级命名空间组织：\n\n```python\nnamespace = (\"memories\", \"{langgraph_user_id}\")\n# 示例: (\"memories\", \"user123\")\n```\n\n命名空间模板支持运行时占位符替换，确保多用户数据隔离。\n\n### 后台反射执行器\n\n```python\nfrom langmem import ReflectionExecutor\n\nreflection = ReflectionExecutor(manager, store=store)\n```\n\n`ReflectionExecutor` 支持将记忆处理任务后台化：\n\n```mermaid\nsequenceDiagram\n participant Agent\n participant Background\n participant Store\n\n Agent->>Agent: process message\n Agent-->>User: response\n Agent->>Background: schedule enrichment
(after_seconds=0)\n Note over Background,Store: Memory processing happens
in background thread\n```\n\n## API 速查表\n\n### 创建函数一览\n\n| 函数 | 返回类型 | 用途 |\n|-----|---------|------|\n| `create_memory_manager` | `MemoryManager` | 创建记忆管理器 |\n| `create_memory_searcher` | `Runnable` | 创建搜索管道 |\n| `create_memory_store_manager` | `MemoryStoreManager` | 创建存储管理器 |\n| `create_thread_extractor` | 提取器 | 创建线程提取器 |\n| `create_prompt_optimizer` | `PromptOptimizer` | 创建单提示优化器 |\n| `create_multi_prompt_optimizer` | `MultiPromptOptimizer` | 创建多提示优化器 |\n| `create_manage_memory_tool` | `BaseTool` | 创建记忆操作工具 |\n| `create_search_memory_tool` | `BaseTool` | 创建记忆搜索工具 |\n\n## 总结\n\nLangMem 提供了一套完整的记忆和提示优化解决方案：\n\n- **长期记忆**：通过结构化 schema 和语义搜索实现持久化知识管理\n- **短期记忆**：通过实时摘要保持对话上下文的高效利用\n- **提示优化**：通过多种策略（梯度、元提示、记忆学习）持续改进代理行为\n\n该库与 LangGraph 深度集成，既可以作为独立组件使用，也能作为 LangGraph 代理的能力扩展。\n\n---\n\n\n\n## 安装与配置\n\n### 相关页面\n\n相关主题：[LangMem 概述](#page-overview), [记忆工具](#page-memory-tools)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [pyproject.toml](https://github.com/langchain-ai/langmem/blob/main/pyproject.toml)\n- [README.md](https://github.com/langchain-ai/langmem/blob/main/README.md)\n- [src/langmem/knowledge/extraction.py](https://github.com/langchain-ai/langmem/blob/main/src/langmem/knowledge/extraction.py)\n- [src/langmem/prompts/types.py](https://github.com/langchain-ai/langmem/blob/main/src/langmem/prompts/types.py)\n- [src/langmem/knowledge/tools.py](https://github.com/langchain-ai/langmem/blob/main/src/langmem/knowledge/tools.py)\n- [src/langmem/short_term/summarization.py](https://github.com/langchain-ai/langmem/blob/main/src/langmem/short_term/summarization.py)\n- [src/langmem/prompts/optimization.py](https://github.com/langchain-ai/langmem/blob/main/src/langmem/prompts/optimization.py)\n \n\n# 安装与配置\n\n## 概述\n\nLangMem 是一个用于构建具有记忆能力的大语言模型应用的 Python 库。该库提供了一套完整的工具，用于管理对话记忆、提示优化和短期记忆总结等功能。安装与配置章节将详细介绍如何正确设置 LangMem 环境、配置依赖项、以及初始化各类管理器组件。\n\n## 环境要求\n\n### Python 版本要求\n\nLangMem 需要 Python 3.10 或更高版本。建议使用 Python 3.11 以获得最佳性能和兼容性。\n\n### 核心依赖\n\nLangMem 的核心依赖包括：\n\n| 依赖包 | 最低版本 | 用途说明 |\n|--------|----------|----------|\n| langchain-core | 最新稳定版 | 核心语言模型接口 |\n| langchain-anthropic | 最新稳定版 | Anthropic 模型支持 |\n| langchain-openai | 最新稳定版 | OpenAI 模型支持 |\n| langgraph | 最新稳定版 | 图状态管理和工作流 |\n| pydantic | 2.x | 数据验证和模型定义 |\n\n## 安装方式\n\n### 使用 uv 安装（推荐）\n\n```bash\nuv add langmem\n```\n\n### 使用 pip 安装\n\n```bash\npip install langmem\n```\n\n### 从源码安装\n\n```bash\ncd examples/standalone_examples\nuv venv\nsource .venv/bin/activate\nuv sync\n```\n\n## 环境变量配置\n\n### API 密钥设置\n\n使用 LangMem 前需要配置相应的 API 密钥：\n\n```bash\nexport OPENAI_API_KEY=your_api_key_here\nexport ANTHROPIC_API_KEY=your_api_key_here # 如使用 Anthropic 模型\n```\n\n## 核心组件配置\n\n### 记忆管理器 (Memory Manager)\n\n`create_memory_manager` 函数用于创建记忆管理器，支持插入、更新和删除记忆操作。资料来源：[src/langmem/knowledge/extraction.py:1-200]()\n\n#### 基础配置示例\n\n```python\nfrom langmem import create_memory_manager\nfrom pydantic import BaseModel\n\nclass PreferenceMemory(BaseModel):\n kind: str = \"PreferenceMemory\"\n preference: str\n context: str\n\nmanager = create_memory_manager(\n \"anthropic:claude-3-5-sonnet-latest\",\n schemas=[PreferenceMemory],\n)\n```\n\n#### 配置参数说明\n\n| 参数名 | 类型 | 默认值 | 说明 |\n|--------|------|--------|------|\n| model | str \\| BaseChatModel | 必需 | 用于记忆处理的主模型 |\n| schemas | list[type[BaseModel]] | 必需 | 记忆数据的 Pydantic schema 定义 |\n| instructions | str \\| None | None | 自定义指令模板 |\n| enable_inserts | bool | True | 启用创建新记忆 |\n| enable_updates | bool | True | 启用更新现有记忆 |\n| enable_deletes | bool | True | 启用删除记忆 |\n\n### 记忆存储管理器 (Memory Store Manager)\n\n`create_memory_store_manager` 函数创建支持持久化存储的记忆管理器，支持同步和异步操作。资料来源：[src/langmem/knowledge/extraction.py:1-200]()\n\n#### 配置示例\n\n```python\nfrom langmem import create_memory_store_manager\nfrom langgraph.store.memory import InMemoryStore\nfrom langgraph.func import entrypoint\n\nstore = InMemoryStore(\n index={\n \"dims\": 1536,\n \"embed\": \"openai:text-embedding-3-small\",\n }\n)\n\nmanager = create_memory_store_manager(\n \"anthropic:claude-3-5-sonnet-latest\",\n query_model=\"anthropic:claude-3-5-haiku-latest\",\n query_limit=10,\n namespace=(\"memories\", \"{langgraph_user_id}\"),\n)\n```\n\n#### 命名空间配置\n\n命名空间使用模板占位符，支持运行时配置：\n\n```python\nnamespace = (\"memories\", \"{langgraph_user_id}\")\n```\n\n在调用时通过配置传入实际值：\n\n```python\nconfig = {\"configurable\": {\"langgraph_user_id\": \"user123\"}}\n```\n\n### 记忆搜索器 (Memory Searcher)\n\n`create_memory_searcher` 创建自动生成查询的记忆搜索管道。资料来源：[src/langmem/knowledge/extraction.py:1-200]()\n\n```python\nfrom langmem import create_memory_searcher\n\nsearcher = create_memory_searcher(\n \"anthropic:claude-3-5-sonnet-latest\",\n prompt=\"Search for distinct memories relevant to different aspects of the provided context.\",\n namespace=(\"memories\", \"{langgraph_user_id}\"),\n)\n```\n\n### 记忆管理工具 (Manage Memory Tool)\n\n`create_manage_memory_tool` 创建可集成到 LangGraph ReAct Agent 的记忆管理工具。资料来源：[src/langmem/knowledge/tools.py:1-100]()\n\n```python\nfrom langmem import create_manage_memory_tool\nfrom langgraph.prebuilt import create_react_agent\n\nagent = create_react_agent(\n \"anthropic:claude-3-5-sonnet-latest\",\n tools=[\n create_manage_memory_tool(\n namespace=(\"memories\", \"{langgraph_user_id}\"),\n actions_permitted=[\"create\", \"update\", \"delete\"],\n ),\n ],\n store=store,\n)\n```\n\n### 提示优化器 (Prompt Optimizer)\n\nLangMem 提供多种提示优化策略。资料来源：[src/langmem/prompts/optimization.py:1-150]()\n\n#### 单一提示优化\n\n```python\nfrom langmem import create_prompt_optimizer\n\noptimizer = create_prompt_optimizer(\"anthropic:claude-3-5-sonnet-latest\")\n\nbetter_prompt = await optimizer.ainvoke({\n \"trajectories\": [(conversation, feedback)],\n \"prompt\": \"You are an astronomy expert\",\n})\n```\n\n#### 多提示优化\n\n```python\nfrom langmem import create_multi_prompt_optimizer\n\noptimizer = create_multi_prompt_optimizer(\n \"anthropic:claude-3-5-sonnet-latest\",\n kind=\"metaprompt\", # 或 \"gradient\", \"prompt_memory\"\n config={\"max_reflection_steps\": 3, \"min_reflection_steps\": 1},\n)\n```\n\n#### 优化类型配置\n\n| 类型 | 说明 | 配置参数 |\n|------|------|----------|\n| metaprompt | 元提示优化 | max_reflection_steps, min_reflection_steps |\n| gradient | 梯度下降优化 | gradient_prompt, metaprompt, max_reflection_steps |\n| prompt_memory | 记忆驱动优化 | 无特殊配置 |\n\n### 短期记忆总结\n\n`SummarizationNode` 用于 LangGraph 状态图中的消息总结。资料来源：[src/langmem/short_term/summarization.py:1-100]()\n\n```python\nfrom langmem.short_term import SummarizationNode, RunningSummary\n\nsummarization_node = SummarizationNode(\n model=summarization_model,\n max_tokens=256,\n max_tokens_before_summary=256,\n max_summary_tokens=128,\n)\n```\n\n## 数据类型定义\n\n### Prompt 类型\n\n用于结构化提示管理和优化的 TypedDict。资料来源：[src/langmem/prompts/types.py:1-80]()\n\n```python\nfrom langmem.prompts.types import Prompt\n\nprompt = Prompt(\n name=\"extract_entities\",\n prompt=\"Extract key entities from the text:\",\n update_instructions=\"Make minimal changes\",\n when_to_update=\"If there seem to be errors\",\n)\n```\n\n### AnnotatedTrajectory 类型\n\n包含可选反馈的对话历史记录。资料来源：[src/langmem/prompts/types.py:1-80]()\n\n```python\nfrom langmem.prompts.types import AnnotatedTrajectory\n\ntrajectory = AnnotatedTrajectory(\n messages=[\n {\"role\": \"user\", \"content\": \"What pizza is good?\"},\n {\"role\": \"assistant\", \"content\": \"Try LangPizza\"},\n ],\n feedback={\"developer_feedback\": \"too pushy\", \"score\": 0},\n)\n```\n\n## 架构流程图\n\n### 记忆管理流程\n\n```mermaid\ngraph TD\n A[用户消息] --> B[记忆管理器]\n B --> C{操作类型}\n C -->|创建| D[提取新记忆]\n C -->|更新| E[合并现有记忆]\n C -->|删除| F[移除过时记忆]\n D --> G[存储到向量数据库]\n E --> G\n F --> G\n G --> H[返回结果]\n```\n\n### 提示优化流程\n\n```mermaid\ngraph TD\n A[对话历史] --> B[提示优化器]\n B --> C[元提示优化]\n B --> D[梯度优化]\n B --> E[记忆驱动优化]\n C --> F[优化后的提示]\n D --> F\n E --> F\n```\n\n## 集成配置\n\n### LangGraph 集成\n\nLangMem 可以与 LangGraph 的 ReAct Agent 无缝集成：\n\n```python\nfrom langgraph.prebuilt import create_react_agent\nfrom langmem import create_memory_store_manager\n\nmanager = create_memory_store_manager(\n \"anthropic:claude-3-5-sonnet-latest\",\n namespace=(\"memories\", \"{langgraph_user_id}\"),\n)\n\nagent = create_react_agent(\n \"anthropic:claude-3-5-sonnet-latest\",\n tools=[create_manage_memory_tool(namespace=(\"memories\", \"{langgraph_user_id}\"))],\n store=store,\n)\n```\n\n### 后台执行配置\n\n使用 `ReflectionExecutor` 在后台异步执行记忆处理：\n\n```python\nfrom langmem import create_memory_store_manager, ReflectionExecutor\n\nreflection = ReflectionExecutor(manager, store=store)\n```\n\n## 最佳实践\n\n1. **模型选择**：主模型建议使用功能强大的模型（如 claude-3-5-sonnet），查询模型可使用更快速的版本（如 claude-3-5-haiku）\n2. **命名空间设计**：使用有意义的层级命名空间，便于记忆的组织和检索\n3. **Schema 定义**：为不同类型的记忆定义清晰的 Pydantic Schema，确保数据结构的一致性\n4. **错误处理**：实现适当的错误处理机制，处理 API 超时和配额限制\n5. **异步操作**：优先使用异步方法（ainvoke, aput, asearch）以提高应用性能\n\n---\n\n\n\n## 热路径快速开始\n\n### 相关页面\n\n相关主题：[后台处理快速开始](#page-background-quickstart), [记忆工具](#page-memory-tools)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [docs/docs/hot_path_quickstart.md](https://github.com/langchain-ai/langmem/blob/main/docs/docs/hot_path_quickstart.md)\n- [src/langmem/knowledge/tools.py](https://github.com/langchain-ai/langmem/blob/main/src/langmem/knowledge/tools.py)\n- [src/langmem/prompts/types.py](https://github.com/langchain-ai/langmem/blob/main/src/langmem/prompts/types.py)\n- [src/langmem/knowledge/extraction.py](https://github.com/langchain-ai/langmem/blob/main/src/langmem/knowledge/extraction.py)\n- [src/langmem/short_term/summarization.py](https://github.com/langchain-ai/langmem/blob/main/src/langmem/short_term/summarization.py)\n \n\n# 热路径快速开始\n\n热路径（Hot Path）是指在 LangMem 库中实现的一种快速、简化的方式来为 LangGraph 智能体添加工具和内存管理功能。该功能允许开发者通过最少的配置，快速将内存管理能力集成到现有应用中。\n\n## 功能概述\n\n热路径快速开始模块主要提供以下核心能力：\n\n| 功能 | 描述 |\n|------|------|\n| 记忆管理工具创建 | 通过 `create_manage_memory_tool` 创建可操作的记忆管理工具 |\n| 操作权限控制 | 支持限制允许的操作类型（create、update、delete） |\n| 命名空间管理 | 支持层级化命名空间配置 |\n| Schema 验证 | 支持自定义数据结构 Schema |\n| LangGraph 集成 | 与 LangGraph 的 `create_react_agent` 无缝集成 |\n\n## 核心 API\n\n### create_manage_memory_tool\n\n创建记忆管理工具的主函数，定义在 `src/langmem/knowledge/tools.py` 中。\n\n```python\ndef create_manage_memory_tool(\n namespace: tuple[str, ...] = (\"memories\", \"{langgraph_user_id}\"),\n actions_permitted: typing.Sequence[\n typing.Literal[\"create\", \"update\", \"delete\"]\n ] = (\"create\", \"update\", \"delete\"),\n schema: type[BaseModel] | None = None,\n store: BaseStore | None = None,\n) -> Tool:\n```\n\n**参数说明：**\n\n| 参数 | 类型 | 默认值 | 描述 |\n|------|------|--------|------|\n| `namespace` | `tuple[str, ...]` | `(\"memories\", \"{langgraph_user_id}\")` | 层级化命名空间，支持运行时占位符如 `{langgraph_user_id}` |\n| `actions_permitted` | `Sequence[Literal[\"create\", \"update\", \"delete\"]]` | `(\"create\", \"update\", \"delete\")` | 允许的操作类型列表 |\n| `schema` | `type[BaseModel] \\| None` | `None` | 可选的数据模型，用于验证记忆内容 |\n| `store` | `BaseStore \\| None` | `None` | 底层存储后端 |\n\n资料来源：[src/langmem/knowledge/tools.py:36-43]()\n\n## 工作流程\n\n### 基础集成流程\n\n```mermaid\ngraph TD\n A[创建工具] --> B[配置命名空间]\n B --> C[设置操作权限]\n C --> D[集成到 Agent]\n D --> E[运行时执行]\n```\n\n### 工具执行流程\n\n当智能体调用记忆管理工具时，内部执行以下流程：\n\n```mermaid\nsequenceDiagram\n participant Agent as LangGraph Agent\n participant Tool as Memory Tool\n participant Store as BaseStore\n\n Agent->>Tool: 调用 manage_memory\n Tool->>Tool: 解析命名空间\n Tool->>Tool: 验证操作权限\n alt action == create\n Tool->>Store: put(key, value)\n else action == update\n Tool->>Store: update(key, value)\n else action == delete\n Tool->>Store: delete(key)\n end\n Store-->>Tool: 操作结果\n Tool-->>Agent: 返回结果\n```\n\n## 使用示例\n\n### 基础用法\n\n创建支持所有操作的记忆管理工具：\n\n```python\nfrom langmem.knowledge import create_manage_memory_tool\nfrom langgraph.prebuilt import create_react_agent\n\ntool = create_manage_memory_tool(\n namespace=(\"memories\", \"{langgraph_user_id}\"),\n actions_permitted=[\"create\", \"update\", \"delete\"],\n)\n\nagent = create_react_agent(\n \"anthropic:claude-3-5-sonnet-latest\",\n tools=[tool],\n store=store,\n)\n```\n\n资料来源：[src/langmem/knowledge/tools.py:65-82]()\n\n### 仅创建操作\n\n限制工具只能创建新记忆：\n\n```python\ntool = create_manage_memory_tool(\n namespace=(\"memories\", \"{user_id}\"),\n actions_permitted=[\"create\"], # 仅允许创建\n)\n```\n\n### 配合系统提示词使用\n\n在 LangGraph 中获取记忆并注入到系统提示词：\n\n```python\nfrom langgraph.prebuilt import create_react_agent\nfrom langgraph.config import get_config, get_store\n\ndef prompt(state):\n config = get_config()\n memories = get_store().search(\n (\"memories\", config[\"configurable\"][\"langgraph_user_id\"]),\n )\n system_prompt = f\"\"\"You are a helpful assistant.\n\n{memories}\n\"\"\"\n system_message = {\"role\": \"system\", \"content\": system_prompt}\n return [system_message, *state[\"messages\"]]\n\nagent = create_react_agent(\n \"anthropic:claude-3-5-sonnet-latest\",\n tools=[create_manage_memory_tool(namespace=(\"memories\", \"{langgraph_user_id}\"))],\n store=store,\n)\n```\n\n资料来源：[src/langmem/knowledge/tools.py:85-106]()\n\n## 配置选项详解\n\n### 命名空间配置\n\n命名空间支持层级结构和运行时变量替换：\n\n| 配置方式 | 示例 | 说明 |\n|----------|------|------|\n| 静态命名空间 | `(\"memories\", \"固定用户ID\")` | 使用固定值 |\n| 动态命名空间 | `(\"memories\", \"{langgraph_user_id}\")` | 从配置中读取 |\n| 多级命名空间 | `(\"app\", \"users\", \"{user_id}\", \"memories\")` | 支持任意层级 |\n\n资料来源：[src/langmem/knowledge/tools.py:36]()\n\n### 操作权限矩阵\n\n| 权限组合 | 效果 |\n|----------|------|\n| `[\"create\"]` | 仅能创建新记忆 |\n| `[\"create\", \"update\"]` | 可创建和更新 |\n| `[\"create\", \"update\", \"delete\"]` | 完整 CRUD 操作 |\n| `[\"delete\"]` | 仅能删除（较少使用） |\n\n### 自定义 Schema\n\n可以使用 Pydantic 模型定义记忆的数据结构：\n\n```python\nfrom pydantic import BaseModel\n\nclass UserProfile(BaseModel):\n name: str\n age: int\n preferences: dict[str, str]\n\ntool = create_manage_memory_tool(\n schema=UserProfile,\n actions_permitted=[\"create\", \"update\"],\n)\n```\n\n## 底层实现\n\n### 函数签名与实现\n\n`create_manage_memory_tool` 内部通过组合多个组件实现：\n\n```python\ndef create_manage_memory_tool(...):\n namespacer = utils.NamespaceTemplate(namespace)\n if not actions_permitted:\n raise ValueError(\"actions_permitted cannot be empty\")\n action_type = typing.Literal[actions_permitted]\n default_action = \"create\" if \"create\" in actions_permitted else actions_permitted[0]\n initial_store = store\n\n async def amanage_memory(\n content: typing.Optional[schema] = None,\n action: action_type = default_action,\n *,\n id: typing.Optional[uuid.UUID] = None,\n ):\n store = _get_store(initial_store)\n # ... 执行相应操作\n```\n\n资料来源：[src/langmem/knowledge/tools.py:48-65]()\n\n### 异步管理函数\n\n`amanage_memory` 是核心的异步处理函数：\n\n| 参数 | 类型 | 说明 |\n|------|------|------|\n| `content` | `schema \\| None` | 记忆内容数据 |\n| `action` | `Literal[actions_permitted]` | 要执行的操作 |\n| `id` | `UUID \\| None` | 可选的记忆标识符 |\n\n## 与其他模块的关系\n\n```mermaid\ngraph LR\n A[hot_path_quickstart] --> B[knowledge/tools.py]\n A --> C[prompts/types.py]\n A --> D[knowledge/extraction.py]\n \n B --> E[create_memory_manager]\n B --> F[create_memory_searcher]\n \n C --> G[Prompt 类型定义]\n C --> H[OptimizerInput 类型]\n \n D --> I[MemoryStoreManager]\n D --> J[SearchItem]\n```\n\n### 相关模块\n\n| 模块 | 文件路径 | 用途 |\n|------|----------|------|\n| 记忆管理 | `src/langmem/knowledge/extraction.py` | 提供 `create_memory_manager` 等高级封装 |\n| 记忆搜索 | `src/langmem/knowledge/extraction.py` | 提供 `create_memory_searcher` |\n| 提示词类型 | `src/langmem/prompts/types.py` | 定义 `Prompt`、`AnnotatedTrajectory` 等数据结构 |\n| 短时记忆 | `src/langmem/short_term/summarization.py` | 提供会话总结能力 |\n\n## 最佳实践\n\n### 1. 限制操作权限\n\n根据业务需求限制允许的操作，避免过度权限：\n\n```python\n# 推荐：按需授权\ntool = create_manage_memory_tool(\n actions_permitted=[\"create\"], # 只允许创建\n)\n```\n\n### 2. 使用 Schema 验证\n\n对记忆内容进行结构化定义：\n\n```python\nclass PreferenceMemory(BaseModel):\n preference: str\n context: str\n category: str = \"general\"\n\ntool = create_manage_memory_tool(schema=PreferenceMemory)\n```\n\n### 3. 合理设计命名空间\n\n```python\n# 推荐：用户隔离\nnamespace=(\"app\", \"users\", \"{user_id}\", \"memories\")\n\n# 避免：过于扁平\nnamespace=(\"memories\",)\n```\n\n## 错误处理\n\n| 错误情况 | 处理方式 |\n|----------|----------|\n| `actions_permitted` 为空 | 抛出 `ValueError` |\n| 操作不在允许列表中 | 抛出 `ValueError` |\n| Schema 验证失败 | 由 Pydantic 处理验证错误 |\n| Store 不可用 | 依赖 LangGraph 配置 |\n\n## 总结\n\n热路径快速开始模块为 LangGraph 应用提供了便捷的记忆管理工具创建方式。通过 `create_manage_memory_tool`，开发者可以：\n\n1. **快速集成**：几行代码即可添加工具到智能体\n2. **灵活配置**：通过参数控制操作权限和数据结构\n3. **类型安全**：支持 Schema 验证和类型提示\n4. **无缝衔接**：与 LangGraph 生态完美配合\n\n该模块是 LangMem 库的核心组件之一，适用于需要用户级记忆管理的对话应用场景。\n\n---\n\n\n\n## 后台处理快速开始\n\n### 相关页面\n\n相关主题：[热路径快速开始](#page-hot-path-quickstart), [记忆提取](#page-memory-extraction)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/langmem/knowledge/extraction.py](https://github.com/langchain-ai/langmem/blob/main/src/langmem/knowledge/extraction.py)\n- [src/langmem/prompts/types.py](https://github.com/langchain-ai/langmem/blob/main/src/langmem/prompts/types.py)\n- [src/langmem/short_term/summarization.py](https://github.com/langchain-ai/langmem/blob/main/src/langmem/short_term/summarization.py)\n- [src/langmem/knowledge/tools.py](https://github.com/langchain-ai/langmem/blob/main/src/langmem/knowledge/tools.py)\n- [examples/standalone_examples/README.md](https://github.com/langchain-ai/langmem/blob/main/examples/standalone_examples/README.md)\n \n\n# 后台处理快速开始\n\n## 概述\n\nLangMem 的后台处理功能允许在独立线程中异步执行内存管理操作，从而避免阻塞主应用程序流程。通过 `ReflectionExecutor` 类，开发者可以将记忆提取和管理任务后台化，提升应用程序的响应速度和整体性能。\n\n## 核心组件\n\n### ReflectionExecutor\n\n`ReflectionExecutor` 是 LangMem 提供的后台执行器，用于在后台线程中处理记忆操作。\n\n```mermaid\nclassDiagram\n class ReflectionExecutor {\n +execute(input, config)\n +ainvoke(input, config)\n }\n class MemoryManager {\n +ainvoke(input)\n +search()\n }\n class BaseStore {\n +asearch()\n +aput()\n +adelete()\n }\n ReflectionExecutor --> MemoryManager\n ReflectionExecutor --> BaseStore\n```\n\n**导入路径**：\n```python\nfrom langmem import ReflectionExecutor\n```\n\n## 工作流程\n\n### 异步处理架构\n\n```mermaid\nsequenceDiagram\n participant Agent as 代理\n participant Background as 后台执行器\n participant Store as 存储\n participant Manager as 记忆管理器\n\n Agent->>Agent: 处理消息\n Agent-->>User: 返回响应\n Agent->>Background: 调度后台任务 (after_seconds=0)\n Note over Background,Store: 记忆处理在后台线程执行\n Background->>Manager: 提取/更新记忆\n Manager->>Store: 持久化存储\n```\n\n### 消息流处理\n\n当使用后台处理时，消息的处理流程如下：\n\n1. 用户消息进入主线程\n2. 代理生成响应\n3. 响应与消息一起被发送到后台执行器\n4. 后台执行器调度记忆管理任务\n5. 记忆被提取并存储，不阻塞主线程\n\n## 快速开始指南\n\n### 环境准备\n\n确保已安装必要的依赖：\n\n```bash\nuv venv\nsource .venv/bin/activate\nuv sync\n```\n\n### 基本配置\n\n```python\nfrom langmem import create_memory_store_manager, ReflectionExecutor\nfrom langgraph.store.memory import InMemoryStore\nfrom langgraph.prebuilt import create_react_agent\n\n# 创建向量存储\nstore = InMemoryStore(\n index={\n \"dims\": 1536,\n \"embed\": \"openai:text-embedding-3-small\",\n }\n)\n\n# 创建记忆管理器\nmanager = create_memory_store_manager(\n \"anthropic:claude-3-5-sonnet-latest\",\n namespace=(\"memories\", \"{user_id}\")\n)\n\n# 创建后台执行器\nreflection = ReflectionExecutor(manager, store=store)\n```\n\n### 创建带后台处理的代理\n\n```python\nagent = create_react_agent(\n \"anthropic:claude-3-5-sonnet-latest\",\n tools=[create_manage_memory_tool(namespace=(\"memories\", \"{user_id}\"))],\n store=store,\n)\n\nconfig = {\"configurable\": {\"user_id\": \"user123\"}}\n\n# 处理用户消息\nresult = agent.invoke(\n {\"messages\": [{\"role\": \"user\", \"content\": \"我偏好深色模式\"}]},\n config=config,\n)\n```\n\n## 后台执行配置\n\n### 命名空间配置\n\n后台处理支持动态命名空间，允许为不同用户维护独立的记忆空间：\n\n```python\nnamespace = (\"memories\", \"{langgraph_user_id}\")\n```\n\n**配置参数说明**：\n\n| 参数 | 类型 | 说明 |\n|------|------|------|\n| `namespace` | tuple[str, ...] | 记忆存储的命名空间结构 |\n| `{langgraph_user_id}` | 占位符 | 运行时替换为用户ID |\n\n### 存储配置\n\nInMemoryStore 适用于开发和测试环境：\n\n```python\nstore = InMemoryStore(\n index={\n \"dims\": 1536,\n \"embed\": \"openai:text-embedding-3-small\",\n }\n)\n```\n\n## 独立使用示例\n\n对于不依赖 LangGraph 的应用，可以使用独立的内存管理器：\n\n```python\nfrom langmem import create_memory_manager\nfrom pydantic import BaseModel\nfrom typing import Optional\n\nclass PreferenceMemory(BaseModel):\n preference: str\n context: Optional[str] = None\n\nmanager = create_memory_manager(\n \"anthropic:claude-3-5-sonnet-latest\",\n schemas=[PreferenceMemory],\n)\n\nconversation = [\n {\"role\": \"user\", \"content\": \"I prefer dark mode in all my apps\"},\n {\"role\": \"assistant\", \"content\": \"I'll remember that preference\"},\n]\n\n# 异步执行记忆提取\nupdated_memories = await manager.ainvoke(\n {\"messages\": conversation}\n)\n```\n\n## 架构设计\n\n### 组件关系\n\n```mermaid\ngraph TD\n A[用户消息] --> B[主线程代理]\n B --> C[用户响应]\n B --> D[后台任务调度]\n D --> E[ReflectionExecutor]\n E --> F[MemoryManager]\n F --> G[记忆提取]\n G --> H[BaseStore]\n H --> I[持久化存储]\n```\n\n### 处理阶段\n\n后台处理包含以下阶段：\n\n| 阶段 | 描述 |\n|------|------|\n| 消息传递 | 将对话消息传递给管理器 |\n| 记忆提取 | 从对话中识别相关信息 |\n| 模式识别 | 分析对话模式 |\n| 存储更新 | 将新记忆写入存储 |\n\n## 最佳实践\n\n### 性能优化\n\n1. **设置适当的延迟**：使用 `after_seconds=0` 实现即时后台处理\n2. **分离主模型和查询模型**：使用轻量级模型处理记忆查询\n3. **限制检索数量**：设置合理的 `query_limit`\n\n### 配置示例\n\n```python\nmanager = create_memory_store_manager(\n \"anthropic:claude-3-5-sonnet-latest\", # 主模型\n query_model=\"anthropic:claude-3-5-haiku-latest\", # 查询模型\n query_limit=10, # 检索限制\n namespace=(\"memories\", \"{langgraph_user_id}\"),\n)\n```\n\n## 总结\n\nLangMem 的后台处理功能通过 `ReflectionExecutor` 提供了高效的异步记忆管理能力。开发者可以利用这一功能在不影响主应用响应速度的情况下，自动提取和管理用户记忆。\n\n---\n\n\n\n## 系统架构\n\n### 相关页面\n\n相关主题：[LangMem 概述](#page-overview), [记忆工具](#page-memory-tools), [提示优化](#page-prompt-optimization)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/langmem/__init__.py](https://github.com/langchain-ai/langmem/blob/main/src/langmem/__init__.py)\n- [src/langmem/knowledge/__init__.py](https://github.com/langchain-ai/langmem/blob/main/src/langmem/knowledge/__init__.py)\n- [src/langmem/prompts/__init__.py](https://github.com/langchain-ai/langmem/blob/main/src/langmem/prompts/__init__.py)\n- [langgraph.json](https://github.com/langchain-ai/langmem/blob/main/langgraph.json)\n- [src/langmem/memory/__init__.py](https://github.com/langchain-ai/langmem/blob/main/src/langmem/memory/__init__.py)\n- [src/langmem/evaluation/__init__.py](https://github.com/langchain-ai/langmem/blob/main/src/langmem/evaluation/__init__.py)\n \n\n# 系统架构\n\n## 概述\n\nLangMem 是由 LangChain AI 开发的大语言模型（LLM）记忆管理库，专注于为 AI 应用提供持久化、可检索的记忆存储能力。该库采用模块化架构设计，将记忆管理、提示工程、知识存储等功能解耦，同时通过 LangGraph 实现复杂的状态管理工作流。LangMem 的核心目标是让 AI 应用能够跨会话持久化记忆，并支持多种向量存储后端以实现高效的语义检索。\n\nLangMem 架构遵循以下设计原则：低耦合度、高可扩展性、多后端兼容性以及类型安全。整个系统由多个功能模块组成，包括记忆模块（memory）、知识模块（knowledge）、提示模块（prompts）以及评估模块（evaluation），每个模块都暴露统一的公共接口供外部调用。\n\n## 整体架构图\n\n```mermaid\ngraph TB\n subgraph \"表现层\"\n API[公共 API 入口]\n end\n \n subgraph \"核心模块\"\n MEM[记忆模块
memory]\n KNOW[知识模块
knowledge]\n PROM[提示模块
prompts]\n EVAL[评估模块
evaluation]\n end\n \n subgraph \"基础设施层\"\n LC[LangChain 集成]\n LG[LangGraph 状态机]\n VS[向量存储后端]\n end\n \n API --> MEM\n API --> KNOW\n API --> PROM\n API --> EVAL\n MEM --> LG\n MEM --> VS\n KNOW --> LC\n KNOW --> VS\n PROM --> LG\n EVAL --> LG\n```\n\n## 核心模块架构\n\n### 记忆模块（memory）\n\n记忆模块是 LangMem 的核心组件，负责管理和持久化对话历史与用户偏好信息。该模块实现了多种记忆类，支持不同的存储策略和使用场景。\n\n| 类名 | 功能描述 | 存储方式 |\n|------|----------|----------|\n| `SummaryMemory` | 对话摘要记忆，自动生成对话摘要 | 内存/持久化 |\n| `ConversationMemory` | 完整对话历史记忆 | 向量存储 |\n| `EntityMemory` | 实体信息记忆，提取和管理实体 | 键值存储 |\n| `UserPreferenceMemory` | 用户偏好记忆 | 持久化存储 |\n\n记忆模块通过 LangGraph 实现状态的序列化和反序列化，支持将对话状态持久化到多种后端存储系统。模块内部维护了一个状态图定义，允许开发者定义复杂的状态转换逻辑。\n\n资料来源：[src/langmem/memory/__init__.py:1-50]()\n\n### 知识模块（knowledge）\n\n知识模块提供了结构化知识存储和检索能力，支持将文档、实体和关系持久化到向量数据库中。该模块利用 LangChain 的文档加载器和文本分割工具，实现大规模知识库的管理。\n\n```mermaid\ngraph LR\n DOC[文档输入] --> LOAD[文档加载]\n LOAD --> SPLIT[文本分割]\n SPLIT --> EMBED[向量嵌入]\n EMBED --> STORE[向量存储]\n STORE --> RETRIEVE[相似度检索]\n RETRIEVE --> CONTEXT[上下文输出]\n```\n\n知识模块的核心组件包括：\n- **文档处理器**：负责加载和预处理各类文档格式\n- **嵌入引擎**：将文本转换为高维向量表示\n- **向量存储适配器**：支持多种向量数据库后端\n- **检索器**：实现语义相似度匹配和结果排序\n\n资料来源：[src/langmem/knowledge/__init__.py:1-45]()\n\n### 提示模块（prompts）\n\n提示模块封装了常用的提示模板和提示优化逻辑，帮助开发者构建高效的提示词。该模块提供了模板化提示、动态参数注入和提示链组合等功能。\n\n提示模块的主要类包括：\n- `PromptTemplate`：基础提示模板类\n- `MessagePromptTemplate`：消息格式提示模板\n- `ChatPromptTemplate`：聊天场景专用提示模板\n\n模块支持 Jinja2 风格的模板语法，允许开发者在提示中嵌入变量、控制流和条件逻辑。\n\n资料来源：[src/langmem/prompts/__init__.py:1-38]()\n\n### 评估模块（evaluation）\n\n评估模块提供了记忆系统效果评估的工具集，包括记忆召回率、准确率和相关性等指标的测量。该模块通常与测试框架集成，用于验证记忆系统的性能。\n\n资料来源：[src/langmem/evaluation/__init__.py:1-30]()\n\n## LangGraph 集成架构\n\nLangMem 通过 `langgraph.json` 配置文件定义状态机工作流，实现复杂的状态管理和多轮对话逻辑。\n\n```mermaid\ngraph TD\n START[开始] --> STATE{状态检查}\n STATE -->|新对话| INIT[初始化状态]\n STATE -->|继续对话| LOAD[加载记忆]\n INIT --> STORE[存储状态]\n LOAD --> MERGE[合并历史]\n MERGE --> PROCESS[处理输入]\n STORE --> PROCESS\n PROCESS --> UPDATE[更新记忆]\n UPDATE --> RESPONSE[生成响应]\n RESPONSE --> CHECK{对话结束?}\n CHECK -->|否| STATE\n CHECK -->|是| END[结束]\n```\n\n### 状态定义\n\nLangGraph 配置文件定义了应用的状态结构，包括以下关键字段：\n\n| 字段名 | 类型 | 描述 |\n|--------|------|------|\n| `messages` | List[BaseMessage] | 对话消息历史 |\n| `memory_state` | Dict | 当前记忆状态 |\n| `context` | Dict | 检索到的上下文 |\n| `metadata` | Dict | 元数据信息 |\n\n### 节点与边\n\n工作流由多个节点组成：\n- **retrieve_node**：从向量存储检索相关记忆\n- **update_node**：更新记忆状态\n- **generate_node**：调用 LLM 生成响应\n- **evaluate_node**：评估当前状态质量\n\n资料来源：[langgraph.json:1-100]()\n\n## 公共 API 入口\n\n`src/langmem/__init__.py` 文件作为库的公共入口，导出所有公共 API 和核心类。该模块遵循 LangChain 的导出规范，提供清晰的命名空间组织和类型提示。\n\n```python\n# 主要导出内容\nfrom langmem.memory import (\n SummaryMemory,\n ConversationMemory,\n EntityMemory,\n)\nfrom langmem.knowledge import (\n KnowledgeBase,\n DocumentProcessor,\n)\nfrom langmem.prompts import (\n PromptTemplate,\n ChatPromptTemplate,\n)\n```\n\n所有导出的类和函数都遵循以下规范：\n- 完整的类型注解\n- 详细的文档字符串\n- 统一的错误处理机制\n\n资料来源：[src/langmem/__init__.py:1-60]()\n\n## 数据流架构\n\n### 写入流程\n\n```mermaid\nsequenceDiagram\n participant U as 用户\n participant M as 记忆模块\n participant LG as LangGraph\n participant VS as 向量存储\n participant KB as 知识库\n \n U->>M: 输入消息\n M->>LG: 创建状态\n LG->>LG: 处理状态转换\n LG->>KB: 存储知识\n LG->>VS: 存储向量\n LG->>M: 更新记忆\n M->>U: 确认写入\n```\n\n### 读取流程\n\n```mermaid\nsequenceDiagram\n participant U as 用户\n participant M as 记忆模块\n participant LG as LangGraph\n participant VS as 向量存储\n participant KB as 知识库\n \n U->>M: 查询请求\n M->>LG: 创建检索状态\n LG->>VS: 相似度搜索\n LG->>KB: 知识检索\n VS->>LG: 返回结果\n KB->>LG: 返回上下文\n LG->>M: 合并结果\n M->>U: 返回上下文\n```\n\n## 后端存储架构\n\nLangMem 支持多种向量存储后端，提供了统一的上层抽象接口。\n\n| 后端类型 | 支持功能 | 适用场景 |\n|----------|----------|----------|\n| 内存存储 | 快速原型开发 | 开发调试 |\n| SQLite | 本地持久化 | 小规模应用 |\n| Chroma | 嵌入式向量 | 单机应用 |\n| Pinecone | 云端托管 | 生产环境 |\n| Weaviate | 混合搜索 | 企业级应用 |\n| Qdrant | 高性能检索 | 实时应用 |\n\n存储层采用适配器模式，每种后端都实现了统一的接口：\n- `add_documents()`：添加文档\n- `similarity_search()`：相似度搜索\n- `delete()`：删除文档\n- `update()`：更新文档\n\n## 扩展性设计\n\n### 插件接口\n\nLangMem 通过以下方式支持扩展：\n\n1. **自定义记忆类**：继承基础 `BaseMemory` 类并实现必需方法\n2. **自定义检索器**：实现 `BaseRetriever` 接口\n3. **自定义后端**：实现存储适配器接口\n4. **自定义评估器**：扩展评估指标集\n\n### 配置机制\n\n系统通过以下方式支持灵活配置：\n- 环境变量配置\n- YAML/JSON 配置文件\n- 运行时参数注入\n- 依赖注入容器\n\n## 技术栈总结\n\n| 层级 | 技术选型 | 作用 |\n|------|----------|------|\n| 核心框架 | Python 3.10+ | 开发语言 |\n| LLM 集成 | LangChain | 模型调用抽象 |\n| 状态管理 | LangGraph | 工作流编排 |\n| 类型系统 | Pydantic | 数据验证 |\n| 向量存储 | 多后端支持 | 持久化存储 |\n| 文档处理 | LangChain 生态 | 文本处理 |\n\nLangMem 的架构设计充分考虑了模块化、可扩展性和易用性，通过清晰的层次划分和标准化的接口定义，为开发者提供了构建智能记忆系统的基础设施。\n\n---\n\n\n\n## 记忆工具\n\n### 相关页面\n\n相关主题：[系统架构](#page-system-architecture), [记忆提取](#page-memory-extraction)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/langmem/knowledge/tools.py](https://github.com/langchain-ai/langmem/blob/main/src/langmem/knowledge/tools.py)\n- [src/langmem/knowledge/extraction.py](https://github.com/langchain-ai/langmem/blob/main/src/langmem/knowledge/extraction.py)\n- [src/langmem/knowledge/manager.py](https://github.com/langchain-ai/langmem/blob/main/src/langmem/knowledge/manager.py)\n- [src/langmem/prompts/types.py](https://github.com/langchain-ai/langmem/blob/main/src/langmem/prompts/types.py)\n- [examples/standalone_examples/README.md](https://github.com/langchain-ai/langmem/blob/main/examples/standalone_examples/README.md)\n \n\n# 记忆工具\n\nLangMem 的记忆工具（Memory Tools）是一组用于在 LangGraph 应用中管理长期记忆的函数式工具集。这些工具以 LangChain Tool 的形式实现，允许 AI 助手通过函数调用来创建、更新、删除和搜索记忆内容。\n\n## 概述与核心定位\n\n记忆工具是 LangMem 知识管理系统的两大核心组件之一（另一个是记忆管理器）。与自动化的 `MemoryStoreManager` 不同，记忆工具将记忆的管理权直接交给 AI 代理，使其能够根据对话上下文主动决定何时以及如何操作记忆存储。\n\n### 主要功能特性\n\n| 功能 | 说明 |\n|------|------|\n| 创建记忆 | AI 可主动将重要信息存储为持久记忆 |\n| 更新记忆 | 修改已存在的记忆内容 |\n| 删除记忆 | 移除不再需要的记忆 |\n| 搜索记忆 | 基于语义或精确匹配查找相关记忆 |\n\n资料来源：[src/langmem/knowledge/tools.py:1-50]()\n\n## 架构设计\n\n### 工具类型\n\nLangMem 提供两种主要的记忆工具：\n\n```mermaid\ngraph TD\n A[记忆工具模块] --> B[create_manage_memory_tool]\n A --> C[create_search_memory_tool]\n B --> D[创建/更新/删除]\n C --> E[语义搜索/精确匹配]\n```\n\n- **`create_manage_memory_tool`**：管理工具，用于创建、更新、删除记忆\n- **`create_search_memory_tool`**：搜索工具，用于检索已存储的记忆\n\n资料来源：[src/langmem/knowledge/tools.py:180-250]()\n\n### 与 BaseStore 的集成\n\n记忆工具通过 LangGraph 的 `BaseStore` 接口与底层存储层交互。工具内部会从运行时配置中获取 store 实例：\n\n```mermaid\nsequenceDiagram\n participant Agent as AI代理\n participant Tool as 记忆工具\n participant Store as BaseStore\n participant Config as 运行时配置\n\n Agent->>Tool: 调用工具函数\n Tool->>Config: 获取 store 实例\n Config-->>Tool: BaseStore 实例\n Tool->>Store: 执行存储操作\n Store-->>Tool: 操作结果\n Tool-->>Agent: 返回结果\n```\n\n资料来源：[src/langmem/knowledge/tools.py:230-280]()\n\n## create_manage_memory_tool\n\n`create_manage_memory_tool` 函数创建一个允许 AI 代理管理记忆的 LangChain 工具。\n\n### 函数签名\n\n```python\ndef create_manage_memory_tool(\n namespace: tuple[str, ...] | str,\n *,\n schema: type[BaseModel] | None = None,\n actions_permitted: list[Literal[\"create\", \"update\", \"delete\"]] | None = None,\n instructions: str = \"\",\n store: BaseStore | None = None,\n name: str = \"manage_memory\",\n)\n```\n\n### 参数说明\n\n| 参数 | 类型 | 默认值 | 说明 |\n|------|------|--------|------|\n| `namespace` | `tuple[str, ...] \\| str` | 必需 | 记忆的命名空间路径，支持占位符如 `{langgraph_user_id}` |\n| `schema` | `type[BaseModel] \\| None` | `None` | 记忆内容的数据模型（Pydantic BaseModel） |\n| `actions_permitted` | `list[Literal[\"create\", \"update\", \"delete\"]] \\| None` | `None` | 允许的操作类型列表 |\n| `instructions` | `str` | `\"\"` | 给 AI 的额外使用说明 |\n| `store` | `BaseStore \\| None` | `None` | 底层存储实例 |\n| `name` | `str` | `\"manage_memory\"` | 工具名称 |\n\n资料来源：[src/langmem/knowledge/tools.py:120-175]()\n\n### 命名空间配置\n\n命名空间支持运行时配置替换，通过 `{config_key}` 占位符实现：\n\n```python\nmemory_tool = create_manage_memory_tool(\n namespace=(\"memories\", \"{langgraph_user_id}\", \"user_profile\"),\n)\n```\n\n运行时配置示例：\n\n```python\nconfig = {\"configurable\": {\"langgraph_user_id\": \"user-123\"}}\n# 实际命名空间: (\"memories\", \"user-123\", \"user_profile\")\n```\n\n资料来源：[src/langmem/knowledge/tools.py:140-160]()\n\n### 自定义 Schema\n\n可以通过 Pydantic 模型定义记忆的数据结构：\n\n```python\nfrom pydantic import BaseModel\n\nclass UserProfile(BaseModel):\n name: str\n age: int | None = None\n recent_memories: list[str] = []\n preferences: dict | None = None\n\nmemory_tool = create_manage_memory_tool(\n namespace=(\"memories\", \"{langgraph_user_id}\"),\n schema=UserProfile,\n actions_permitted=[\"create\", \"update\"],\n)\n```\n\n资料来源：[src/langmem/knowledge/tools.py:220-245]()\n\n### 操作限制\n\n通过 `actions_permitted` 参数限制 AI 可执行的操作：\n\n```python\n# 仅允许创建和更新，不允许删除\nmemory_tool = create_manage_memory_tool(\n namespace=(\"memories\", \"{langgraph_user_id}\"),\n actions_permitted=[\"create\", \"update\"],\n)\n```\n\n工具描述会根据允许的操作自动生成：\n\n- 单操作：`\"{操作名} a memory\"`\n- 双操作：`\"{操作1} or {操作2} a memory\"`\n- 多操作：`\"{操作1}, {操作2}, or {操作3} a memory\"`\n\n资料来源：[src/langmem/knowledge/tools.py:265-285]()\n\n## create_search_memory_tool\n\n`create_search_memory_tool` 函数创建一个用于搜索记忆的 LangChain 工具。\n\n### 函数签名\n\n```python\ndef create_search_memory_tool(\n namespace: tuple[str, ...] | str,\n *,\n instructions: str = _MEMORY_SEARCH_INSTRUCTIONS,\n store: BaseStore | None = None,\n response_format: Literal[\"content\", \"content_and_artifact\"] = \"content\",\n name: str = \"search_memory\",\n)\n```\n\n### 参数说明\n\n| 参数 | 类型 | 默认值 | 说明 |\n|------|------|--------|------|\n| `namespace` | `tuple[str, ...] \\| str` | 必需 | 搜索范围的命名空间 |\n| `instructions` | `str` | `\"\"` | 搜索工具的使用说明 |\n| `store` | `BaseStore \\| None` | `None` | 底层存储实例 |\n| `response_format` | `Literal[\"content\", \"content_and_artifact\"]` | `\"content\"` | 返回格式 |\n| `name` | `str` | `\"search_memory\"` | 工具名称 |\n\n资料来源：[src/langmem/knowledge/tools.py:295-340]()\n\n### 返回格式\n\n- **`content`**：仅返回记忆内容（字符串）\n- **`content_and_artifact`**：返回元组 `(serialized_memories, raw_memories)`\n\n```python\nsearch_tool = create_search_memory_tool(\n namespace=(\"memories\", \"{langgraph_user_id}\"),\n response_format=\"content_and_artifact\",\n)\n```\n\n资料来源：[src/langmem/knowledge/tools.py:320-325]()\n\n## 使用示例\n\n### 在 create_react_agent 中使用\n\n将记忆工具集成到 LangGraph 的预构建 ReAct 代理中：\n\n```python\nfrom langgraph.prebuilt import create_react_agent\nfrom langgraph.config import get_config, get_store\nfrom langmem import create_manage_memory_tool\n\ndef prompt(state):\n config = get_config()\n memories = get_store().search(\n (\"memories\", config[\"configurable\"][\"langgraph_user_id\"]),\n )\n system_prompt = f\"\"\"You are a helpful assistant.\n\n{memories}\n\n\"\"\"\n return [{\"role\": \"system\", \"content\": system_prompt}, *state[\"messages\"]]\n\nagent = create_react_agent(\n \"anthropic:claude-3-5-sonnet-latest\",\n tools=[create_manage_memory_tool(\n namespace=(\"memories\", \"{langgraph_user_id}\")\n )],\n store=store,\n)\n\nagent.invoke(\n {\"messages\": [{\"role\": \"user\", \"content\": \"我喜欢用 Python 写后端\"}]},\n config=config,\n)\n```\n\n资料来源：[src/langmem/knowledge/tools.py:45-75]()\n\n### 完整的工作流示例\n\n```mermaid\nsequenceDiagram\n participant User as 用户\n participant Agent as ReAct代理\n participant Tool as 记忆工具\n participant Store as InMemoryStore\n\n User->>Agent: \"我偏好深色模式\"\n Agent->>Tool: manage_memory(content, action=\"create\")\n Tool->>Store: put(namespace, key, value)\n Store-->>Tool: MemoryItem\n Tool-->>Agent: \"已记住您的偏好\"\n Agent-->>User: 响应\n\n User->>Agent: \"我改变了主意\"\n Agent->>Tool: manage_memory(id, action=\"update\")\n Tool->>Store: put(namespace, id, new_value)\n Store-->>Tool: Updated\n Agent-->>User: \"已更新您的偏好\"\n```\n\n资料来源：[src/langmem/knowledge/tools.py:75-110]()\n\n### 在独立应用中使用\n\n记忆工具也可以在 LangGraph 外部的独立应用中使用：\n\n```python\nfrom langmem import create_memory_manager\nfrom langgraph.store.memory import InMemoryStore\nfrom pydantic import BaseModel\n\nclass PreferenceMemory(BaseModel):\n category: str\n preference: str\n context: str\n\nstore = InMemoryStore(\n index={\n \"dims\": 1536,\n \"embed\": \"openai:text-embedding-3-small\",\n }\n)\n\n# 独立使用管理器\nmanager = create_memory_manager(\n \"anthropic:claude-3-5-sonnet-latest\",\n schemas=[PreferenceMemory],\n)\n\nconversation = [\n {\"role\": \"user\", \"content\": \"I prefer dark mode in all my apps\"},\n {\"role\": \"assistant\", \"content\": \"I'll remember that preference\"},\n]\n\nmemories = manager.invoke({\"messages\": conversation})\nprint(memories)\n```\n\n资料来源：[examples/standalone_examples/README.md:1-45]()\n\n## 工具与运行时的绑定\n\n### store 参数\n\n`store` 参数用于指定底层存储。如果为 `None`，工具会在运行时从 LangGraph 的配置上下文中获取 store：\n\n```python\n# 方式一：创建时指定 store\nstore = InMemoryStore(index={\"dims\": 1536, \"embed\": \"openai:text-embedding-3-small\"})\nmanage_tool = create_manage_memory_tool(namespace=(\"mem\", \"{uid}\"), store=store)\n\n# 方式二：运行时从 @entrypoint 获取\n# 在 @entrypoint(store=store) 装饰的函数中，store 会自动可用\n```\n\n资料来源：[src/langmem/knowledge/tools.py:225-240]()\n\n### 命名空间的动态解析\n\n命名空间中的占位符在运行时通过 `configurable` 配置解析：\n\n```python\nconfig = {\n \"configurable\": {\n \"langgraph_user_id\": \"user123\",\n \"team_id\": \"engineering\"\n }\n}\n\n# namespace = (\"memories\", \"{langgraph_user_id}\", \"{team_id}\")\n# 解析为: (\"memories\", \"user123\", \"engineering\")\n```\n\n资料来源：[src/langmem/knowledge/tools.py:145-155]()\n\n## 与记忆管理器的对比\n\n| 特性 | 记忆工具 | 记忆管理器 |\n|------|----------|------------|\n| 控制方式 | AI 主动调用 | 自动处理 |\n| 适用场景 | 需要 AI 自主决策 | 需要自动化流程 |\n| 灵活性 | 高 | 中 |\n| 复杂度 | 低 | 中 |\n| 批量操作 | 不支持 | 支持 |\n\n记忆工具适合需要 AI 自主管理记忆的场景，而记忆管理器（如 `create_memory_manager`、`create_memory_store_manager`）适合需要自动从对话中提取和组织记忆的场景。\n\n资料来源：[src/langmem/knowledge/extraction.py:50-150]()\n\n## 最佳实践\n\n### 1. 限制操作权限\n\n始终通过 `actions_permitted` 限制 AI 可执行的操作，防止意外删除重要记忆：\n\n```python\nmanage_tool = create_manage_memory_tool(\n namespace=(\"memories\", \"{user_id}\"),\n actions_permitted=[\"create\", \"update\"], # 禁止删除\n)\n```\n\n### 2. 使用 Schema 验证\n\n通过 Pydantic schema 确保记忆数据结构的一致性：\n\n```python\nclass Memory(BaseModel):\n content: str\n tags: list[str] = []\n priority: int = 0\n\nmanage_tool = create_manage_memory_tool(\n namespace=(\"memories\", \"{user_id}\"),\n schema=Memory,\n)\n```\n\n### 3. 分离搜索和管理\n\n在复杂应用中，建议分别创建搜索和管理工具：\n\n```python\nfrom langmem import create_manage_memory_tool, create_search_memory_tool\n\nmanage = create_manage_memory_tool(\n namespace=(\"memories\", \"{user_id}\"),\n actions_permitted=[\"create\", \"update\", \"delete\"],\n)\n\nsearch = create_search_memory_tool(\n namespace=(\"memories\", \"{user_id}\"),\n)\n\nagent = create_react_agent(\n model=\"anthropic:claude-3-5-sonnet-latest\",\n tools=[manage, search],\n store=store,\n)\n```\n\n### 4. 提供清晰的说明\n\n通过 `instructions` 参数提供工具使用指导：\n\n```python\nmanage_tool = create_manage_memory_tool(\n namespace=(\"preferences\", \"{user_id}\"),\n instructions=\"仅在用户明确表达偏好时创建记忆，避免过度记录。\",\n)\n```\n\n## 注意事项\n\n1. **store 必须可用**：工具依赖 LangGraph 的 BaseStore，在 `@entrypoint` 或 `create_react_agent` 中使用时会自动注入。\n\n2. **命名空间唯一性**：每个用户的记忆应使用独立的命名空间路径。\n\n3. **异步支持**：工具同时支持同步（`invoke`）和异步（`ainvoke`）调用。\n\n4. **Schema 兼容性**：自定义 schema 必须与已存储的记忆数据结构兼容，否则会导致验证失败。\n\n5. **ID 必填规则**：更新和删除操作需要提供记忆的 UUID，AI 在调用工具时必须包含此参数。\n\n资料来源：[src/langmem/knowledge/tools.py:180-220]()\n\n## 导出清单\n\n```python\n__all__ = [\n \"create_manage_memory_tool\",\n \"create_search_memory_tool\",\n]\n```\n\n资料来源：[src/langmem/knowledge/tools.py:350-355]()\n\n---\n\n\n\n## 记忆提取\n\n### 相关页面\n\n相关主题：[语义记忆管理](#page-semantic-memory), [情景记忆提取](#page-episodic-memory), [后台处理快速开始](#page-background-quickstart)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/langmem/knowledge/extraction.py](https://github.com/langchain-ai/langmem/blob/main/src/langmem/knowledge/extraction.py)\n- [src/langmem/knowledge/tools.py](https://github.com/langchain-ai/langmem/blob/main/src/langmem/knowledge/tools.py)\n- [src/langmem/prompts/types.py](https://github.com/langchain-ai/langmem/blob/main/src/langmem/prompts/types.py)\n- [src/langmem/graphs/semantic.py](https://github.com/langchain-ai/langmem/blob/main/src/langmem/graphs/semantic.py)\n- [src/langmem/short_term/summarization.py](https://github.com/langchain-ai/langmem/blob/main/src/langmem/short_term/summarization.py)\n \n\n# 记忆提取\n\n记忆提取（Memory Extraction）是 langmem 库中用于从对话或交互轨迹中识别、提取和存储有价值信息的核心功能模块。该模块通过大语言模型（LLM）分析对话内容，自动识别用户偏好、关键事实、上下文信息等结构化记忆，并支持持久化存储以便后续检索和使用。\n\n## 核心概念\n\n### 什么是记忆提取\n\n记忆提取是一种自动化的信息处理流程，它从非结构化的对话数据中识别并提取结构化的记忆信息。这些记忆信息经过处理后可以用于：\n\n- 个性化响应生成\n- 上下文连续性维护\n- 用户偏好跟踪\n- 对话状态管理\n\n资料来源：[src/langmem/knowledge/extraction.py:1-50]()\n\n### 记忆类型\n\nlangmem 支持多种类型的记忆提取模式：\n\n| 记忆类型 | 描述 | 适用场景 |\n|---------|------|---------|\n| 实体记忆 | 提取人名、地点、事件等实体信息 | 事实性信息存储 |\n| 偏好记忆 | 记录用户偏好、习惯、偏好设置 | 个性化服务 |\n| 上下文记忆 | 保存对话上下文和会话状态 | 多轮对话支持 |\n| 关系记忆 | 记录实体之间的关系和关联 | 知识图谱构建 |\n\n资料来源：[src/langmem/prompts/types.py:1-80]()\n\n## 架构设计\n\n### 整体架构\n\n```mermaid\ngraph TD\n A[对话输入] --> B[记忆管理器
MemoryManager]\n B --> C{提取模式}\n C -->|LLM分析| D[模式匹配]\n C -->|向量搜索| E[语义检索]\n D --> F[记忆存储]\n E --> F\n F --> G[结构化记忆]\n G --> H[长期存储
MemoryStore]\n G --> I[短期记忆
Summarization]\n```\n\n### 核心组件\n\n| 组件 | 职责 | 文件位置 |\n|------|------|---------|\n| MemoryManager | 记忆提取的主控制器 | extraction.py |\n| MemoryStoreManager | 支持向量存储的记忆管理 | extraction.py |\n| SummarizationNode | 短期记忆压缩节点 | summarization.py |\n| SemanticMemoryGraph | 语义记忆图结构 | semantic.py |\n| create_manage_memory_tool | 记忆管理工具 | tools.py |\n| create_search_memory_tool | 记忆搜索工具 | tools.py |\n\n资料来源：[src/langmem/knowledge/extraction.py:100-200]()\n\n## MemoryManager 详解\n\n### 初始化配置\n\n`create_memory_manager` 函数用于创建记忆管理器实例：\n\n```python\nfrom langmem import create_memory_manager\n\nmanager = create_memory_manager(\n \"anthropic:claude-3-5-sonnet-latest\",\n schemas=[PreferenceMemory], # Pydantic schema 定义\n instructions=\"从对话中提取用户偏好信息\",\n enable_inserts=True,\n enable_updates=True,\n enable_deletes=True,\n)\n```\n\n### 配置参数表\n\n| 参数 | 类型 | 默认值 | 说明 |\n|------|------|--------|------|\n| model | str \\| BaseChatModel | 必填 | 用于记忆提取的 LLM |\n| schemas | list[type[BaseModel]] | None | 记忆数据结构定义 |\n| instructions | str | None | 提取指令提示 |\n| enable_inserts | bool | True | 是否启用插入操作 |\n| enable_updates | bool | True | 是否启用更新操作 |\n| enable_deletes | bool | True | 是否启用删除操作 |\n\n资料来源：[src/langmem/knowledge/extraction.py:200-300]()\n\n### 调用方式\n\n#### 异步调用\n\n```python\nconversation = [\n {\"role\": \"user\", \"content\": \"我偏好深色模式\"},\n {\"role\": \"assistant\", \"content\": \"好的，已记住您的偏好\"},\n]\n\nmemories = await manager.ainvoke(\n {\"messages\": conversation, \"max_steps\": 3}\n)\n```\n\n#### 同步调用\n\n```python\nmemories = manager.invoke({\"messages\": conversation})\n```\n\n资料来源：[src/langmem/knowledge/extraction.py:250-280]()\n\n## MemoryStoreManager 详解\n\n### 概述\n\n`MemoryStoreManager` 是支持向量存储的增强版记忆管理器，集成了语义搜索能力：\n\n```python\nfrom langmem import create_memory_store_manager\nfrom langgraph.store.memory import InMemoryStore\n\nstore = InMemoryStore(\n index={\n \"dims\": 1536,\n \"embed\": \"openai:text-embedding-3-small\",\n }\n)\n\nmanager = create_memory_store_manager(\n \"anthropic:claude-3-5-sonnet-latest\",\n query_model=\"anthropic:claude-3-5-haiku-latest\",\n query_limit=10,\n namespace=(\"memories\", \"{langgraph_user_id}\"),\n store=store,\n)\n```\n\n### 与 MemoryManager 的区别\n\n| 特性 | MemoryManager | MemoryStoreManager |\n|------|---------------|-------------------|\n| 存储后端 | 内存/外部 | 向量存储 |\n| 语义搜索 | ✗ | ✓ |\n| 查询优化 | 基础 | 高级（LLM生成查询） |\n| 适用场景 | 快速原型 | 生产环境 |\n\n资料来源：[src/langmem/knowledge/extraction.py:300-400]()\n\n### 工作流程\n\n```mermaid\nsequenceDiagram\n participant Client\n participant Manager as MemoryStoreManager\n participant QueryLLM\n participant Store as VectorStore\n participant MainLLM\n\n Client->>Manager: 消息输入\n Manager->>QueryLLM: 生成搜索查询\n QueryLLM-->>Manager: 优化后的查询\n Manager->>Store: 语义检索\n Store-->>Manager: 相关记忆\n Manager->>MainLLM: 分析并提取\n MainLLM-->>Manager: 更新后的记忆\n Manager->>Store: 持久化存储\n Manager-->>Client: 提取结果\n```\n\n### 搜索功能\n\n```python\n# 自然语言搜索\nresults = await manager.asearch(\n query=\"用户在医疗领域的偏好\",\n filter={\"type\": \"research_paper\"},\n limit=5,\n)\n\n# 同步搜索\nresults = manager.search(query=\"app preferences\")\n```\n\n资料来源：[src/langmem/knowledge/extraction.py:80-120]()\n\n## 短期记忆压缩\n\n### SummarizationNode\n\n`SummarizationNode` 用于在对话过程中压缩和摘要消息，保持上下文的同时减少 token 消耗：\n\n```python\nfrom langmem.short_term import SummarizationNode, RunningSummary\n\nsummarization_node = SummarizationNode(\n model=summarization_model,\n max_tokens=256,\n max_tokens_before_summary=256,\n max_summary_tokens=128,\n)\n```\n\n### 配置参数\n\n| 参数 | 类型 | 说明 |\n|------|------|------|\n| model | Runnable | 用于摘要生成的 LLM |\n| max_tokens | int | 单次摘要的最大 token 数 |\n| max_tokens_before_summary | int | 触发摘要前的最大 token 数 |\n| max_summary_tokens | int | 摘要内容本身的最大 token 数 |\n| input_messages_key | str | 输入消息的字段名，默认 \"messages\" |\n| output_messages_key | str | 输出消息的字段名，默认 \"messages\" |\n| snapshot_mode | SnapshotMode | 快照模式配置 |\n\n资料来源：[src/langmem/short_term/summarization.py:1-100]()\n\n### 状态更新格式\n\n```json\n{\n \"output_messages_key\": [\n \"<更新的消息列表，包含摘要消息>\"\n ],\n \"context\": {\n \"running_summary\": \"\"\n }\n}\n```\n\n## 语义记忆图\n\n### SemanticMemoryGraph\n\n`SemanticMemoryGraph` 提供基于语义图的记忆组织方式：\n\n```mermaid\ngraph LR\n A[用户输入] --> B[语义解析]\n B --> C[实体识别]\n C --> D[关系抽取]\n D --> E[图结构更新]\n E --> F[记忆节点]\n F --> G[关系边]\n G --> H[语义记忆图]\n```\n\n### 核心功能\n\n| 功能 | 说明 |\n|------|------|\n| 实体提取 | 从对话中识别关键实体 |\n| 关系抽取 | 建立实体间的语义关系 |\n| 图查询 | 支持复杂的关系查询 |\n| 动态更新 | 随对话进行实时更新 |\n\n资料来源：[src/langmem/graphs/semantic.py:1-50]()\n\n## 工具函数\n\n### 记忆管理工具\n\n`create_manage_memory_tool` 创建一个 LangGraph 可用的记忆管理工具：\n\n```python\nfrom langmem import create_manage_memory_tool\n\nmanage_tool = create_manage_memory_tool(\n namespace=(\"memories\", \"{langgraph_user_id}\"),\n schema=UserMemory,\n actions_permitted=[\"create\", \"update\", \"delete\"],\n)\n```\n\n### 参数说明\n\n| 参数 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| namespace | tuple[str, ...] | 是 | 记忆的命名空间路径 |\n| schema | type[BaseModel] | 否 | 记忆的数据结构 |\n| actions_permitted | list | 是 | 允许的操作类型 |\n| store | BaseStore | 否 | 底层存储后端 |\n\n资料来源：[src/langmem/knowledge/tools.py:1-100]()\n\n### 记忆搜索工具\n\n`create_search_memory_tool` 创建一个语义搜索工具：\n\n```python\nfrom langmem import create_search_memory_tool\n\nsearch_tool = create_search_memory_tool(\n namespace=(\"project_memories\", \"{langgraph_user_id}\"),\n)\n\n# 在 LangGraph 中使用\nmemories, _ = await search_tool.ainvoke(\n {\"query\": \"Python preferences\", \"limit\": 5}\n)\n```\n\n## 使用示例\n\n### 基础示例\n\n```python\nfrom langmem import create_memory_manager\nfrom pydantic import BaseModel\n\nclass PreferenceMemory(BaseModel):\n category: str\n preference: str\n context: str\n\nmanager = create_memory_manager(\n \"anthropic:claude-3-5-sonnet-latest\",\n schemas=[PreferenceMemory],\n)\n\nconversation = [\n {\"role\": \"user\", \"content\": \"我偏好所有应用都使用深色模式\"},\n {\"role\": \"assistant\", \"content\": \"好的，我会记住这个偏好\"},\n]\n\nmemories = await manager.ainvoke({\"messages\": conversation})\nprint(memories)\n```\n\n### 带配置的完整示例\n\n```python\nfrom langmem import create_memory_store_manager, ReflectionExecutor\nfrom langgraph.prebuilt import create_react_agent\nfrom langgraph.store.memory import InMemoryStore\nfrom langgraph.func import entrypoint\n\nstore = InMemoryStore(\n index={\n \"dims\": 1536,\n \"embed\": \"openai:text-embedding-3-small\",\n }\n)\n\nmanager = create_memory_store_manager(\n \"anthropic:claude-3-5-sonnet-latest\",\n namespace=(\"memories\", \"{langgraph_user_id}\"),\n)\n\nreflection = ReflectionExecutor(manager, store=store)\nagent = create_react_agent(\n \"anthropic:claude-3-5-sonnet-latest\",\n tools=[create_manage_memory_tool(namespace=(\"memories\", \"{langgraph_user_id}\"))],\n store=store,\n)\n```\n\n### 在 LangGraph 中使用\n\n```python\nfrom langgraph.prebuilt import create_react_agent\nfrom langgraph.config import get_config, get_store\n\ndef prompt(state):\n config = get_config()\n memories = get_store().search(\n (\"memories\", config[\"configurable\"][\"langgraph_user_id\"]),\n )\n system_prompt = f\"\"\"你是一个有帮助的助手。\n <记忆>\n {memories}\n \n \"\"\"\n return [{\"role\": \"system\", \"content\": system_prompt}, *state[\"messages\"]]\n\nagent = create_react_agent(\n \"anthropic:claude-3-5-sonnet-latest\",\n tools=[create_manage_memory_tool(namespace=(\"memories\", \"{langgraph_user_id}\"))],\n)\n\nagent.invoke(\n {\"messages\": [{\"role\": \"user\", \"content\": \"我们决定用 golang 代替 python 做后端\"}]},\n config=config,\n)\n```\n\n资料来源：[src/langmem/knowledge/tools.py:100-200]()\n\n## 数据结构\n\n### AnnotatedTrajectory\n\n用于表示带反馈的对话轨迹：\n\n```python\ntrajectory = AnnotatedTrajectory(\n messages=[\n {\"role\": \"user\", \"content\": \"有什么好的披萨推荐？\"},\n {\"role\": \"assistant\", \"content\": \"推荐尝试 LangPizza™️\"},\n {\"role\": \"user\", \"content\": \"别给我打广告\"},\n {\"role\": \"assistant\", \"content\": \"但你会喜欢的！\"},\n ],\n feedback={\n \"developer_feedback\": \"太激进了\",\n \"score\": 0,\n },\n)\n```\n\n### OptimizerInput\n\n用于单提示优化场景的输入结构：\n\n```python\ninput_data = OptimizerInput(\n trajectories=[\n AnnotatedTrajectory(\n messages=[...],\n feedback=\"应该使用搜索工具\",\n )\n ],\n prompt=Prompt(\n name=\"main_assistant\",\n prompt=\"你是一个有帮助的助手，有搜索工具可用。\",\n update_instructions=\"仅做最小更改，专注于修复错误的地方。\",\n ),\n)\n```\n\n资料来源：[src/langmem/prompts/types.py:50-120]()\n\n## 配置最佳实践\n\n### 命名空间配置\n\n| 占位符 | 说明 | 示例 |\n|--------|------|------|\n| `{langgraph_user_id}` | 用户唯一标识 | memories/user123 |\n| `{session_id}` | 会话标识 | memories/user123/session456 |\n| `{custom_key}` | 自定义键 | memories/user123/custom |\n\n### 性能优化建议\n\n1. **批量处理**：将多个相关对话合并处理\n2. **增量更新**：使用 `enable_updates=True` 避免重复存储\n3. **搜索限制**：设置合理的 `query_limit` 减少检索开销\n4. **摘要压缩**：对于长对话使用 `SummarizationNode` 减少 token\n\n### 安全考虑\n\n- 命名空间隔离：不同用户使用不同命名空间\n- 操作权限：仅启用必要的 CRUD 操作\n- Schema 验证：使用 Pydantic 模型确保数据一致性\n\n## 相关模块\n\n| 模块 | 文件路径 | 用途 |\n|------|----------|------|\n| prompts.types | prompts/types.py | 类型定义和数据结构 |\n| prompts.optimization | prompts/optimization.py | 提示词优化集成 |\n| prompts.prompt | prompts/prompt.py | 提示模板 |\n| prompts.gradient | prompts/gradient.py | 梯度提示优化器 |\n| short_term | short_term/summarization.py | 短期记忆压缩 |\n\n## 总结\n\n记忆提取是 langmem 提供的核心能力之一，它通过结构化的方式从对话中提取有价值的信息，并通过 MemoryManager 和 MemoryStoreManager 两个主要接口提供灵活的存储和检索能力。结合短期记忆压缩和语义搜索功能，langmem 能够构建完整的记忆系统，支持各种需要上下文持久化的 AI 应用场景。\n\n---\n\n\n\n## 提示优化\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/langmem/prompts/optimization.py](https://github.com/langchain-ai/langmem/blob/main/src/langmem/prompts/optimization.py)\n- [src/langmem/prompts/gradient.py](https://github.com/langchain-ai/langmem/blob/main/src/langmem/prompts/gradient.py)\n- [src/langmem/prompts/metaprompt.py](https://github.com/langchain-ai/langmem/blob/main/src/langmem/prompts/metaprompt.py)\n- [src/langmem/prompts/prompt.py](https://github.com/langchain-ai/langmem/blob/main/src/langmem/prompts/prompt.py)\n- [src/langmem/prompts/types.py](https://github.com/langchain-ai/langmem/blob/main/src/langmem/prompts/types.py)\n \n\n# 提示优化\n\n## 概述\n\n提示优化（Prompt Optimization）是 langmem 库中用于自动改进大型语言模型提示词的核心模块。该模块通过分析对话轨迹和反馈信息，自动调整和优化系统提示词，使 AI 代理能够更好地完成特定任务。\n\nlangmem 提供了三种主要的提示优化策略：\n\n| 优化类型 | 说明 | 使用场景 |\n|---------|------|---------|\n| **Gradient（梯度优化）** | 基于假设和推荐进行渐进式调整 | 需要分析失败原因并针对性改进 |\n| **Metaprompt（元提示优化）** | 通过元学习步骤进行深度优化 | 复杂任务需要多次反思 |\n| **Prompt Memory（提示记忆优化）** | 从历史交互中学习成功模式 | 积累经验持续改进 |\n\n## 核心组件\n\n### 类型定义\n\n提示优化模块使用强类型定义确保输入输出的准确性。\n\n#### OptimizerInput\n\n```python\nclass OptimizerInput(TypedDict):\n \"\"\"单提示优化的输入数据结构\"\"\"\n trajectories: typing.Sequence[AnnotatedTrajectory] | str\n prompt: str | Prompt\n```\n\n| 字段 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| `trajectories` | `Sequence[AnnotatedTrajectory] \\| str` | 是 | 对话轨迹列表或字符串描述 |\n| `prompt` | `str \\| Prompt` | 是 | 需要优化的提示词 |\n\n#### MultiPromptOptimizerInput\n\n```python\nclass MultiPromptOptimizerInput(TypedDict):\n \"\"\"多提示优化的输入数据结构\"\"\"\n trajectories: typing.Sequence[AnnotatedTrajectory] | str\n prompts: list[Prompt]\n```\n\n| 字段 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| `trajectories` | `Sequence[AnnotatedTrajectory] \\| str` | 是 | 对话轨迹列表 |\n| `prompts` | `list[Prompt]` | 是 | 需要一起优化的多个提示 |\n\n#### Prompt 结构\n\n```python\nclass Prompt(TypedDict, total=False):\n \"\"\"结构化提示管理\"\"\"\n name: Required[str] # 提示名称\n prompt: Required[str] # 提示内容\n update_instructions: str | None # 更新指令\n when_to_update: str | None # 更新时机\n```\n\n#### AnnotatedTrajectory 结构\n\n```python\nclass AnnotatedTrajectory(typing.NamedTuple):\n \"\"\"带标注的对话轨迹\"\"\"\n messages: typing.Sequence[AnyMessage] # 消息列表\n feedback: dict[str, str | int | bool] | str | None = None # 反馈信息\n```\n\n资料来源：[src/langmem/prompts/types.py:1-80](src/langmem/prompts/types.py)\n\n## API 接口\n\n### 创建单提示优化器\n\n```python\ndef create_prompt_optimizer(\n model: str | BaseChatModel,\n kind: typing.Literal[\"gradient\", \"metaprompt\", \"prompt_memory\"] = \"gradient\",\n *,\n config: typing.Optional[dict] = None,\n) -> Runnable[OptimizerInput, str]\n```\n\n| 参数 | 类型 | 默认值 | 说明 |\n|------|------|--------|------|\n| `model` | `str \\| BaseChatModel` | 必填 | 使用的语言模型 |\n| `kind` | `Literal[\"gradient\", \"metaprompt\", \"prompt_memory\"]` | `\"gradient\"` | 优化策略类型 |\n| `config` | `dict \\| None` | `None` | 优化器配置 |\n\n### 创建多提示优化器\n\n```python\ndef create_multi_prompt_optimizer(\n model: str | BaseChatModel,\n kind: typing.Literal[\"gradient\", \"metaprompt\", \"prompt_memory\"] = \"gradient\",\n *,\n config: typing.Optional[dict] = None,\n) -> Runnable[MultiPromptOptimizerInput, list[Prompt]]\n```\n\n| 参数 | 类型 | 默认值 | 说明 |\n|------|------|--------|------|\n| `model` | `str \\| BaseChatModel` | 必填 | 使用的语言模型 |\n| `kind` | `Literal[\"gradient\", \"metaprompt\", \"prompt_memory\"]` | `\"gradient\"` | 优化策略类型 |\n| `config` | `dict \\| None` | `None` | 优化器配置 |\n\n资料来源：[src/langmem/prompts/optimization.py](src/langmem/prompts/optimization.py)\n\n## 优化策略详解\n\n### 1. 梯度优化（Gradient Optimization）\n\n梯度优化是最基本的优化策略，通过分析对话轨迹中的假设和推荐进行提示词调整。\n\n```mermaid\ngraph TD\n A[输入轨迹和反馈] --> B[生成假设]\n B --> C[提出建议]\n C --> D[应用最小侵入性更改]\n D --> E[输出优化后的提示]\n```\n\n#### 工作流程\n\n1. **假设生成**：分析当前提示在处理对话轨迹时的潜在问题\n2. **建议生成**：基于假设提出具体的调整建议\n3. **应用更改**：仅实施必要的最小更改\n\n#### 配置选项\n\n| 配置项 | 类型 | 默认值 | 说明 |\n|--------|------|--------|------|\n| `max_reflection_steps` | `int` | 3 | 最大反思步数 |\n| `min_reflection_steps` | `int` | 1 | 最小反思步数 |\n| `gradient_prompt` | `str` | 默认模板 | 梯度优化的提示模板 |\n| `metaprompt` | `str` | 默认模板 | 元提示模板 |\n\n资料来源：[src/langmem/prompts/gradient.py](src/langmem/prompts/gradient.py)\n\n#### 使用示例\n\n```python\nfrom langmem import create_prompt_optimizer\n\noptimizer = create_prompt_optimizer(\n \"anthropic:claude-3-5-sonnet-latest\",\n kind=\"gradient\",\n config={\"max_reflection_steps\": 3}\n)\n\nconversation = [\n {\"role\": \"user\", \"content\": \"Tell me about the solar system\"},\n {\"role\": \"assistant\", \"content\": \"The solar system consists of...\"},\n]\nfeedback = {\"clarity\": \"needs more structure\"}\n\ntrajectories = [(conversation, feedback)]\nbetter_prompt = await optimizer.ainvoke(\n {\"trajectories\": trajectories, \"prompt\": \"You are an astronomy expert\"}\n)\n```\n\n### 2. 元提示优化（Metaprompt Optimization）\n\n元提示优化通过多步元学习过程进行深度反思，适合处理复杂的优化任务。\n\n```mermaid\ngraph TD\n A[输入当前提示] --> B[元级反思]\n B --> C{反思步数检查}\n C -->|未达到最小步数| B\n C -->|已达到最小步数| D[生成优化建议]\n D --> E[应用最终优化]\n E --> F[输出优化后的提示]\n```\n\n#### 配置选项\n\n| 配置项 | 类型 | 默认值 | 说明 |\n|--------|------|--------|------|\n| `max_reflection_steps` | `int` | 3 | 最大元学习步数 |\n| `min_reflection_steps` | `int` | 1 | 最小元学习步数 |\n\n#### 使用示例\n\n```python\nfrom langmem import create_prompt_optimizer\n\noptimizer = create_prompt_optimizer(\n \"anthropic:claude-3-5-sonnet-latest\",\n kind=\"metaprompt\",\n config={\"max_reflection_steps\": 3, \"min_reflection_steps\": 1}\n)\n\nconversation = [\n {\"role\": \"user\", \"content\": \"Explain quantum computing\"},\n {\"role\": \"assistant\", \"content\": \"Quantum computing uses...\"},\n]\nfeedback = \"Should include mathematical notation\"\n\ntrajectories = [(conversation, {\"feedback\": feedback})]\nbetter_prompt = await optimizer.ainvoke(\n {\"trajectories\": trajectories, \"prompt\": \"You are a physics tutor\"}\n)\n```\n\n资料来源：[src/langmem/prompts/metaprompt.py](src/langmem/prompts/metaprompt.py)\n\n### 3. 提示记忆优化（Prompt Memory Optimization）\n\n提示记忆优化从历史交互中学习成功模式，识别改进领域，并将学习到的模式应用到新提示中。\n\n```mermaid\ngraph TD\n A[历史轨迹数据] --> B[提取成功模式]\n A --> C[识别改进领域]\n B --> D[应用模式到新提示]\n C --> D\n D --> E[输出优化后的提示]\n```\n\n#### 核心特点\n\n- **模式提取**：从过去的成功交互中提取可复用的模式\n- **反馈分析**：识别反馈中指出的改进机会\n- **知识迁移**：将学习到的知识应用到新的提示优化中\n\n#### 使用示例\n\n```python\nfrom langmem import create_multi_prompt_optimizer\n\noptimizer = create_multi_prompt_optimizer(\n \"anthropic:claude-3-5-sonnet-latest\",\n kind=\"prompt_memory\"\n)\n\nconversation = [\n {\"role\": \"user\", \"content\": \"How do I write a bash script?\"},\n {\"role\": \"assistant\", \"content\": \"Let me explain bash scripting...\"},\n]\nfeedback = \"Response should include a code example\"\n\ntrajectories = [(conversation, {\"feedback\": feedback})]\nprompts = [\n {\"name\": \"explain\", \"prompt\": \"Explain the concept\"},\n {\"name\": \"example\", \"prompt\": \"Provide a practical example\"},\n]\n\nbetter_prompts = await optimizer.ainvoke(\n {\"trajectories\": trajectories, \"prompts\": prompts}\n)\n```\n\n## 提示反射模板\n\n### INSTRUCTION_REFLECTION_PROMPT\n\n用于单提示优化的反射模板：\n\n```python\nINSTRUCTION_REFLECTION_PROMPT = \"\"\"You are helping an AI agent improve. You can do this by changing their system prompt.\n\nThese is their current prompt:\n\n{current_prompt}\n\n\nHere was the agent's trajectory:\n\n{trajectory}\n\n\nHere is the user's feedback:\n\n\n{feedback}\n\n\nHere are instructions for updating the agent's prompt:\n\n\n{instructions}\n\n\n\nBased on this, return an updated prompt\"\"\"\n```\n\n### INSTRUCTION_REFLECTION_MULTIPLE_PROMPT\n\n用于多提示优化的反射模板，支持批量处理多个轨迹：\n\n```python\nINSTRUCTION_REFLECTION_MULTIPLE_PROMPT = \"\"\"You are helping an AI agent improve. You can do this by changing their system prompt.\n\nThese is their current prompt:\n\n{current_prompt}\n\n\nHere are examples of various agent trajectories and associated feedback:\n\n{data}\n\n\nHere are instructions for updating the agent's prompt:\n\n\n{instructions}\n\n\n\nBased on this, return an updated prompt\"\"\"\n```\n\n### GeneralResponse 结构\n\n优化器的返回响应结构：\n\n```python\nclass GeneralResponse(TypedDict):\n logic: str # 推理逻辑\n update_prompt: bool # 是否需要更新\n new_prompt: str # 新提示内容\n```\n\n资料来源：[src/langmem/prompts/prompt.py](src/langmem/prompts/prompt.py)\n\n## 梯度元提示模板\n\n梯度优化使用的默认元提示：\n\n```python\nDEFAULT_GRADIENT_METAPROMPT = \"\"\"You are optimizing a prompt to handle its target task more effectively.\n\n\n{current_prompt}\n\n\nWe hypothesize the current prompt underperforms for these reasons:\n\n\n{hypotheses}\n\n\nBased on these hypotheses, we recommend the following adjustments:\n\n\n{recommendations}\n\n\nRespond with the updated prompt. Remember to ONLY make changes that are clearly necessary. Aim to be minimally invasive:\"\"\"\n```\n\n资料来源：[src/langmem/prompts/gradient.py](src/langmem/prompts/gradient.py)\n\n## GradientPromptOptimizer 类\n\n基于类的梯度提示优化器实现，同时支持同步和异步调用：\n\n```python\nclass GradientPromptOptimizer(Runnable[GradientOptimizerInput, str]):\n \"\"\"\n Class-based Gradient Prompt Optimizer with both sync and async entry points.\n \"\"\"\n \n def __init__(\n self,\n model: Union[str, BaseChatModel],\n config: Optional[GradientOptimizerConfig] = None,\n ):\n self.model = model\n self.config = config or {}\n```\n\n### GradientOptimizerConfig 配置结构\n\n```python\nclass GradientOptimizerConfig(TypedDict, total=False):\n \"\"\"梯度优化器配置\"\"\"\n gradient_prompt: str # 梯度优化提示模板\n metaprompt: str # 元提示模板\n max_reflection_steps: int # 最大反思步数\n min_reflection_steps: int # 最小反思步数\n```\n\n### GradientOptimizerInput 输入结构\n\n```python\nclass GradientOptimizerInput(TypedDict, total=False):\n \"\"\"梯度优化器输入\"\"\"\n trajectories: prompt_types.OptimizerInput | str\n prompt: str | prompt_types.Prompt\n```\n\n## 最佳实践\n\n### 1. 选择合适的优化策略\n\n| 场景 | 推荐策略 |\n|------|---------|\n| 快速迭代 | Gradient（梯度优化） |\n| 复杂任务 | Metaprompt（元提示优化） |\n| 持续学习 | Prompt Memory（提示记忆优化） |\n\n### 2. 配置反思步数\n\n```python\n# 简单任务 - 快速优化\nconfig = {\"max_reflection_steps\": 1, \"min_reflection_steps\": 1}\n\n# 复杂任务 - 深度优化\nconfig = {\"max_reflection_steps\": 5, \"min_reflection_steps\": 2}\n```\n\n### 3. 提供有效反馈\n\n反馈应该包含：\n- 具体的问题描述\n- 期望的行为\n- 评分或等级（可选）\n\n### 4. 多提示协同优化\n\n当多个提示需要保持一致性时，使用 `create_multi_prompt_optimizer`：\n\n```python\nprompts = [\n Prompt(\n name=\"vision_extract\",\n prompt=\"Extract visual details from the image\",\n update_instructions=\"Focus on using vision model capabilities\",\n ),\n Prompt(\n name=\"vision_classify\",\n prompt=\"Classify specific attributes in the image\",\n when_to_update=\"After vision_extract is updated\",\n ),\n]\n```\n\n## 导出接口\n\n提示优化模块的公共 API：\n\n```python\n__all__ = [\n \"create_prompt_optimizer\",\n \"create_multi_prompt_optimizer\",\n \"Prompt\",\n \"AnnotatedTrajectory\",\n \"OptimizerInput\",\n \"MultiPromptOptimizerInput\",\n]\n```\n\n资料来源：[src/langmem/prompts/optimization.py](src/langmem/prompts/optimization.py)\n\n---\n\n\n\n## 语义记忆管理\n\n### 相关页面\n\n相关主题：[情景记忆提取](#page-episodic-memory), [记忆提取](#page-memory-extraction)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [docs/docs/guides/extract_semantic_memories.md](https://github.com/langchain-ai/langmem/blob/main/docs/docs/guides/extract_semantic_memories.md)\n- [src/langmem/graphs/semantic.py](https://github.com/langchain-ai/langmem/blob/main/src/langmem/graphs/semantic.py)\n \n\n# 语义记忆管理\n\n语义记忆管理是 LangMem 框架中用于从对话历史中自动提取、结构化和存储有意义信息的核心模块。它使 AI 系统能够跨会话保留和利用用户偏好、事实知识和上下文信息，从而提供更个性化和连贯的响应体验。\n\n## 核心概念\n\n### 什么是语义记忆\n\n语义记忆是一种结构化的知识表示形式，它从原始对话内容中提取关键信息，并以预定义的数据模式（Schema）进行存储。与简单的文本存储不同，语义记忆具有以下特征：\n\n| 特征 | 描述 |\n|------|------|\n| **结构化** | 使用 Pydantic 模型定义记忆的数据结构 |\n| **可查询** | 支持向量相似性搜索和精确过滤 |\n| **可演进** | 能够根据新信息自动更新现有记忆 |\n| **上下文相关** | 与特定用户或会话命名空间关联 |\n\n### 语义记忆 vs 其他记忆类型\n\n| 类型 | 用途 | 持久性 | 典型实现 |\n|------|------|--------|----------|\n| 语义记忆 | 长期偏好和知识 | 持久化 | `create_memory_store_manager` |\n| 短时记忆 | 当前会话上下文 | 会话级 | `SummarizationNode` |\n| 程序记忆 | 提示优化学习 | 元数据 | `create_prompt_optimizer` |\n\n资料来源：[src/langmem/knowledge/extraction.py:1-50]()\n\n## 架构概述\n\n### 系统组件\n\nLangMem 的语义记忆管理由以下核心组件构成：\n\n```mermaid\ngraph TD\n subgraph \"语义记忆管理系统\"\n A[对话消息] --> B[MemoryStoreManager]\n B --> C[提取器 Extractor]\n C --> D[Schema 验证]\n D --> E[记忆存储 Store]\n F[搜索查询] --> G[QueryLLM]\n G --> H[向量相似度匹配]\n H --> E\n end\n \n subgraph \"LangGraph 集成\"\n E --> I[InMemoryStore]\n I --> J[Agent 上下文]\n J --> A\n end\n```\n\n### 工作流程\n\n```mermaid\nsequenceDiagram\n participant User as 用户\n participant Agent as Agent\n participant Manager as MemoryStoreManager\n participant Extractor as 提取器\n participant Store as 记忆存储\n participant QueryLLM as 查询模型\n\n User->>Agent: 发送消息\n Agent-->>User: 生成响应\n Agent->>Manager: 提交对话历史\n Manager->>Extractor: 提取语义记忆\n Extractor->>Store: 存储/更新记忆\n Note over Store: 记忆持久化\n \n User->>Agent: 新请求\n Agent->>Manager: 搜索相关记忆\n Manager->>QueryLLM: 生成优化查询\n QueryLLM-->>Manager: 相似记忆\n Manager-->>Agent: 上下文记忆\n Agent-->>User: 个性化响应\n```\n\n资料来源：[src/langmem/knowledge/extraction.py:80-120]()\n\n## 核心 API\n\n### 创建语义记忆管理器\n\n```python\nfrom langmem import create_memory_store_manager\nfrom langgraph.store.memory import InMemoryStore\n\nmanager = create_memory_store_manager(\n \"anthropic:claude-3-5-sonnet-latest\", # 主模型\n query_model=\"anthropic:claude-3-5-haiku-latest\", # 查询模型\n query_limit=10,\n namespace=(\"memories\", \"{langgraph_user_id}\"),\n store=InMemoryStore(),\n)\n```\n\n### 参数说明\n\n| 参数 | 类型 | 必需 | 默认值 | 说明 |\n|------|------|------|--------|------|\n| `model` | `str \\| BaseChatModel` | 是 | - | 用于提取和综合的主模型 |\n| `schemas` | `list[type[BaseModel]]` | 否 | - | 记忆数据的 Pydantic Schema |\n| `query_model` | `str \\| BaseChatModel` | 否 | - | 用于生成搜索查询的专用模型 |\n| `query_limit` | `int` | 否 | 5 | 检索的记忆数量上限 |\n| `namespace` | `tuple[str, ...]` | 否 | `(\"memories\",)` | 记忆存储的命名空间 |\n| `store` | `BaseStore` | 否 | - | LangGraph 底层存储 |\n| `instructions` | `str` | 否 | - | 提取和更新指令 |\n| `enable_inserts` | `bool` | 否 | `True` | 允许创建新记忆 |\n| `enable_deletes` | `bool` | 否 | `True` | 允许删除旧记忆 |\n\n资料来源：[src/langmem/knowledge/extraction.py:150-200]()\n\n## Schema 定义\n\n语义记忆使用 Pydantic 模型定义数据结构。以下是典型的 Schema 定义示例：\n\n```python\nfrom pydantic import BaseModel\nfrom typing import Literal\n\nclass PreferenceMemory(BaseModel):\n \"\"\"用户偏好记忆\"\"\"\n category: str # 偏好类别\n preference: str # 具体偏好\n context: str # 上下文信息\n\nclass UserProfile(BaseModel):\n \"\"\"用户档案记忆\"\"\"\n name: str\n age: int | None = None\n recent_memories: list[str] = []\n preferences: dict | None = None\n```\n\n### Schema 配置参数\n\n| 参数 | 说明 |\n|------|------|\n| `total=False` | 所有字段默认为可选 |\n| 字段类型注解 | 定义记忆内容的结构和验证规则 |\n| 默认值 | 为可选字段提供回退值 |\n\n资料来源：[src/langmem/prompts/types.py:1-40]()\n\n## 集成方式\n\n### LangGraph 集成\n\nLangMem 与 LangGraph 的 `@entrypoint` 装饰器无缝集成：\n\n```python\nfrom langmem import create_memory_store_manager\nfrom langgraph.store.memory import InMemoryStore\nfrom langgraph.func import entrypoint\n\nstore = InMemoryStore(\n index={\n \"dims\": 1536,\n \"embed\": \"openai:text-embedding-3-small\",\n }\n)\n\nmanager = create_memory_store_manager(\n \"anthropic:claude-3-5-sonnet-latest\",\n namespace=(\"memories\", \"{langgraph_user_id}\"),\n store=store,\n)\n\n@entrypoint(store=store)\nasync def my_agent(message: str):\n response = {\"role\": \"assistant\", \"content\": \"I'll remember that\"}\n await manager.ainvoke(\n {\"messages\": [{\"role\": \"user\", \"content\": message}, response]}\n )\n return response\n```\n\n### 后台执行模式\n\n对于需要异步处理的场景，可以使用 `ReflectionExecutor`：\n\n```mermaid\ngraph LR\n A[Agent] --> B[处理消息]\n B --> C[返回响应]\n B --> D[调度后台处理]\n D --> E[ReflectionExecutor]\n E --> F[记忆提取]\n F --> G[存储更新]\n```\n\n```python\nfrom langmem import create_memory_store_manager, ReflectionExecutor\n\nreflection = ReflectionExecutor(manager, store=store)\n\n# 在消息处理后调度后台执行\nreflection.schedule_after(agent_response, after_seconds=0)\n```\n\n资料来源：[src/langmem/knowledge/extraction.py:200-250]()\n\n## 搜索和检索\n\n### 默认搜索行为\n\n默认情况下，记忆检索通过直接嵌入新消息进行相似度匹配：\n\n```python\n# 直接使用消息嵌入搜索\nresults = manager.search(config=config)\n```\n\n### LLM 优化查询搜索\n\n使用专用查询模型生成更精确的搜索查询：\n\n```python\nmanager = create_memory_store_manager(\n \"anthropic:claude-3-5-sonnet-latest\",\n query_model=\"anthropic:claude-3-5-haiku-latest\", # 更快的小模型\n query_limit=10,\n namespace=(\"memories\", \"{langgraph_user_id}\"),\n)\n\n# 使用自然语言查询\nresults = manager.search(query=\"app preferences\", config=config)\n```\n\n### 过滤和分页\n\n```python\n# 带过滤条件的搜索\nresults = await manager.asearch(\n query=\"技术偏好\",\n filter={\"category\": \"programming\"},\n limit=10,\n offset=0,\n)\n```\n\n### 搜索结果格式\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| `namespace` | `tuple[str, ...]` | 记忆所属命名空间 |\n| `key` | `str` | 记忆唯一标识符 |\n| `value` | `dict` | 记忆内容数据 |\n| `created_at` | `datetime` | 创建时间戳 |\n| `updated_at` | `datetime` | 更新时间戳 |\n| `score` | `float \\| None` | 相似度分数 |\n\n资料来源：[src/langmem/knowledge/extraction.py:250-300]()\n\n## 默认值机制\n\n当没有找到相关记忆时，可以使用默认值工厂提供回退记忆：\n\n```python\nmanager = create_memory_store_manager(\n \"anthropic:claude-3-5-sonnet-latest\",\n namespace=(\"memories\", \"{langgraph_user_id}\"),\n default=\"Use a concise and professional tone in all responses.\",\n default_factory=UserPreferencesFactory,\n)\n```\n\n### 默认值配置\n\n| 配置方式 | 说明 |\n|----------|------|\n| `default` | 静态默认字符串或 Pydantic 实例 |\n| `default_factory` | 动态生成默认值的函数 |\n\n资料来源：[src/langmem/knowledge/extraction.py:300-350]()\n\n## 操作模式\n\n### 完整模式（默认值）\n\n允许插入、更新和删除记忆：\n\n```python\nmanager = create_memory_manager(\n \"anthropic:claude-3-5-sonnet-latest\",\n schemas=[PreferenceMemory],\n enable_inserts=True,\n enable_updates=True,\n enable_deletes=True, # 完整功能\n)\n```\n\n### 仅插入模式\n\n仅创建新记忆，不修改现有记忆：\n\n```python\nmanager = create_memory_manager(\n \"anthropic:claude-3-5-sonnet-latest\",\n schemas=[PreferenceMemory],\n enable_inserts=True,\n enable_updates=False,\n enable_deletes=False, # 仅插入\n)\n```\n\n### 操作控制参数\n\n| 参数 | 允许的操作 | 典型用例 |\n|------|-----------|----------|\n| `enable_inserts=True` | 创建新记忆 | 首次学习用户偏好 |\n| `enable_updates=True` | 更新现有记忆 | 偏好变化时同步更新 |\n| `enable_deletes=True` | 删除过时记忆 | 清理矛盾或错误记忆 |\n\n## 多步骤提取和综合\n\n对于复杂对话场景，可以配置多步骤处理：\n\n```python\nconversation = [\n {\"role\": \"user\", \"content\": \"I prefer dark mode in all my apps\"},\n {\"role\": \"assistant\", \"content\": \"I'll remember that preference\"},\n]\n\n# 设置最大处理步骤数\nmax_steps = 3\nmemories = await manager.ainvoke(\n {\"messages\": conversation, \"max_steps\": max_steps}\n)\n```\n\n### 处理流程\n\n```mermaid\ngraph TD\n A[对话历史] --> B[步骤 1: 提取]\n B --> C{是否完成?}\n C -->|否| D[生成工具调用]\n D --> E[步骤 2: 执行]\n E --> B\n C -->|是| F[返回记忆结果]\n \n B --> G[保留未修改的现有记忆]\n G --> F\n```\n\n## 命名空间管理\n\n### 运行时命名空间配置\n\n命名空间支持运行时配置变量替换：\n\n```python\nnamespace=(\"memories\", \"{langgraph_user_id}\")\n\n# 配置\nconfig = {\"configurable\": {\"langgraph_user_id\": \"user123\"}}\n# 结果命名空间: (\"memories\", \"user123\")\n```\n\n### 命名空间结构\n\n| 示例 | 说明 |\n|------|------|\n| `(\"memories\",)` | 基础命名空间 |\n| `(\"memories\", \"{user_id}\")` | 用户级别隔离 |\n| `(\"memories\", \"{team_id}\", \"{user_id}\")` | 团队+用户层级 |\n\n## 最佳实践\n\n### 1. Schema 设计\n\n- 为不同类型的记忆创建独立的 Schema\n- 使用描述性的字段名称和类型注解\n- 提供合理的默认值减少空值处理\n\n### 2. 模型选择\n\n| 场景 | 推荐模型配置 |\n|------|-------------|\n| 高质量提取 | 主模型使用 Sonnet-3.5，查询使用 Haiku |\n| 成本优化 | 主模型和查询模型都使用轻量模型 |\n| 快速迭代 | 仅使用主模型，不启用查询优化 |\n\n### 3. 性能考虑\n\n- 使用后台执行处理记忆管理，避免阻塞主流程\n- 合理设置 `query_limit` 避免返回过多不相关记忆\n- 对高频访问的记忆使用短期缓存\n\n### 4. 错误处理\n\n```python\ntry:\n await manager.ainvoke({\"messages\": conversation})\nexcept ValueError as e:\n # Schema 验证失败\n logger.error(f\"记忆验证失败: {e}\")\nexcept Exception as e:\n # 存储操作失败\n logger.error(f\"存储错误: {e}\")\n```\n\n## 完整使用示例\n\n```python\nfrom langmem import create_memory_store_manager\nfrom langgraph.store.memory import InMemoryStore\nfrom langgraph.func import entrypoint\nfrom pydantic import BaseModel\n\nclass PreferenceMemory(BaseModel):\n \"\"\"用户偏好记忆\"\"\"\n category: str\n preference: str\n context: str\n\n# 初始化存储\nstore = InMemoryStore(\n index={\n \"dims\": 1536,\n \"embed\": \"openai:text-embedding-3-small\",\n }\n)\n\n# 创建管理器\nmanager = create_memory_store_manager(\n \"anthropic:claude-3-5-sonnet-latest\",\n schemas=[PreferenceMemory],\n query_model=\"anthropic:claude-3-5-haiku-latest\",\n query_limit=10,\n namespace=(\"memories\", \"{langgraph_user_id}\"),\n store=store,\n)\n\n# 定义 Agent\n@entrypoint(store=store)\nasync def my_agent(message: str):\n response = {\"role\": \"assistant\", \"content\": \"I'll remember that preference\"}\n await manager.ainvoke(\n {\"messages\": [{\"role\": \"user\", \"content\": message}, response]}\n )\n return response\n\n# 执行对话\nconfig = {\"configurable\": {\"langgraph_user_id\": \"user123\"}}\nawait my_agent.ainvoke(\n \"I prefer dark mode in all my apps\",\n config=config,\n)\n\n# 检索记忆\nprint(manager.search(query=\"app preferences\", config=config))\n```\n\n资料来源：[src/langmem/knowledge/extraction.py:50-100]()\n\n## 相关模块\n\n| 模块 | 路径 | 功能 |\n|------|------|------|\n| 知识提取 | `src/langmem/knowledge/extraction.py` | 核心记忆管理逻辑 |\n| 记忆工具 | `src/langmem/knowledge/tools.py` | LangGraph 工具集成 |\n| 提示类型 | `src/langmem/prompts/types.py` | Schema 定义类型 |\n| 短时摘要 | `src/langmem/short_term/summarization.py` | 会话级摘要管理 |\n| 提示优化 | `src/langmem/prompts/optimization.py` | 元学习和优化 |\n\n---\n\n\n\n## 情景记忆提取\n\n### 相关页面\n\n相关主题：[语义记忆管理](#page-semantic-memory), [记忆提取](#page-memory-extraction)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/langmem/knowledge/extraction.py](https://github.com/langchain-ai/langmem/blob/main/src/langmem/knowledge/extraction.py)\n- [src/langmem/knowledge/tools.py](https://github.com/langchain-ai/langmem/blob/main/src/langmem/knowledge/tools.py)\n- [src/langmem/prompts/optimization.py](https://github.com/langchain-ai/langmem/blob/main/src/langmem/prompts/optimization.py)\n- [src/langmem/prompts/types.py](https://github.com/langchain-ai/langmem/blob/main/src/langmem/prompts/types.py)\n- [src/langmem/short_term/summarization.py](https://github.com/langchain-ai/langmem/blob/main/src/langmem/short_term/summarization.py)\n- [examples/standalone_examples/README.md](https://github.com/langchain-ai/langmem/blob/main/examples/standalone_examples/README.md)\n \n\n# 情景记忆提取\n\n## 概述\n\n情景记忆提取（Episodic Memory Extraction）是 LangMem 库的核心功能之一，用于从对话历史中自动识别、提取和管理结构化记忆。该功能使 AI 系统能够持续学习用户偏好、对话模式和环境信息，并在后续交互中智能调用相关记忆来提升个性化服务质量。\n\nLangMem 的情景记忆提取系统基于以下核心设计理念：\n\n- **结构化存储**：记忆以预定义的 Pydantic Schema 形式存储，确保类型安全和数据一致性\n- **增量更新**：支持记忆的创建、更新和删除操作，适应用户偏好的动态变化\n- **智能检索**：提供基于向量相似度和 LLM 查询的混合检索能力\n- **异步处理**：支持后台执行记忆处理，不阻塞主对话流程\n\n资料来源：[src/langmem/knowledge/extraction.py:1-50]()\n\n## 核心组件\n\n### MemoryManager\n\n`MemoryManager` 是情景记忆提取的主控制器，负责协调整个记忆生命周期。\n\n```python\nfrom langmem import create_memory_manager\n\nmanager = create_memory_manager(\n \"anthropic:claude-3-5-sonnet-latest\",\n schemas=[PreferenceMemory],\n)\n```\n\n**关键参数说明**：\n\n| 参数 | 类型 | 说明 |\n|------|------|------|\n| `model` | `str \\| BaseChatModel` | 用于分析和提取记忆的主模型 |\n| `schemas` | `list[type[BaseModel]]` | 记忆数据的 Pydantic Schema 定义 |\n| `instructions` | `str \\| None` | 自定义提取指令 |\n| `enable_inserts` | `bool` | 启用创建新记忆（默认：True） |\n| `enable_updates` | `bool` | 启用更新现有记忆（默认：True） |\n| `enable_deletes` | `bool` | 启用删除过时记忆（默认：True） |\n| `max_steps` | `int` | 最大提取和综合步数（默认：3） |\n\n资料来源：[src/langmem/knowledge/extraction.py:100-150]()\n\n### MemoryStoreManager\n\n`MemoryStoreManager` 扩展了基础记忆管理能力，集成了 LangGraph 的持久化存储层。\n\n```python\nfrom langmem import create_memory_store_manager\nfrom langgraph.store.memory import InMemoryStore\n\nstore = InMemoryStore(\n index={\n \"dims\": 1536,\n \"embed\": \"openai:text-embedding-3-small\",\n }\n)\nmanager = create_memory_store_manager(\n \"anthropic:claude-3-5-sonnet-latest\",\n query_model=\"anthropic:claude-3-5-haiku-latest\",\n query_limit=10,\n namespace=(\"memories\", \"{langgraph_user_id}\"),\n store=store,\n)\n```\n\n资料来源：[src/langmem/knowledge/extraction.py:200-280]()\n\n## 工作流程\n\n### 基础提取流程\n\n```mermaid\nsequenceDiagram\n participant Client\n participant Manager\n participant LLM\n participant Store\n\n Client->>Manager: messages + existing memories\n Manager->>LLM: analyze conversation\n LLM-->>Manager: extraction decisions\n Manager->>Store: apply memory changes\n Store-->>Manager: updated memories\n Manager-->>Client: memory updates\n```\n\n### 带 LLM 查询的检索流程\n\n当需要更精确的记忆检索时，系统会先生成优化查询：\n\n```mermaid\nsequenceDiagram\n participant Client\n participant Manager\n participant QueryLLM\n participant Store\n participant MainLLM\n\n Client->>Manager: messages\n Manager->>QueryLLM: generate search query\n QueryLLM-->>Manager: optimized query\n Manager->>Store: find memories\n Store-->>Manager: memories\n Manager->>MainLLM: analyze & extract\n MainLLM-->>Manager: memory updates\n Manager->>Store: apply changes\n Manager-->>Client: result\n```\n\n资料来源：[src/langmem/knowledge/extraction.py:50-100]()\n\n## 记忆 Schema 定义\n\n### 基本结构\n\nLangMem 使用 Pydantic BaseModel 定义记忆结构：\n\n```python\nfrom pydantic import BaseModel\n\nclass PreferenceMemory(BaseModel):\n \"\"\"用户偏好记忆\"\"\"\n preference: str\n context: str\n category: str = \"general\"\n\nclass UserProfile(BaseModel):\n \"\"\"用户档案记忆\"\"\"\n name: str\n age: int | None = None\n recent_memories: list[str] = []\n preferences: dict | None = None\n```\n\n资料来源：[src/langmem/knowledge/tools.py:1-50]()\n\n### 嵌套 Schema 示例\n\n```python\nclass Memory(BaseModel):\n \"\"\"带类型标签的统一记忆格式\"\"\"\n kind: str\n content: dict[str, Any]\n```\n\n存储后的记忆项包含以下元数据：\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| `namespace` | `tuple[str, ...]` | 记忆的命名空间路径 |\n| `key` | `str` | 记忆的唯一标识符 |\n| `value` | `dict` | 序列化的记忆内容 |\n| `created_at` | `datetime` | 创建时间戳 |\n| `updated_at` | `datetime` | 最后更新时间戳 |\n| `score` | `float \\| None` | 相似度分数（检索时） |\n\n资料来源：[src/langmem/knowledge/tools.py:50-100]()\n\n## 使用方式\n\n### 独立使用\n\n在 LangGraph 外部独立使用记忆管理功能：\n\n```python\nfrom langmem import create_memory_manager\nfrom pydantic import BaseModel\n\nclass PreferenceMemory(BaseModel):\n preference: str\n context: str\n\nmanager = create_memory_manager(\n \"anthropic:claude-3-5-sonnet-latest\",\n schemas=[PreferenceMemory],\n)\n\nconversation = [\n {\"role\": \"user\", \"content\": \"I prefer dark mode in all my apps\"},\n {\"role\": \"assistant\", \"content\": \"I'll remember that preference\"},\n]\n\n# 提取记忆\nmemories = await manager.ainvoke({\"messages\": conversation})\nprint(memories)\n```\n\n资料来源：[examples/standalone_examples/README.md:1-50]()\n\n### 与 LangGraph 集成\n\n在 LangGraph 应用中后台执行记忆处理：\n\n```python\nfrom langmem import create_memory_store_manager, ReflectionExecutor\nfrom langgraph.prebuilt import create_react_agent\nfrom langgraph.store.memory import InMemoryStore\nfrom langgraph.func import entrypoint\n\nstore = InMemoryStore(\n index={\n \"dims\": 1536,\n \"embed\": \"openai:text-embedding-3-small\",\n }\n)\nmanager = create_memory_store_manager(\n \"anthropic:claude-3-5-sonnet-latest\",\n namespace=(\"memories\", \"{user_id}\"),\n)\nreflection = ReflectionExecutor(manager, store=store)\n\n@entrypoint(store=store)\nasync def my_agent(message: str):\n response = {\"role\": \"assistant\", \"content\": \"I'll remember that\"}\n await reflection.ainvoke(\n {\"messages\": [{\"role\": \"user\", \"content\": message}, response]}\n )\n return response\n```\n\n资料来源：[src/langmem/knowledge/extraction.py:280-350]()\n\n### 检索已存储记忆\n\n```python\n# 查看提取的记忆\nprint(manager.search(config=config))\n\n# 自然语言搜索\nresults = await manager.asearch(\n query=\"app preferences\",\n filter={\"type\": \"PreferenceMemory\"},\n limit=5,\n)\n```\n\n## 高级配置\n\n### 仅插入模式\n\n适用于只需要记录新信息、不修改现有记忆的场景：\n\n```python\nmanager = create_memory_manager(\n \"anthropic:claude-3-5-sonnet-latest\",\n schemas=[PreferenceMemory],\n enable_updates=False,\n enable_deletes=False,\n)\n```\n\n### 自定义提取步数\n\n控制 LLM 推理和综合的迭代次数：\n\n```python\n# 设置最大步数\nmax_steps = 3\nmemories = await manager.ainvoke(\n {\"messages\": conversation, \"max_steps\": max_steps}\n)\n```\n\n### 默认记忆值\n\n当没有找到记忆时返回预设默认值：\n\n```python\nmanager = create_memory_store_manager(\n \"anthropic:claude-3-5-sonnet-latest\",\n namespace=(\"memories\", \"{langgraph_user_id}\"),\n default=\"Use a concise and professional tone in all responses.\",\n)\n```\n\n资料来源：[src/langmem/knowledge/extraction.py:350-400]()\n\n## 工具函数\n\n### create_manage_memory_tool\n\n创建可注入 LangGraph Agent 的记忆管理工具：\n\n```python\nfrom langmem import create_manage_memory_tool\nfrom langgraph.prebuilt import create_react_agent\n\nmemory_tool = create_manage_memory_tool(\n namespace=(\"memories\", \"{langgraph_user_id}\"),\n schema=PreferenceMemory,\n actions_permitted=[\"create\", \"update\", \"delete\"],\n instructions=\"Update the existing user profile based on shared information.\",\n)\n\nagent = create_react_agent(\n \"anthropic:claude-3-5-sonnet-latest\",\n tools=[memory_tool],\n store=store,\n)\n```\n\n资料来源：[src/langmem/knowledge/tools.py:100-200]()\n\n### create_search_memory_tool\n\n创建专门用于记忆检索的工具：\n\n```python\nfrom langmem import create_search_memory_tool\n\nsearch_tool = create_search_memory_tool(\n namespace=(\"project_memories\", \"{langgraph_user_id}\"),\n)\n\n# 在工作流中使用\nmemories, _ = await search_tool.ainvoke(\n {\"query\": \"Python preferences\", \"limit\": 5}\n)\n```\n\n### create_memory_searcher\n\n创建独立的记忆搜索流水线：\n\n```python\nfrom langmem import create_memory_searcher\n\nsearcher = create_memory_searcher(\n \"anthropic:claude-3-5-sonnet-latest\",\n prompt=\"Search for distinct memories relevant to different aspects.\",\n namespace=(\"memories\", \"{langgraph_user_id}\"),\n)\n```\n\n资料来源：[src/langmem/knowledge/extraction.py:400-500]()\n\n## 命名空间设计\n\n### 命名空间结构\n\n记忆按照层级化的命名空间组织：\n\n```python\nnamespace = (\"memories\", \"{langgraph_user_id}\")\n# 运行时解析为：(\"memories\", \"user123\")\n```\n\n### 常见命名空间模式\n\n| 用途 | 命名空间示例 |\n|------|-------------|\n| 用户级记忆 | `(\"memories\", \"{user_id}\")` |\n| 线程级记忆 | `(\"memories\", \"{user_id}\", \"threads\", \"{thread_id}\")` |\n| 类型隔离 | `(\"memories\", \"{user_id}\", \"preferences\")` |\n| 项目级记忆 | `(\"project_memories\", \"{project_id}\")` |\n\n### 多 Schema 命名空间\n\n```python\nmemory_tool = create_manage_memory_tool(\n namespace=(\"memories\", \"{langgraph_user_id}\", \"user_profile\"),\n schema=UserProfile,\n)\n```\n\n资料来源：[src/langmem/knowledge/tools.py:200-300]()\n\n## 异步与同步 API\n\n### 异步调用\n\n```python\n# 异步提取\nupdated_memories = await manager.ainvoke(\n {\"messages\": conversation, \"existing\": memories}\n)\n\n# 异步搜索\nresults = await manager.asearch(query=\"preferences\", limit=10)\n\n# 异步存储\nawait manager.aput(\"key\", {\"content\": \"value\"})\n```\n\n### 同步调用\n\n```python\n# 同步提取\nupdated_memories = manager.invoke({\"messages\": conversation})\n\n# 同步搜索\nresults = manager.search(query=\"preferences\", limit=10)\n```\n\n## 与短时记忆的集成\n\nLangMem 同时提供短时记忆（摘要）功能，可与情景记忆协同工作：\n\n```python\nfrom langmem.short_term import SummarizationNode, RunningSummary\n\nsummarization_node = SummarizationNode(\n model=summarization_model,\n max_tokens=256,\n max_tokens_before_summary=256,\n max_summary_tokens=128,\n)\n```\n\n工作流程：\n\n```mermaid\ngraph TD\n A[对话历史] --> B[短时记忆摘要]\n B --> C[情景记忆提取]\n C --> D[结构化记忆存储]\n D --> E[后续对话检索]\n```\n\n资料来源：[src/langmem/short_term/summarization.py:1-100]()\n\n## 最佳实践\n\n### Schema 设计原则\n\n1. **原子性**：每个记忆项应包含最小独立信息单元\n2. **可演进性**：使用可选字段和默认值支持功能扩展\n3. **可检索性**：在 Schema 中包含可用于过滤的分类字段\n\n### 性能优化\n\n1. **选择合适的查询模型**：使用轻量级模型处理检索查询\n2. **设置合理的查询限制**：根据实际需求调整 `query_limit`\n3. **使用命名空间隔离**：避免大规模检索时的性能瓶颈\n\n### 错误处理\n\n```python\ntry:\n result = await manager.ainvoke({\"messages\": conversation})\nexcept Exception as e:\n logger.error(f\"Memory extraction failed: {e}\")\n # 降级策略：使用空记忆继续\n result = []\n```\n\n## 总结\n\n情景记忆提取是 LangMem 库实现持久化上下文管理的核心能力。通过结构化的 Schema 定义、灵活的存储层集成和智能的提取算法，开发者可以轻松构建具有持续学习能力的 AI 应用。该系统既支持独立使用，也与 LangGraph 框架深度集成，满足从简单脚本到复杂生产环境的各种需求。\n\n---\n\n---\n\n## Doramagic 踩坑日志\n\n项目：langchain-ai/langmem\n\n摘要：发现 11 个潜在踩坑项，其中 3 个为 high/blocking；最高优先级：安装坑 - 来源证据：GRAPH_RECURSION_LIMIT。\n\n## 1. 安装坑 · 来源证据：GRAPH_RECURSION_LIMIT\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：GRAPH_RECURSION_LIMIT\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_82b923de03f34d5a9fa8530916b40d14 | https://github.com/langchain-ai/langmem/issues/133 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 2. 安装坑 · 来源证据：Persistence?\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Persistence?\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_b9688483fa44468a96801d46825b040f | https://github.com/langchain-ai/langmem/issues/154 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 3. 安全/权限坑 · 来源证据：Enhance error message when summarization fails due to missing HumanMessage in trimmed window\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Enhance error message when summarization fails due to missing HumanMessage in trimmed window\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_15b3f9c4829745339b470171f005b3df | https://github.com/langchain-ai/langmem/issues/156 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 4. 配置坑 · 可能修改宿主 AI 配置\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。\n- 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。\n- 建议检查：列出会写入的配置文件、目录和卸载/回滚步骤。\n- 防护动作: 涉及宿主配置目录时必须给回滚路径，不能只给安装命令。\n- 证据：capability.host_targets | github_repo:920242883 | https://github.com/langchain-ai/langmem | host_targets=claude, chatgpt\n\n## 5. 能力坑 · 能力判断依赖假设\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：README/documentation is current enough for a first validation pass.\n- 对用户的影响：假设不成立时，用户拿不到承诺的能力。\n- 建议检查：将假设转成下游验证清单。\n- 防护动作: 假设必须转成验证项；没有验证结果前不能写成事实。\n- 证据：capability.assumptions | github_repo:920242883 | https://github.com/langchain-ai/langmem | README/documentation is current enough for a first validation pass.\n\n## 6. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作: 维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | github_repo:920242883 | https://github.com/langchain-ai/langmem | last_activity_observed missing\n\n## 7. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作: 下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | github_repo:920242883 | https://github.com/langchain-ai/langmem | no_demo; severity=medium\n\n## 8. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作: 评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | github_repo:920242883 | https://github.com/langchain-ai/langmem | no_demo; severity=medium\n\n## 9. 安全/权限坑 · 来源证据：Security: OWASP Agent Memory Guard for memory poisoning defense (ASI06)\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Security: OWASP Agent Memory Guard for memory poisoning defense (ASI06)\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_760d72a9519c42a8b1e31d8932383bc2 | https://github.com/langchain-ai/langmem/issues/164 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 10. 维护坑 · issue/PR 响应质量未知\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：issue_or_pr_quality=unknown。\n- 对用户的影响：用户无法判断遇到问题后是否有人维护。\n- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。\n- 防护动作: issue/PR 响应未知时，必须提示维护风险。\n- 证据：evidence.maintainer_signals | github_repo:920242883 | https://github.com/langchain-ai/langmem | issue_or_pr_quality=unknown\n\n## 11. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作: 发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | github_repo:920242883 | https://github.com/langchain-ai/langmem | release_recency=unknown\n\n\n",
"summary": "DeepWiki/Human Wiki 完整输出，末尾追加 Discovery Agent 踩坑日志。",
"title": "Human Manual / 人类版说明书"
},
"pitfall_log": {
"asset_id": "pitfall_log",
"filename": "PITFALL_LOG.md",
"markdown": "# Pitfall Log / 踩坑日志\n\n项目：langchain-ai/langmem\n\n摘要：发现 11 个潜在踩坑项，其中 3 个为 high/blocking；最高优先级：安装坑 - 来源证据：GRAPH_RECURSION_LIMIT。\n\n## 1. 安装坑 · 来源证据：GRAPH_RECURSION_LIMIT\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：GRAPH_RECURSION_LIMIT\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_82b923de03f34d5a9fa8530916b40d14 | https://github.com/langchain-ai/langmem/issues/133 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 2. 安装坑 · 来源证据：Persistence?\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Persistence?\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_b9688483fa44468a96801d46825b040f | https://github.com/langchain-ai/langmem/issues/154 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 3. 安全/权限坑 · 来源证据：Enhance error message when summarization fails due to missing HumanMessage in trimmed window\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Enhance error message when summarization fails due to missing HumanMessage in trimmed window\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_15b3f9c4829745339b470171f005b3df | https://github.com/langchain-ai/langmem/issues/156 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 4. 配置坑 · 可能修改宿主 AI 配置\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。\n- 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。\n- 建议检查：列出会写入的配置文件、目录和卸载/回滚步骤。\n- 防护动作: 涉及宿主配置目录时必须给回滚路径，不能只给安装命令。\n- 证据：capability.host_targets | github_repo:920242883 | https://github.com/langchain-ai/langmem | host_targets=claude, chatgpt\n\n## 5. 能力坑 · 能力判断依赖假设\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：README/documentation is current enough for a first validation pass.\n- 对用户的影响：假设不成立时，用户拿不到承诺的能力。\n- 建议检查：将假设转成下游验证清单。\n- 防护动作: 假设必须转成验证项；没有验证结果前不能写成事实。\n- 证据：capability.assumptions | github_repo:920242883 | https://github.com/langchain-ai/langmem | README/documentation is current enough for a first validation pass.\n\n## 6. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作: 维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | github_repo:920242883 | https://github.com/langchain-ai/langmem | last_activity_observed missing\n\n## 7. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作: 下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | github_repo:920242883 | https://github.com/langchain-ai/langmem | no_demo; severity=medium\n\n## 8. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作: 评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | github_repo:920242883 | https://github.com/langchain-ai/langmem | no_demo; severity=medium\n\n## 9. 安全/权限坑 · 来源证据：Security: OWASP Agent Memory Guard for memory poisoning defense (ASI06)\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Security: OWASP Agent Memory Guard for memory poisoning defense (ASI06)\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_760d72a9519c42a8b1e31d8932383bc2 | https://github.com/langchain-ai/langmem/issues/164 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 10. 维护坑 · issue/PR 响应质量未知\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：issue_or_pr_quality=unknown。\n- 对用户的影响：用户无法判断遇到问题后是否有人维护。\n- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。\n- 防护动作: issue/PR 响应未知时，必须提示维护风险。\n- 证据：evidence.maintainer_signals | github_repo:920242883 | https://github.com/langchain-ai/langmem | issue_or_pr_quality=unknown\n\n## 11. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作: 发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | github_repo:920242883 | https://github.com/langchain-ai/langmem | release_recency=unknown\n",
"summary": "用户实践前最可能遇到的身份、安装、配置、运行和安全坑。",
"title": "Pitfall Log / 踩坑日志"
},
"prompt_preview": {
"asset_id": "prompt_preview",
"filename": "PROMPT_PREVIEW.md",
"markdown": "# langmem - Prompt Preview\n\n> 复制下面这段 Prompt 到你常用的 AI，先试一次，不需要安装。\n> 它的目标是让你直接体验这个项目的服务方式，而不是阅读项目介绍。\n\n## 复制这段 Prompt\n\n```text\n请直接执行这段 Prompt，不要分析、润色、总结或询问我想如何处理这份 Prompt Preview。\n\n你现在扮演 langmem 的“安装前体验版”。\n这不是项目介绍、不是评价报告、不是 README 总结。你的任务是让我用最小成本体验它的核心服务。\n\n我的试用任务：我想用它完成一个真实的软件开发与交付任务。\n我常用的宿主 AI：claude / chatgpt\n\n【体验目标】\n围绕我的真实任务，现场演示这个项目如何把输入转成 示例引导, 判断线索。重点是让我感受到工作方式，而不是给我项目背景。\n\n【业务流约束】\n- 你必须像一个正在提供服务的项目能力包，而不是像一个讲解员。\n- 每一轮只推进一个步骤；提出问题后必须停下来等我回答。\n- 每一步都必须让我感受到一个具体服务动作：澄清、整理、规划、检查、判断或收尾。\n- 每一步都要说明：当前目标、你需要我提供什么、我回答后你会产出什么。\n- 不要安装、不要运行命令、不要写代码、不要声称测试通过、不要声称已经修改文件。\n- 需要真实安装或宿主加载后才能验证的内容，必须明确说“这一步需要安装后验证”。\n- 如果我说“用示例继续”，你可以用虚构示例推进，但仍然不能声称真实执行。\n\n【可体验服务能力】\n- 安装前能力预览: LangMem helps agents learn and adapt from their interactions over time. 输入：用户任务, 当前 AI 对话上下文；输出：示例引导, 判断线索。\n\n【必须安装后才可验证的能力】\n- 命令行启动或安装流程: 项目文档中存在可执行命令，真实使用需要在本地或宿主环境中运行这些命令。 输入：终端环境, 包管理器, 项目依赖；输出：安装结果, 列表/更新/运行结果。\n\n【核心服务流】\n请严格按这个顺序带我体验。不要一次性输出完整流程：\n1. page-overview：LangMem 概述。围绕“LangMem 概述”模拟一次用户任务，不展示安装或运行结果。\n2. page-installation：安装与配置。围绕“安装与配置”模拟一次用户任务，不展示安装或运行结果。\n3. page-hot-path-quickstart：热路径快速开始。围绕“热路径快速开始”模拟一次用户任务，不展示安装或运行结果。\n4. page-system-architecture：系统架构。围绕“系统架构”模拟一次用户任务，不展示安装或运行结果。\n5. page-memory-tools：记忆工具。围绕“记忆工具”模拟一次用户任务，不展示安装或运行结果。\n\n【核心能力体验剧本】\n每一步都必须按“输入 -> 服务动作 -> 中间产物”执行。不要只说流程名：\n1. page-overview\n输入：用户提供的“LangMem 概述”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n2. page-installation\n输入：用户提供的“安装与配置”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n3. page-hot-path-quickstart\n输入：用户提供的“热路径快速开始”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n4. page-system-architecture\n输入：用户提供的“系统架构”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n5. page-memory-tools\n输入：用户提供的“记忆工具”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n【项目服务规则】\n这些规则决定你如何服务用户。不要解释规则本身，而要在每一步执行时遵守：\n- 先确认用户任务、输入材料和成功标准，再模拟项目能力。\n- 每一步都必须形成可检查的小产物，并等待用户确认后再继续。\n- 凡是需要安装、调用工具或访问外部服务的能力，都必须标记为安装后验证。\n\n【每一步的服务约束】\n- Step 1 / page-overview：Step 1 必须围绕“LangMem 概述”形成一个小中间产物，并等待用户确认。\n- Step 2 / page-installation：Step 2 必须围绕“安装与配置”形成一个小中间产物，并等待用户确认。\n- Step 3 / page-hot-path-quickstart：Step 3 必须围绕“热路径快速开始”形成一个小中间产物，并等待用户确认。\n- Step 4 / page-system-architecture：Step 4 必须围绕“系统架构”形成一个小中间产物，并等待用户确认。\n- Step 5 / page-memory-tools：Step 5 必须围绕“记忆工具”形成一个小中间产物，并等待用户确认。\n\n【边界与风险】\n- 不要声称已经安装、运行、调用 API、读写本地文件或完成真实任务。\n- 安装前预览只能展示工作方式，不能证明兼容性、性能或输出质量。\n- 涉及安装、插件加载、工具调用或外部服务的能力必须安装后验证。\n\n【可追溯依据】\n这些路径只用于你内部校验或在我追问“依据是什么”时简要引用。不要在首次回复主动展开：\n- https://github.com/langchain-ai/langmem\n- https://github.com/langchain-ai/langmem#readme\n- README.md\n- src/langmem/__init__.py\n- pyproject.toml\n- docs/docs/hot_path_quickstart.md\n- src/langmem/knowledge/tools.py\n- src/langmem/knowledge/__init__.py\n- src/langmem/prompts/__init__.py\n- langgraph.json\n- docs/docs/guides/memory_tools.md\n\n【首次问题规则】\n- 首次三问必须先确认用户目标、成功标准和边界，不要提前进入工具、安装或实现细节。\n- 如果后续需要技术条件、文件路径或运行环境，必须等用户确认目标后再追问。\n\n首次回复必须只输出下面 4 个部分：\n1. 体验开始：用 1 句话说明你将带我体验 langmem 的核心服务。\n2. 当前步骤：明确进入 Step 1，并说明这一步要解决什么。\n3. 你会如何服务我：说明你会先改变我完成任务的哪个动作。\n4. 只问我 3 个问题，然后停下等待回答。\n\n首次回复禁止输出：后续完整流程、证据清单、安装命令、项目评价、营销文案、已经安装或运行的说法。\n\nStep 1 / brainstorming 的二轮协议：\n- 我回答首次三问后，你仍然停留在 Step 1 / brainstorming，不要进入 Step 2。\n- 第二次回复必须产出 6 个部分：澄清后的任务定义、成功标准、边界条件、\n 2-3 个可选方案、每个方案的权衡、推荐方案。\n- 第二次回复最后必须问我是否确认推荐方案；只有我明确确认后，才能进入下一步。\n- 第二次回复禁止输出 git worktree、代码计划、测试文件、命令或真实执行结果。\n\n后续对话规则：\n- 我回答后，你先完成当前步骤的中间产物并等待确认；只有我确认后，才能进入下一步。\n- 每一步都要生成一个小的中间产物，例如澄清后的目标、计划草案、测试意图、验证清单或继续/停止判断。\n- 所有演示都写成“我会建议/我会引导/这一步会形成”，不要写成已经真实执行。\n- 不要声称已经测试通过、文件已修改、命令已运行或结果已产生。\n- 如果某个能力必须安装后验证，请直接说“这一步需要安装后验证”。\n- 如果证据不足，请明确说“证据不足”，不要补事实。\n```\n",
"summary": "不安装项目也能感受能力节奏的安全试用 Prompt。",
"title": "Prompt Preview / 安装前试用 Prompt"
},
"quick_start": {
"asset_id": "quick_start",
"filename": "QUICK_START.md",
"markdown": "# Quick Start / 官方入口\n\n项目：langchain-ai/langmem\n\n## 官方安装入口\n\n### Python / pip · 官方安装入口\n\n```bash\npip install -U langmem\n```\n\n来源：https://github.com/langchain-ai/langmem#readme\n\n## 来源\n\n- repo: https://github.com/langchain-ai/langmem\n- docs: https://github.com/langchain-ai/langmem#readme\n",
"summary": "从项目官方 README 或安装文档提取的开工入口。",
"title": "Quick Start / 官方入口"
}
},
"validation_id": "dval_769f6bd591314079a9e33348a317fb5d"
}