{
"canonical_name": "Evilander/Audrey",
"compilation_id": "pack_d89adfd9a47349ac9921a3d84a90e5aa",
"created_at": "2026-05-16T04:52:55.151256+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 `npx audrey` 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": "npx audrey",
"sandbox_container_image": "node:22-slim",
"sandbox_execution_backend": "docker",
"sandbox_planner_decision": "deterministic_isolated_install",
"sandbox_validation_id": "sbx_d3ff37d0ac634526b46b6084a3996db8"
},
"feedback_event_type": "project_pack_compilation_feedback",
"learning_candidate_reasons": [],
"template_gaps": []
},
"identity": {
"canonical_id": "project_f0b2823ca69f8fc9b5862c0578f5ec5d",
"canonical_name": "Evilander/Audrey",
"homepage_url": null,
"license": "unknown",
"repo_url": "https://github.com/Evilander/Audrey",
"slug": "audrey",
"source_packet_id": "phit_e1185f748c1f4ccdaf8ccc20d6f3429d",
"source_validation_id": "dval_bcf396c2d9534088a3eb88304c9c4a26"
},
"merchandising": {
"best_for": "需要软件开发与交付能力，并使用 mcp_host的用户",
"github_forks": 5,
"github_stars": 23,
"one_liner_en": "Persistent memory and continuity engine for Claude Code and AI agents.",
"one_liner_zh": "Persistent memory and continuity engine for Claude Code and AI agents.",
"primary_category": {
"category_id": "software-development",
"confidence": "medium",
"name_en": "Software Development",
"name_zh": "软件开发与交付",
"reason": "matched_keywords:code, git"
},
"target_user": "使用 mcp_host, claude, claude_code 等宿主 AI 的用户",
"title_en": "Audrey",
"title_zh": "Audrey 能力包",
"visible_tags": [
{
"label_en": "Browser Agents",
"label_zh": "浏览器 Agent",
"source": "repo_evidence_project_characteristics",
"tag_id": "product_domain-browser-agents",
"type": "product_domain"
},
{
"label_en": "Web Task Automation",
"label_zh": "网页任务自动化",
"source": "repo_evidence_project_characteristics",
"tag_id": "user_job-web-task-automation",
"type": "user_job"
},
{
"label_en": "Browser Automation",
"label_zh": "浏览器自动化",
"source": "repo_evidence_project_characteristics",
"tag_id": "core_capability-browser-automation",
"type": "core_capability"
},
{
"label_en": "Page Observation and Action Planning",
"label_zh": "页面观察与动作规划",
"source": "repo_evidence_project_characteristics",
"tag_id": "workflow_pattern-page-observation-and-action-planning",
"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_e1185f748c1f4ccdaf8ccc20d6f3429d",
"page_model": {
"artifacts": {
"artifact_slug": "audrey",
"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": "npx audrey",
"label": "Node.js / npx · 官方安装入口",
"source": "https://github.com/Evilander/Audrey#readme",
"verified": true
}
],
"display_tags": [
"浏览器 Agent",
"网页任务自动化",
"浏览器自动化",
"页面观察与动作规划",
"评测体系"
],
"eyebrow": "软件开发与交付",
"glance": [
{
"body": "判断自己是不是目标用户。",
"label": "最适合谁",
"value": "需要软件开发与交付能力，并使用 mcp_host的用户"
},
{
"body": "先理解能力边界，再决定是否继续。",
"label": "核心价值",
"value": "Persistent memory and continuity engine for Claude Code and AI agents."
},
{
"body": "未完成验证前保持审慎。",
"label": "继续前",
"value": "publish to Doramagic.ai project surfaces"
}
],
"guardrail_source": "Boundary & Risk Card",
"guardrails": [
{
"body": "Prompt Preview 只展示流程，不证明项目已安装或运行。",
"label": "Check 1",
"value": "不要把试用当真实运行"
},
{
"body": "mcp_host, claude, claude_code",
"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 社区证据显示该项目存在一个安装相关的待验证问题：Audrey 1.0.1 — honest GuardBench gate, Guard time decay, structured validate errors",
"category": "安装坑",
"evidence": [
"community_evidence:github | cevd_135b992964ae468aa28f88ee639816d1 | https://github.com/Evilander/Audrey/releases/tag/v1.0.1 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：Audrey 1.0.1 — honest GuardBench gate, Guard time decay, structured validate errors",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Audrey Guard 0.23.0",
"category": "安装坑",
"evidence": [
"community_evidence:github | cevd_9c913c644e2c4c099ea01523623f080e | https://github.com/Evilander/Audrey/releases/tag/v0.23.0 | 来源讨论提到 python 相关条件，需在安装/试用前复核。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：Audrey Guard 0.23.0",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v0.16.0",
"category": "安装坑",
"evidence": [
"community_evidence:github | cevd_a7c5c62d4f034e50ba2e9c36e0798882 | https://github.com/Evilander/Audrey/releases/tag/v0.16.0 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：v0.16.0",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v0.16.1 — Windows MCP fix",
"category": "安装坑",
"evidence": [
"community_evidence:github | cevd_c0141ccf0a3245ec8c8ba112af7948e0 | https://github.com/Evilander/Audrey/releases/tag/v0.16.1 | 来源讨论提到 windows 相关条件，需在安装/试用前复核。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：v0.16.1 — Windows MCP fix",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v0.17.0",
"category": "安装坑",
"evidence": [
"community_evidence:github | cevd_9617863b3f954035926b8670b5bbea29 | https://github.com/Evilander/Audrey/releases/tag/v0.17.0 | 来源讨论提到 python 相关条件，需在安装/试用前复核。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：v0.17.0",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。",
"category": "配置坑",
"evidence": [
"capability.host_targets | github_repo:1161444210 | https://github.com/Evilander/Audrey | host_targets=mcp_host, claude, claude_code"
],
"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:1161444210 | https://github.com/Evilander/Audrey | 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:1161444210 | https://github.com/Evilander/Audrey | 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:1161444210 | https://github.com/Evilander/Audrey | no_demo; severity=medium"
],
"severity": "medium",
"suggested_check": "进入安全/权限治理复核队列。",
"title": "下游验证发现风险项",
"user_impact": "下游已经要求复核，不能在页面中弱化。"
},
{
"body": "no_demo",
"category": "安全/权限坑",
"evidence": [
"risks.scoring_risks | github_repo:1161444210 | https://github.com/Evilander/Audrey | no_demo; severity=medium"
],
"severity": "medium",
"suggested_check": "把风险写入边界卡，并确认是否需要人工复核。",
"title": "存在评分风险",
"user_impact": "风险会影响是否适合普通用户安装。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Audrey 1.0.0",
"category": "安全/权限坑",
"evidence": [
"community_evidence:github | cevd_d30d964956da40a2b5e26dc7404861f8 | https://github.com/Evilander/Audrey/releases/tag/v1.0.0 | 来源讨论提到 python 相关条件，需在安装/试用前复核。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：Audrey 1.0.0",
"user_impact": "可能影响授权、密钥配置或安全边界。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v0.22.2 — correctness pass + legitimate benchmarking",
"category": "安全/权限坑",
"evidence": [
"community_evidence:github | cevd_f9c004c97d31437ebdc3699d6f1ba2f4 | https://github.com/Evilander/Audrey/releases/tag/v0.22.2 | 来源讨论提到 python 相关条件，需在安装/试用前复核。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：v0.22.2 — correctness pass + legitimate benchmarking",
"user_impact": "可能影响授权、密钥配置或安全边界。"
},
{
"body": "issue_or_pr_quality=unknown。",
"category": "维护坑",
"evidence": [
"evidence.maintainer_signals | github_repo:1161444210 | https://github.com/Evilander/Audrey | 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:1161444210 | https://github.com/Evilander/Audrey | release_recency=unknown"
],
"severity": "low",
"suggested_check": "确认最近 release/tag 和 README 安装命令是否一致。",
"title": "发布节奏不明确",
"user_impact": "安装命令和文档可能落后于代码，用户踩坑概率升高。"
}
],
"source": "ProjectPitfallLog + ProjectHitPacket + validation + community signals",
"summary": "发现 14 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：安装坑 - 来源证据：Audrey 1.0.1 — honest GuardBench gate, Guard time decay, structured validate errors。",
"title": "踩坑日志"
},
"snapshot": {
"contributors": 4,
"forks": 5,
"license": "unknown",
"note": "站点快照，非实时质量证明；用于开工前背景判断。",
"stars": 23
},
"source_url": "https://github.com/Evilander/Audrey",
"steps": [
{
"body": "不安装项目，先体验能力节奏。",
"code": "preview",
"title": "先试 Prompt"
},
{
"body": "理解输入、输出、失败模式和边界。",
"code": "manual",
"title": "读说明书"
},
{
"body": "把上下文交给宿主 AI 继续工作。",
"code": "context",
"title": "带给 AI"
},
{
"body": "进入主力环境前先完成安装入口与风险边界验证。",
"code": "verify",
"title": "沙箱验证"
}
],
"subtitle": "Persistent memory and continuity engine for Claude Code and AI agents.",
"title": "Audrey 能力包",
"trial_prompt": "# Audrey - Prompt Preview\n\n> 复制下面这段 Prompt 到你常用的 AI，先试一次，不需要安装。\n> 它的目标是让你直接体验这个项目的服务方式，而不是阅读项目介绍。\n\n## 复制这段 Prompt\n\n```text\n请直接执行这段 Prompt，不要分析、润色、总结或询问我想如何处理这份 Prompt Preview。\n\n你现在扮演 Audrey 的“安装前体验版”。\n这不是项目介绍、不是评价报告、不是 README 总结。你的任务是让我用最小成本体验它的核心服务。\n\n我的试用任务：我想用它完成一个真实的软件开发与交付任务。\n我常用的宿主 AI：MCP Client / claude / Claude Code\n\n【体验目标】\n围绕我的真实任务，现场演示这个项目如何把输入转成 示例引导, 判断线索。重点是让我感受到工作方式，而不是给我项目背景。\n\n【业务流约束】\n- 你必须像一个正在提供服务的项目能力包，而不是像一个讲解员。\n- 每一轮只推进一个步骤；提出问题后必须停下来等我回答。\n- 每一步都必须让我感受到一个具体服务动作：澄清、整理、规划、检查、判断或收尾。\n- 每一步都要说明：当前目标、你需要我提供什么、我回答后你会产出什么。\n- 不要安装、不要运行命令、不要写代码、不要声称测试通过、不要声称已经修改文件。\n- 需要真实安装或宿主加载后才能验证的内容，必须明确说“这一步需要安装后验证”。\n- 如果我说“用示例继续”，你可以用虚构示例推进，但仍然不能声称真实执行。\n\n【可体验服务能力】\n- 安装前能力预览: Persistent memory and continuity engine for Claude Code and AI agents. 输入：用户任务, 当前 AI 对话上下文；输出：示例引导, 判断线索。\n\n【必须安装后才可验证的能力】\n- 命令行启动或安装流程: 项目文档中存在可执行命令，真实使用需要在本地或宿主环境中运行这些命令。 输入：终端环境, 包管理器, 项目依赖；输出：安装结果, 列表/更新/运行结果。\n\n【核心服务流】\n请严格按这个顺序带我体验。不要一次性输出完整流程：\n1. page-overview：项目概述。围绕“项目概述”模拟一次用户任务，不展示安装或运行结果。\n2. page-quick-start：快速开始。围绕“快速开始”模拟一次用户任务，不展示安装或运行结果。\n3. page-system-architecture：系统架构。围绕“系统架构”模拟一次用户任务，不展示安装或运行结果。\n4. page-memory-model：记忆模型。围绕“记忆模型”模拟一次用户任务，不展示安装或运行结果。\n5. page-audrey-guard：Audrey Guard 安全循环。围绕“Audrey Guard 安全循环”模拟一次用户任务，不展示安装或运行结果。\n\n【核心能力体验剧本】\n每一步都必须按“输入 -> 服务动作 -> 中间产物”执行。不要只说流程名：\n1. page-overview\n输入：用户提供的“项目概述”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n2. page-quick-start\n输入：用户提供的“快速开始”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n3. page-system-architecture\n输入：用户提供的“系统架构”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n4. page-memory-model\n输入：用户提供的“记忆模型”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n5. page-audrey-guard\n输入：用户提供的“Audrey Guard 安全循环”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n【项目服务规则】\n这些规则决定你如何服务用户。不要解释规则本身，而要在每一步执行时遵守：\n- 先确认用户任务、输入材料和成功标准，再模拟项目能力。\n- 每一步都必须形成可检查的小产物，并等待用户确认后再继续。\n- 凡是需要安装、调用工具或访问外部服务的能力，都必须标记为安装后验证。\n\n【每一步的服务约束】\n- Step 1 / page-overview：Step 1 必须围绕“项目概述”形成一个小中间产物，并等待用户确认。\n- Step 2 / page-quick-start：Step 2 必须围绕“快速开始”形成一个小中间产物，并等待用户确认。\n- Step 3 / page-system-architecture：Step 3 必须围绕“系统架构”形成一个小中间产物，并等待用户确认。\n- Step 4 / page-memory-model：Step 4 必须围绕“记忆模型”形成一个小中间产物，并等待用户确认。\n- Step 5 / page-audrey-guard：Step 5 必须围绕“Audrey Guard 安全循环”形成一个小中间产物，并等待用户确认。\n\n【边界与风险】\n- 不要声称已经安装、运行、调用 API、读写本地文件或完成真实任务。\n- 安装前预览只能展示工作方式，不能证明兼容性、性能或输出质量。\n- 涉及安装、插件加载、工具调用或外部服务的能力必须安装后验证。\n\n【可追溯依据】\n这些路径只用于你内部校验或在我追问“依据是什么”时简要引用。不要在首次回复主动展开：\n- https://github.com/Evilander/Audrey\n- https://github.com/Evilander/Audrey#readme\n- README.md\n- package.json\n- src/audrey.ts\n- src/controller.ts\n- src/db.ts\n- mcp-server/index.ts\n- src/server.ts\n- src/encode.ts\n- src/recall.ts\n- src/consolidate.ts\n\n【首次问题规则】\n- 首次三问必须先确认用户目标、成功标准和边界，不要提前进入工具、安装或实现细节。\n- 如果后续需要技术条件、文件路径或运行环境，必须等用户确认目标后再追问。\n\n首次回复必须只输出下面 4 个部分：\n1. 体验开始：用 1 句话说明你将带我体验 Audrey 的核心服务。\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_release: Audrey 1.0.1 — honest GuardBench gate, Guard time decay, structured vali（https://github.com/Evilander/Audrey/releases/tag/v1.0.1）；github/github_release: Audrey 1.0.0（https://github.com/Evilander/Audrey/releases/tag/v1.0.0）；github/github_release: Audrey Guard 0.23.0（https://github.com/Evilander/Audrey/releases/tag/v0.23.0）；github/github_release: v0.22.2 — correctness pass + legitimate benchmarking（https://github.com/Evilander/Audrey/releases/tag/v0.22.2）；github/github_release: v0.17.0（https://github.com/Evilander/Audrey/releases/tag/v0.17.0）；github/github_release: v0.16.1 — Windows MCP fix（https://github.com/Evilander/Audrey/releases/tag/v0.16.1）；github/github_release: v0.16.0（https://github.com/Evilander/Audrey/releases/tag/v0.16.0）。这些是项目级外部声音，不作为单独质量证明。",
"items": [
{
"kind": "github_release",
"source": "github",
"title": "Audrey 1.0.1 — honest GuardBench gate, Guard time decay, structured vali",
"url": "https://github.com/Evilander/Audrey/releases/tag/v1.0.1"
},
{
"kind": "github_release",
"source": "github",
"title": "Audrey 1.0.0",
"url": "https://github.com/Evilander/Audrey/releases/tag/v1.0.0"
},
{
"kind": "github_release",
"source": "github",
"title": "Audrey Guard 0.23.0",
"url": "https://github.com/Evilander/Audrey/releases/tag/v0.23.0"
},
{
"kind": "github_release",
"source": "github",
"title": "v0.22.2 — correctness pass + legitimate benchmarking",
"url": "https://github.com/Evilander/Audrey/releases/tag/v0.22.2"
},
{
"kind": "github_release",
"source": "github",
"title": "v0.17.0",
"url": "https://github.com/Evilander/Audrey/releases/tag/v0.17.0"
},
{
"kind": "github_release",
"source": "github",
"title": "v0.16.1 — Windows MCP fix",
"url": "https://github.com/Evilander/Audrey/releases/tag/v0.16.1"
},
{
"kind": "github_release",
"source": "github",
"title": "v0.16.0",
"url": "https://github.com/Evilander/Audrey/releases/tag/v0.16.0"
}
],
"status": "已收录 7 条来源",
"title": "社区讨论"
}
]
},
"homepage_card": {
"category": "软件开发与交付",
"desc": "Persistent memory and continuity engine for Claude Code and AI agents.",
"effort": "安装已验证",
"forks": 5,
"icon": "code",
"name": "Audrey 能力包",
"risk": "可发布",
"slug": "audrey",
"stars": 23,
"tags": [
"浏览器 Agent",
"网页任务自动化",
"浏览器自动化",
"页面观察与动作规划",
"评测体系"
],
"thumb": "gray",
"type": "MCP 配置"
},
"manual": {
"markdown": "# https://github.com/Evilander/Audrey 项目说明书\n\n生成时间：2026-05-16 03:41:21 UTC\n\n## 目录\n\n- [项目概述](#page-overview)\n- [快速开始](#page-quick-start)\n- [系统架构](#page-system-architecture)\n- [记忆模型](#page-memory-model)\n- [Audrey Guard 安全循环](#page-audrey-guard)\n- [数据存储](#page-data-storage)\n- [MCP集成](#page-mcp-integration)\n- [REST API](#page-rest-api)\n- [CLI工具](#page-cli-tools)\n- [JavaScript SDK](#page-javascript-sdk)\n\n\n\n## 项目概述\n\n### 相关页面\n\n相关主题：[系统架构](#page-system-architecture), [快速开始](#page-quick-start)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/Evilander/Audrey/blob/main/README.md)\n- [CHANGELOG.md](https://github.com/Evilander/Audrey/blob/main/CHANGELOG.md)\n- [python/README.md](https://github.com/Evilander/Audrey/blob/main/python/README.md)\n- [src/routes.ts](https://github.com/Evilander/Audrey/blob/main/src/routes.ts)\n- [src/capsule.ts](https://github.com/Evilander/Audrey/blob/main/src/capsule.ts)\n- [src/rules-compiler.ts](https://github.com/Evilander/Audrey/blob/main/src/rules-compiler.ts)\n- [mcp-server/index.ts](https://github.com/Evilander/Audrey/blob/main/mcp-server/index.ts)\n \n\n# 项目概述\n\nAudrey 是一个为 AI 代理（AI Agents）设计的本地优先（local-first）记忆防火墙项目。它为 Codex、Claude Code、Claude Desktop、Cursor、Windsurf、VS Code、JetBrains、Ollama 后端代理以及自定义代理服务提供了一层持久的记忆层，使这些代理能够在执行工具操作前检查记忆内容。\n\n## 核心定位\n\n### 问题背景\n\nAI 代理在长时间运行和跨会话工作时面临以下挑战：\n\n- **记忆缺失**：代理会忘记昨天犯下的具体错误\n- **重复错误**：代理会重复执行之前失败过的命令\n- **规则丢失**：项目特定的规则在不同会话间丢失\n- **矛盾忽略**：代理忽视上下文中的矛盾信息\n- **冷启动**：每次新会话都像从零开始\n\n### 解决方案\n\nAudrey Guard 是项目的核心循环机制，其工作流程如下：\n\n1. **记录**（Record）：记录代理的操作和结果\n2. **记忆**（Remember）：记住重要的内容\n3. **检查**（Check）：在行动前进行检查\n4. **决策**（Decide）：返回 `allow`（允许）、`warn`（警告）或 `block`（阻止）决策，并附带证据\n5. **验证**（Validate）：验证记忆是否真正帮助了代理\n\n资料来源：[README.md:1-25]()\n\n```mermaid\ngraph TD\n A[代理执行工具] --> B{Audrey Guard 检查}\n B -->|允许| C[执行工具]\n B -->|警告| D[返回警告+证据]\n B -->|阻止| E[阻止执行]\n C --> F[记录结果到记忆]\n D --> F\n F --> G{验证成功?}\n G -->|是| H[强化记忆+置信度↑]\n G -->|否| I[弱化记忆+衰减]\n```\n\n## 功能架构\n\n### 多层客户端支持\n\n| 客户端类型 | 状态 | 说明 |\n|-----------|------|------|\n| MCP stdio server | ✅ 稳定 | 提供 20 个工具，以及 status/recent/principles 资源和 briefing/recall/reflection 提示 |\n| CLI | ✅ 稳定 | 支持 doctor、demo、guard、install、mcp-config、hook-config、status、dream、reembed、observe-tool、promote、impact 等命令 |\n| REST API | ✅ 稳定 | 基于 Hono 框架构建，提供 `/health` 和 `/v1/*` 路由 |\n| JavaScript SDK | ✅ 稳定 | 支持直接从 `audrey` 包进行 TypeScript/Node 导入 |\n| Python client | ✅ 稳定 | 通过 `pip install audrey-memory` 安装，调用 REST sidecar |\n\n资料来源：[README.md:88-95]()\n\n### 存储架构\n\nAudrey 采用本地存储方案，无需托管数据库：\n\n- **SQLite**：主数据库，使用 WAL 模式\n- **sqlite-vec**：向量检索扩展\n\n```mermaid\ngraph LR\n A[代理应用] -->|REST API| B[Hono Server]\n A -->|MCP| B\n B --> C[SQLite + WAL]\n B --> D[sqlite-vec]\n```\n\n**重要约束**：SQLite 使用 WAL 模式但无咨询锁，两个进程共享同一目录会导致写竞争。多代理场景下，每个租户、代理身份或并发主机必须设置独立的 `AUDREY_DATA_DIR`。\n\n资料来源：[README.md:107-109]()\n\n## 记忆模型\n\nAudrey 内置了针对代理场景优化的多维度记忆系统：\n\n### 记忆类型\n\n| 记忆类型 | 描述 | 示例 |\n|---------|------|------|\n| 情景记忆 (Episodic) | 具体的观察、工具结果、偏好和会话事实 | \"上次 npm run deploy 因权限失败\" |\n| 语义记忆 (Semantic) | 从重复证据中提炼的概括性原则 | \"在部署前检查权限配置\" |\n| 程序记忆 (Procedural) | 记住的执行方式、规避方法、重试策略和验证流程 | \"恢复失败时使用 git revert\" |\n| 情感与显著性 (Affect & Salience) | 情感权重和重要性影响召回 | 反复失败的命令标记为高显著性 |\n\n资料来源：[README.md:111-120]()\n\n### 记忆生命周期\n\n```mermaid\ngraph TD\n A[新记忆写入] --> B{首次编码}\n B --> C[验证循环]\n C -->|收到反馈| D[置信度更新]\n C -->|重复触发| E[证据积累]\n D --> F[巩固 Consolidation]\n E --> F\n F --> G[衰减 Decay 检查]\n G -->|过期/低置信度| H[降级处理]\n G -->|活跃| I[高优先级召回]\n```\n\n### 高级特性\n\n- **干扰与衰减**（Interference & Decay）：过时、冲突或低置信度的记忆会随时间失去权威性\n- **矛盾处理**（Contradiction Handling）：对竞争的声明进行追踪而非静默覆盖\n- **工具追踪学习**（Tool-trace Learning）：从工具执行轨迹中提取学习模式\n\n资料来源：[README.md:121-124]()\n\n## REST API\n\n### 端点概览\n\n| 方法 | 端点 | 功能 |\n|------|------|------|\n| POST | `/v1/encode` | 编码记忆 |\n| POST | `/v1/recall` | 召回相关记忆 |\n| POST | `/v1/capsule` | 获取回合级记忆包 |\n| GET | `/v1/status` | 健康检查 |\n| GET | `/health` | 基础健康状态 |\n\n资料来源：[README.md:85-87]()\n\n### 请求示例\n\n```typescript\nimport Audrey from 'audrey';\n\nconst brain = new Audrey({\n base_url: \"http://127.0.0.1:7437\",\n agent: \"support-agent\"\n});\n\nbrain.encode(\n \"Stripe returns HTTP 429 above 100 req/s\",\n source: \"direct-observation\",\n tags: [\"stripe\", \"rate-limit\"]\n);\n\nconst results = brain.recall(\"stripe rate limits\", limit: 5);\nbrain.close();\n```\n\n资料来源：[python/README.md:30-45]()\n\n## 部署模式\n\n### 部署方式\n\n| 方式 | 说明 |\n|------|------|\n| npm 包 | `npm install audrey` |\n| Docker | 容器化部署 |\n| Compose | docker-compose 编排 |\n| MCP 配置生成 | 针对不同主机的 MCP 配置自动生成 |\n\n### MCP 配置\n\nAudrey 提供针对多种主机的 MCP 配置生成：\n\n```bash\nnpx audrey mcp-config codex\nnpx audrey mcp-config generic\nnpx audrey mcp-config vscode\n```\n\nClaude Code 还可以直接注册：\n\n```bash\nnpx audrey install\nclaude mcp list\n```\n\n资料来源：[README.md:96-102]()\n\n### Claude Code 钩子配置\n\n```mermaid\ngraph LR\n A[Claude Code] -->|PreToolUse| B[audrey guard --hook]\n A -->|PostToolUse| C[记录脱敏工具轨迹]\n A -->|PostToolUseFailure| C\n B --> D{决策}\n D -->|allow| E[继续执行]\n D -->|warn| F[警告+证据]\n D -->|block| G[阻止执行]\n```\n\n预览钩子配置：\n```bash\nnpx audrey hook-config claude-code\n```\n\n应用钩子配置：\n```bash\nnpx audrey hook-config claude-code --apply --scope project\nnpx audrey hook-config claude-code --apply --scope user\n```\n\n资料来源：[mcp-server/index.ts:1-50]()\n\n## 安全机制\n\n### 认证与授权\n\n| 配置项 | 默认值 | 用途 |\n|--------|--------|------|\n| `AUDREY_HOST` | `127.0.0.0.1` | REST sidecar 绑定地址 |\n| `AUDREY_API_KEY` | 未设置 | 非回环 REST 流量的 Bearer token |\n| `AUDREY_ALLOW_NO_AUTH` | `0` | 允许非回环绑定时无需 API key |\n| `AUDREY_ENABLE_ADMIN_TOOLS` | `0` | 启用导出、导入、遗忘路由/工具 |\n\n> ⚠️ 除非设置 `AUDREY_API_KEY`，否则只能绑定到 `0.0.0.0`。\n\n资料来源：[README.md:127-133]()\n\n### 安全改进（v0.22+）\n\n- HTTP `/v1/recall` 和 `/v1/capsule` 不再将调用者选项体展开到 `audrey.recall()`，防止 `includePrivate: true` 和 `confidenceConfig` 覆盖绕过私有记忆 ACL\n- `audrey serve` 默认为 `127.0.0.1` 绑定，非回环主机无 API key 拒绝启动\n- HTTP API key 比较使用 `crypto.timingSafeEqual` 防止前缀匹配时序泄露\n- `audrey promote --yes` 拒绝写入 `process.cwd()` 之外的 `.claude/rules/*.md`，防止恶意 MCP 调用者注入持久化提示\n\n资料来源：[CHANGELOG.md:1-100]()\n\n## 环境变量配置\n\n### 核心配置\n\n| 变量 | 默认值 | 用途 |\n|------|--------|------|\n| `AUDREY_DATA_DIR` | `.audrey-data/` | 数据存储目录 |\n| `AUDREY_EMBEDDING_PROVIDER` | 自动检测 | 向量嵌入提供者 |\n| `AUDREY_LLM_PROVIDER` | 自动检测 | LLM 提供者 |\n| `AUDREY_DEBUG` | `0` | 启用 MCP 信息日志 |\n| `AUDREY_PROFILE` | `0` | 通过 MCP `_meta.diagnostics` 发出各阶段计时 |\n| `AUDREY_DISABLE_WARMUP` | `0` | 跳过 MCP 启动时的后台嵌入预热 |\n| `AUDREY_PRAGMA_DEFAULTS` | `1` | 是否恢复 SQLite PRAGMA 到 better-sqlite3 默认值 |\n\n### 记忆配置\n\n| 变量 | 默认值 | 用途 |\n|------|--------|------|\n| `AUDREY_CONTEXT_BUDGET_CHARS` | `4000` | 记忆胶囊默认字符预算 |\n| `AUDREY_PROMOTE_ROOTS` | 未设置 | `audrey promote --yes` 写入的额外根目录 |\n\n资料来源：[README.md:134-145]()\n\n## 性能指标\n\n### v0.22.0 性能改进\n\n| 指标 | 改进前 | 改进后 | 提升幅度 |\n|------|--------|--------|----------|\n| 编码响应时间 p50 | 24.7ms | 15.2ms | ~40% |\n| 冷启动首次编码 | 525ms | 28ms（预热后） | 18.7x |\n| 混合召回 | 30.2ms | 14.3ms | 2.1x |\n\n**优化策略**：编码过程中消除了 4 个冗余嵌入调用中的 3 个，验证、干扰和情感共鸣现在复用主内容向量。\n\n资料来源：[CHANGELOG.md:25-50]()\n\n## 规则编译与推广\n\n当记忆达到足够置信度时，可通过 `audrey promote` 将记忆提升为持久化规则文件：\n\n```mermaid\ngraph TD\n A[高置信度记忆] --> B[PromotionCandidate]\n B --> C{rules-compiler.ts}\n C --> D[.claude/rules/.md]\n D --> E[YAML frontmatter]\n E --> F[source memory_ids]\n E --> G[confidence + evidence_count]\n E --> H[promotion_timestamp]\n```\n\n每个规则文件包含：\n- 标题：从记忆中推断\n- Slug：自动生成\n- 相对路径：`.claude/rules/.md`\n- 正文：规则内容\n- Frontmatter：源记忆追踪信息\n\n资料来源：[src/rules-compiler.ts:1-30]()\n\n## 记忆胶囊（Capsule）\n\nCapsule 是回合级记忆数据包，按不同分类组织记忆：\n\n| 分类 | 来源条件 |\n|------|----------|\n| `recent_changes` | 最近变化窗口内创建或强化的记忆 |\n| `must_follow` | 标记为必须遵守的规则 |\n| `procedures` | 程序性记忆或标记为程序的记忆 |\n| `user_preferences` | 用户声明的偏好或标记为用户偏好的记忆 |\n| `risks` | 标记为风险或警告的记忆 + 最近工具失败 |\n| `uncertain_or_disputed` | 争议性记忆或低置信度记忆 |\n\n资料来源：[src/capsule.ts:1-80]()\n\n## 生产就绪检查\n\n### 发布门控\n\n```bash\nnpm run release:gate\npython -m unittest discover -s python/tests -v\nnpm run python:release:check\nnpm run bench:guard:card\nnpm run bench:guard:validate\nnpx audrey doctor\nnpx audrey demo\n```\n\n### 生产环境建议\n\n1. 每个租户、环境或隔离边界设置独立的 `AUDREY_DATA_DIR`\n2. 明确指定 `AUDREY_EMBEDDING_PROVIDER` 和 `AUDREY_LLM_PROVIDER`\n3. 提供者或维度变更前备份 SQLite 数据目录\n4. 编码记忆内容中排除 API key 和原始凭证\n5. REST sidecar 可被本地进程外访问时使用 `AUDREY_API_KEY`\n6. 定期运行 `npx audrey dream` 以保持巩固和衰减活跃\n7. 监管环境需添加应用级加密、保留策略、访问控制和审计日志\n\n资料来源：[README.md:70-85]()\n\n## 技术栈\n\n| 层级 | 技术选型 |\n|------|----------|\n| 运行时 | Node.js / TypeScript |\n| CLI 框架 | 未知（基于 mcp-server/index.ts） |\n| REST 框架 | Hono |\n| 数据库 | SQLite + sqlite-vec |\n| Python SDK | httpx + pydantic |\n\n资料来源：[python/README.md:1-30]()\n\n## 许可\n\nAudrey 采用 MIT 许可证开源。\n\n资料来源：[README.md:1]()\n\n---\n\n\n\n## 快速开始\n\n### 相关页面\n\n相关主题：[项目概述](#page-overview), [CLI工具](#page-cli-tools)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/Evilander/Audrey/blob/main/README.md)\n- [python/README.md](https://github.com/Evilander/Audrey/blob/main/python/README.md)\n- [src/routes.ts](https://github.com/Evilander/Audrey/blob/main/src/routes.ts)\n- [src/impact.ts](https://github.com/Evilander/Audrey/blob/main/src/impact.ts)\n- [mcp-server/index.ts](https://github.com/Evilander/Audrey/blob/main/mcp-server/index.ts)\n- [src/rules-compiler.ts](https://github.com/Evilander/Audrey/blob/main/src/rules-compiler.ts)\n \n\n# 快速开始\n\nAudrey 是一个本地优先的 AI 代理内存防火墙，为 Codex、Claude Code、Claude Desktop、Cursor、Windsurf、VS Code、JetBrains、Ollama 后端代理以及自定义代理服务提供持久的内存层。代理可以在执行工具操作前查询此内存层，从而避免重复犯错的命令、保留项目特定规则、发现矛盾信息。\n\n本页面将引导您完成 Audrey 的完整安装、配置和基础使用流程。\n\n## 环境要求\n\n| 组件 | 版本要求 | 说明 |\n|------|----------|------|\n| Node.js | ≥18.0.0 | 用于运行 CLI 和 MCP 服务器 |\n| npm | ≥9.0.0 | 包管理器 |\n| Python | ≥3.10 | 如需使用 Python SDK |\n| SQLite | 3.39+ | 内置支持，，无需单独安装 |\n\n资料来源：[README.md:1-15]()\n\n## 安装方式\n\n### npm 全局安装\n\nAudrey 作为 npm 包发布，可通过 npx 直接运行：\n\n```bash\nnpx audrey serve\n```\n\n或全局安装以获得更好的离线体验：\n\n```bash\nnpm install -g audrey\n```\n\n资料来源：[README.md:88-92]()\n\n### Python SDK 安装\n\n如需在 Python 项目中使用 Audrey：\n\n```bash\npip install audrey-memory\n```\n\n本地开发模式安装：\n\n```bash\ncd python\npython -m pip install -e .\n```\n\n资料来源：[python/README.md:1-18]()\n\n## 启动服务\n\n### 启动 REST API 服务\n\nAudrey 的 REST API 是核心通信接口，CLI、Python SDK 和 MCP 服务器都依赖此接口：\n\n```bash\nnpx audrey serve\n```\n\n服务默认绑定到 `127.0.0.1:7437`，可通过环境变量修改：\n\n| 环境变量 | 默认值 | 说明 |\n|----------|--------|------|\n| `AUDREY_PORT` | `7437` | REST API 监听端口 |\n| `AUDREY_HOST` | `127.0.0.1` | REST API 绑定地址，仅在设置 `AUDREY_API_KEY` 时可设为 `0.0.0.0` |\n| `AUDREY_API_KEY` | 未设置 | 非本地流量需要 Bearer token 认证 |\n| `AUDREY_DATA_DIR` | `./audrey-data` | SQLite 数据库存储目录 |\n\n资料来源：[README.md:98-115]()\n\n### 启动 MCP 服务器\n\nMCP 服务器提供 20 个工具和多个资源端点：\n\n```bash\nnpx audrey mcp-config \n```\n\n支持的 host 类型：\n- `codex` — Codex 代理\n- `generic` — 通用 MCP 客户端\n- `vscode` — VS Code 代理\n\n资料来源：[mcp-server/index.ts:1-30]()\n\n## 基础使用流程\n\n### 架构概览\n\n```mermaid\ngraph TD\n subgraph 客户端层\n CLI[CLI
audrey 命令]\n MCP[MCP 服务器
stdio 连接]\n REST[REST API
HTTP 请求]\n Python[Python SDK
Python 客户端]\n end\n \n subgraph 核心服务\n Server[Hono 服务器
:7437]\n Audrey[Audrey 核心引擎
记忆处理]\n end\n \n subgraph 存储层\n SQLite[(SQLite
主数据库)]\n Vec[(sqlite-vec
向量索引)]\n end\n \n CLI --> Server\n MCP --> Server\n REST --> Server\n Python --> Server\n Server --> Audrey\n Audrey --> SQLite\n Audrey --> Vec\n```\n\n### 内存编码与检索\n\n#### Python SDK 使用\n\n```python\nfrom audrey_memory import Audrey\n\nbrain = Audrey(\n base_url=\"http://127.0.0.1:7437\",\n api_key=\"secret\",\n agent=\"support-agent\",\n)\n\n# 编码记忆\nmemory_id = brain.encode(\n \"Stripe 返回 HTTP 429 超过 100 req/s\",\n source=\"direct-observation\",\n tags=[\"stripe\", \"rate-limit\"],\n)\n\n# 检索相关记忆\nresults = brain.recall(\"stripe rate limit\", limit=5)\n\n# 获取快照\nsnapshot = brain.snapshot()\nbrain.close()\n```\n\n资料来源：[python/README.md:20-60]()\n\n#### REST API 调用\n\n| 端点 | 方法 | 功能 |\n|------|------|------|\n| `/v1/encode` | POST | 编码新记忆 |\n| `/v1/recall` | POST | 检索相关记忆 |\n| `/v1/capsule` | POST | 获取回合级记忆包 |\n| `/v1/status` | GET | 健康检查 |\n\n资料来源：[README.md:68-74]()\n\n### 异步使用\n\n```python\nimport asyncio\nfrom audrey_memory import AsyncAudrey\n\nasync def main() -> None:\n async with AsyncAudrey(base_url=\"http://127.0.0.1:7437\") as brain:\n await brain.health()\n await brain.encode(\"部署失败因 OOM\", source=\"direct-observation\")\n await brain.recall(\"部署失败\", limit=3)\n\nasyncio.run(main())\n```\n\n资料来源：[python/README.md:62-75]()\n\n## Guard 模式：记忆前置检查\n\nAudrey Guard 是核心反馈循环：在执行工具操作前检查记忆，返回 `allow`、`warn` 或 `block` 并附带证据。\n\n### CLI Guard 命令\n\n```bash\nnpx audrey guard --tool Bash \"npm run deploy\"\n```\n\n### 集成 Claude Code\n\n预览钩子配置：\n\n```bash\nnpx audrey hook-config claude-code\n```\n\n应用钩子配置：\n\n```bash\n# 项目级钩子\nnpx audrey hook-config claude-code --apply --scope project\n\n# 用户级钩子\nnpx audrey hook-config claude-code --apply --scope user\n```\n\n生成的 `PreToolUse` 钩子运行 `audrey guard --hook --fail-on-warn`，`PostToolUse` 和 `PostToolUseFailure` 钩子记录脱敏的工具追踪。\n\n资料来源：[README.md:75-82]()\n\n### Guard 工作流程\n\n```mermaid\ngraph TD\n A[代理执行工具] --> B{PreToolUse 钩子}\n B --> C[调用 audrey guard]\n C --> D[查询记忆库]\n D --> E{决策判断}\n E -->|allow| F[允许执行]\n E -->|warn| G[警告执行]\n E -->|block| H[阻止执行]\n G --> I{用户确认?}\n I -->|是| F\n I -->|否| H\n F --> J[PostToolUse 钩子]\n H --> K[记录阻止事件]\n J --> L[编码执行结果]\n K --> L\n```\n\n## 开发环境配置\n\n### 从源码构建\n\n```bash\nnpm ci\nnpm run build\nnpm test\n```\n\n构建后，CLI 子命令解析本地 `dist/` 输出。\n\n资料来源：[README.md:135-145]()\n\n### 完整发布门控\n\n```bash\nnpm run release:gate\npython -m unittest discover -s python/tests -v\nnpm run python:release:check\n```\n\n## 诊断与验证\n\n### 健康检查\n\n```bash\nnpx audrey doctor\nnpx audrey doctor --json\n```\n\n### 状态检查\n\n```bash\nnpx audrey status --json --fail-on-unhealthy\n```\n\n### 影响评估\n\nAudrey 提供影响评估功能，跟踪记忆的验证状态和使用情况：\n\n```bash\nnpx audrey impact --window 30\n```\n\n返回内容包括：\n- 按类型统计（情景记忆、语义记忆、程序记忆）\n- 窗口期内的验证数量\n- 结果分布（helpful、wrong、used）\n- 高频使用的记忆条目\n- 活跃度最弱的记忆条目\n\n资料来源：[src/impact.ts:1-50]()\n\n## 规则编译与提升\n\n### 规则编译\n\nAudrey 支持将记忆提升为可审查的 Markdown 规则文件：\n\n```bash\nnpx audrey promote\n```\n\n生成的规则文件位于 `.claude/rules/` 目录，包含 YAML 前置元数据，记录源记忆 ID、置信度、证据数量和提升时间戳。\n\n资料来源：[src/rules-compiler.ts:1-30]()\n\n### 规则文件结构\n\n```yaml\n---\ntitle: \"Audrey semantic memory xxx\"\nmemory_ids: [\"01ARZ3NDEKTSV4RRFFQ69G5FAV\"]\nconfidence: 0.85\nevidence_count: 5\npromoted_at: \"2025-01-15T10:30:00Z\"\n---\n\n# 规则正文\n```\n\n## 内存模型\n\nAudrey 的内存模型包含以下维度：\n\n| 内存类型 | 说明 | 示例 |\n|----------|------|------|\n| 情景记忆 | 具体观察、工具结果、偏好、会话事实 | \"用户在 macOS 上运行，遇到权限错误\" |\n| 语义记忆 | 从重复证据中提取的巩固原则 | \"macOS 需要 sudo 才能安装全局 npm 包\" |\n| 程序记忆 | 记住的执行方式、避免事项、重试或验证方法 | \"先检查 --dry-run，再实际执行\" |\n| 情感与显著性 | 情感权重和重要性影响召回 | 高情绪记忆更容易被保留 |\n| 干扰与衰减 | 陈旧、冲突或低置信度记忆逐渐失去权威性 | 长时间未使用的记忆降低权重 |\n| 矛盾处理 | 竞争性声明被追踪而非静默覆盖 | 多条相互矛盾的规则同时标记为待验证 |\n\n资料来源：[README.md:53-68]()\n\n## 数据恢复\n\n### 创建快照\n\n```python\nsnapshot = brain.snapshot()\n# 快照可序列化并保存到外部存储\n```\n\n### 恢复快照\n\n```python\nrestore_target = Audrey(base_url=\"http://127.0.0.1:7437\", api_key=\"secret\")\nrestore_target.restore(snapshot)\nrestore_target.close()\n```\n\n恢复只能导入到空的 Audrey 存储，例如使用新的 `AUDREY_DATA_DIR` 启动的 sidecar。\n\n资料来源：[python/README.md:48-57]()\n\n## 生产环境注意事项\n\n| 检查项 | 说明 |\n|--------|------|\n| 数据目录隔离 | 每个租户、环境或隔离边界设置独立的 `AUDREY_DATA_DIR` |\n| 嵌入模型锁定 | 明确锁定 `AUDREY_EMBEDDING_PROVIDER` 和 `AUDREY_LLM_PROVIDER` |\n| 数据备份 | 提供商或维度变更前备份 SQLite 数据目录 |\n| API 密钥保护 | 保持 API 密钥和原始凭据不在编码记忆内容中 |\n| 网络访问控制 | REST sidecar 可被外部访问时必须设置 `AUDREY_API_KEY` |\n| 定期整合 | 按计划运行 `npx audrey dream` 以保持整合和衰减更新 |\n| 监管环境 | 添加应用级加密、保留、访问控制和审计日志 |\n\n资料来源：[README.md:116-132]()\n\n## 常见问题\n\n### Q: 启动时报错 `bind: address already in use`\n\n端口 7437 被占用，可通过 `AUDREY_PORT` 环境变量指定其他端口：\n\n```bash\nAUDREY_PORT=7438 npx audrey serve\n```\n\n### Q: 远程连接被拒绝\n\n默认情况下服务仅绑定 `127.0.0.1`，如需远程访问：\n\n1. 设置 API 密钥：`AUDREY_API_KEY=your-secret`\n2. 修改绑定地址：`AUDREY_HOST=0.0.0.0`\n\n警告：不推荐在生产环境中禁用认证。\n\n### Q: 记忆检索结果不准确\n\n1. 运行 `npx audrey reembed` 重新生成向量索引\n2. 调整 `memory_recall` 参数的 `retrieval` 模式（`hybrid` 或 `vector`）\n3. 检查相关记忆的置信度是否过低（可能被衰减）\n\n资料来源：[README.md:98-115]()\n\n### Q: MCP 服务器连接失败\n\n确保 MCP 配置正确生成：\n\n```bash\nnpx audrey mcp-config --dry-run\n```\n\n验证 MCP 服务器已启动并监听 stdio。\n\n---\n\n\n\n## 系统架构\n\n### 相关页面\n\n相关主题：[项目概述](#page-overview), [记忆模型](#page-memory-model), [数据存储](#page-data-storage)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/audrey.ts](https://github.com/Evilander/Audrey/blob/main/src/audrey.ts)\n- [src/routes.ts](https://github.com/Evilander/Audrey/blob/main/src/routes.ts)\n- [src/db.ts](https://github.com/Evilander/Audrey/blob/main/src/db.ts)\n- [mcp-server/index.ts](https://github.com/Evilander/Audrey/blob/main/mcp-server/index.ts)\n- [src/server.ts](https://github.com/Evilander/Audrey/blob/main/src/server.ts)\n- [src/capsule.ts](https://github.com/Evilander/Audrey/blob/main/src/capsule.ts)\n- [src/redact.ts](https://github.com/Evilander/Audrey/blob/main/src/redact.ts)\n- [src/rules-compiler.ts](https://github.com/Evilander/Audrey/blob/main/src/rules-compiler.ts)\n- [src/impact.ts](https://github.com/Evilander/Audrey/blob/main/src/impact.ts)\n \n\n# 系统架构\n\n## 概述\n\nAudrey 是一个本地优先的 AI 代理内存防火墙（local-first memory firewall），为 Codex、Claude Code、Cursor、Windsurf 等 AI 代理提供持久化的记忆层。其核心设计目标是在代理执行操作前检查记忆，在操作后记录经验，形成闭环的学习-验证机制。\n\n系统架构采用分层设计，核心层基于 TypeScript 实现，通过 MCP（Model Context Protocol）协议与各类 AI 代理集成，同时提供 REST API 和 Python SDK 供外部调用。\n\n## 架构总览\n\n```mermaid\ngraph TB\n subgraph 代理层\n A[Claude Code] \n B[Codex] \n C[Cursor] \n D[VS Code]\n end\n \n subgraph 协议层\n E[MCP stdio 服务器]\n F[REST API 服务器]\n G[CLI 接口]\n end\n \n subgraph 核心引擎\n H[Audrey 核心]\n I[记忆模型]\n J[检索引擎]\n end\n \n subgraph 存储层\n K[SQLite]\n L[sqlite-vec 向量索引]\n end\n \n A --> E\n B --> E\n C --> E\n D --> E\n \n F --> H\n E --> H\n G --> H\n \n H --> I\n H --> J\n \n I --> K\n J --> L\n J --> K\n```\n\n## 核心组件\n\n### Audrey 核心引擎\n\n核心引擎位于 `src/audrey.ts`，是整个系统的心脏，负责记忆的编码、检索、衰减和一致性管理。\n\n| 组件 | 职责 | 关键方法 |\n|------|------|----------|\n| 记忆编码 | 将观察和经验转化为可存储的记忆 | `encode()`, `consolidate()` |\n| 检索引擎 | 基于向量和关键词的混合检索 | `recall()`, `recallStream()` |\n| 信任度管理 | 基于时间的衰减和证据强化 | `decay()`, `reinforce()` |\n| 矛盾处理 | 追踪竞争性记忆而非静默覆盖 | 资料来源：[src/audrey.ts:1-200]() |\n\n### 数据库层\n\n数据持久化采用双索引架构，同时支持 SQLite 原生查询和向量相似度检索。\n\n| 数据库 | 位置 | 用途 |\n|--------|------|------|\n| SQLite 主库 | `AUDREY_DATA_DIR/memory.db` | 结构化记忆存储 |\n| sqlite-vec | `AUDREY_DATA_DIR/vectors.db` | 向量嵌入索引 |\n\n> **重要**：SQLite 使用 WAL 模式但无咨询锁，多进程共享同一目录会产生写竞争。每个租户或代理必须设置独立的 `AUDREY_DATA_DIR`。\n\n资料来源：[src/db.ts:1-100]()\n\n### MCP 服务器\n\nMCP 服务器（`mcp-server/index.ts`）提供标准化的工具接口，使 Audrey 能以 stdio 模式与各类 AI 代理通信。\n\n**支持的 MCP 工具集**（共 20 个工具）：\n\n| 工具分类 | 工具名称 |\n|----------|----------|\n| 记忆操作 | `memory_encode`, `memory_recall`, `memory_snapshot` |\n| 安全防护 | `guard_preflight`, `guard_postflight` |\n| 管理功能 | `status`, `introspect`, `dream` |\n\nMCP 服务器通过以下步骤与代理集成：\n\n1. 解析命令行参数（host 类型、dry-run 模式等）\n2. 生成特定代理的配置文件\n3. 启动 stdio 连接循环\n4. 处理工具调用请求\n\n资料来源：[mcp-server/index.ts:1-150]()\n\n### REST API 服务器\n\nREST API 基于 Hono 框架构建，提供轻量级的 HTTP 接口。\n\n**可用路由**：\n\n| 方法 | 路径 | 功能 |\n|------|------|------|\n| `GET` | `/health` | 健康检查 |\n| `POST` | `/v1/encode` | 编码记忆 |\n| `POST` | `/v1/recall` | 检索相关记忆 |\n| `POST` | `/v1/capsule` | 获取回合级记忆包 |\n| `GET` | `/v1/status` | 获取系统状态 |\n\n**安全特性**：\n- 默认绑定 `127.0.0.1`，禁止非本地访问\n- 非环回地址必须提供 `AUDREY_API_KEY`\n- HTTP API Key 比较使用 `crypto.timingSafeEqual` 防止时序攻击\n\n资料来源：[src/routes.ts:1-100](), [src/server.ts:1-80]()\n\n## 记忆模型\n\nAudrey 实现了一套多维记忆模型，模拟人类记忆的复杂性。\n\n```mermaid\ngraph LR\n A[观察/交互] --> B[编码]\n B --> C[情景记忆]\n B --> D[语义记忆]\n B --> E[程序记忆]\n C --> F[信任度计算]\n D --> F\n E --> F\n F --> G{衰减/强化}\n G -->|高信任| H[长期记忆]\n G -->|低信任| I[遗忘]\n```\n\n### 记忆类型\n\n| 类型 | 说明 | 典型来源 |\n|------|------|----------|\n| 情景记忆 | 特定观察、工具结果、偏好、会话事实 | `direct-observation` |\n| 语义记忆 | 从重复证据中提取的固化原则 | `consolidated` |\n| 程序记忆 | 记住的行动方式、规避策略、验证方法 | `procedure` |\n\n### 信任度与衰减\n\n每条记忆关联一个信任度分数（0-1），通过以下公式计算：\n\n```\nnew_confidence = old_confidence + (evidence_weight * reinforcement_factor)\n```\n\n衰减采用半衰期模型：\n\n```\ndecayed = original * 0.5^(days_elapsed / half_life_days)\n```\n\n> 半衰期必须大于 0，否则抛出 `RangeError`。\n\n资料来源：[src/audrey.ts:200-350](), [src/impact.ts:50-120]()\n\n## 工作流程\n\n### Guard 循环（核心安全环）\n\n```mermaid\nsequenceDiagram\n participant Agent as AI 代理\n participant Guard as Audrey Guard\n participant Memory as 记忆存储\n participant User as 用户\n \n Agent->>Guard: 执行操作前请求\n Guard->>Memory: 检索相关记忆\n Memory-->>Guard: 历史经验和规则\n Guard->>Guard: 分析风险和矛盾\n Guard-->>Agent: allow / warn / block + 证据\n \n alt allow\n Agent->>User: 执行操作\n Agent->>Guard: 操作结果\n Guard->>Memory: 记录经验\n else warn\n Agent->>Agent: 显示警告给用户\n User-->>Agent: 确认/取消\n end\n```\n\n**Guard 命令行用法**：\n\n```bash\naudrey guard --tool Bash \"npm run deploy\"\naudrey guard --hook --fail-on-warn # MCP 钩子模式\n```\n\n资料来源：[mcp-server/index.ts:150-300]()\n\n### 记忆编码流程\n\n```mermaid\ngraph TD\n A[输入文本] --> B[生成 ULID]\n B --> C[计算向量嵌入]\n C --> D[情感分析]\n D --> E[检查矛盾]\n E --> F{发现矛盾?}\n F -->|是| G[标记为 disputed]\n F -->|否| H[正常状态]\n G --> I[存储记忆]\n H --> I\n I --> J[更新向量索引]\n J --> K[返回 memory_id]\n```\n\n记忆编码支持以下元数据：\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| `source` | string | 记忆来源（direct-observation, told-by-user 等） |\n| `tags` | string[] | 标签数组 |\n| `memory_type` | enum | episodic / semantic / procedural |\n| `private` | boolean | 是否私有（仅创建者可读） |\n\n资料来源：[src/audrey.ts:350-500]()\n\n### 检索流程\n\nAudrey 支持三种检索模式：\n\n| 模式 | 说明 | 性能 |\n|------|------|------|\n| `hybrid`（默认） | 向量 + FTS 混合检索 | 约 14.3ms p50 |\n| `vector` | 纯向量检索（绕过 FTS） | 更快 |\n\n**检索选项白名单**（HTTP API 强制校验）：\n\n- `query`、`limit`、`scope`\n- `tags`、`sources`（数组）\n- `after`、`before`（时间范围）\n- `retrieval`（hybrid/vector）\n\n资料来源：[src/routes.ts:50-150]()\n\n## 数据流与隐私\n\n### 工具调用脱敏\n\n在记录工具调用结果前，系统自动脱敏敏感信息：\n\n```typescript\nconst SENSITIVE_KEY_PATTERN = /(password|secret|api[_-]?key|token)$/i;\n```\n\n脱敏规则覆盖：\n- API 密钥和令牌\n- 密码和私钥\n- Bearer Token\n- AWS 密钥\n- JWT\n\n资料来源：[src/redact.ts:50-100]()\n\n### 私有记忆隔离\n\n私有记忆通过 `private: true` 标记，仅创建者 `agent` 可检索。HTTP API 的 `/v1/recall` 端点实施 ACL 检查，防止跨代理泄露。\n\n> 注意：`includePrivate: true` 不能通过 HTTP 请求体传入（安全修复 v0.22.0）。\n\n## 部署架构\n\n### 多租户隔离\n\n```mermaid\ngraph TB\n subgraph 主机 A\n A1[Agent 1]\n A2[AUDREY_DATA_DIR=/data/agent1]\n end\n \n subgraph 主机 B\n B1[Agent 2]\n B2[AUDREY_DATA_DIR=/data/agent2]\n end\n \n subgraph 主机 C\n C1[Agent 3]\n C2[AUDREY_DATA_DIR=/data/agent3]\n end\n \n A1 --> A2\n B1 --> B2\n C1 --> C2\n```\n\n### 环境变量配置\n\n| 变量 | 默认值 | 说明 |\n|------|--------|------|\n| `AUDREY_DATA_DIR` | `./audrey-data` | 数据存储目录 |\n| `AUDREY_API_KEY` | unset | 非本地访问的 Bearer 令牌 |\n| `AUDREY_HOST` | `127.0.0.1` | REST 服务绑定地址 |\n| `AUDREY_ENABLE_ADMIN_TOOLS` | `0` | 启用导出/导入/遗忘工具 |\n| `AUDREY_CONTEXT_BUDGET_CHARS` | `4000` | 记忆胶囊默认字符预算 |\n| `AUDREY_DEBUG` | `0` | 打印 MCP 调试日志 |\n\n### 启动方式\n\n| 方式 | 命令 | 用途 |\n|------|------|------|\n| MCP stdio | `npx audrey` | 直接集成 AI 代理 |\n| REST 服务 | `npx audrey serve` | 供 Python SDK 或外部调用 |\n| CLI 工具 | `npx audrey guard ...` | 终端手动检查 |\n\n## 规则编译与推广\n\n当需要将记忆固化为持久规则时，Audrey 提供规则编译功能：\n\n```mermaid\ngraph LR\n A[PromotionCandidate] --> B[规则编译]\n B --> C[Markdown 文件]\n C --> D[.claude/rules/]\n D --> E[Claude Code 提示]\n```\n\n规则文件格式：\n```markdown\n---\ntitle: \"警告：高风险操作\"\nsource_memory_ids: [\"01AR...\",\"01AS...\"]\nconfidence: 0.85\nevidence_count: 5\npromoted_at: \"2024-01-15T10:30:00Z\"\n---\n\n内容正文...\n```\n\n资料来源：[src/rules-compiler.ts:1-100]()\n\n## 影响评估\n\nAudrey 提供 `impact` 命令分析记忆库的健康状态：\n\n| 指标 | 说明 |\n|------|------|\n| `validatedTotal` | 经过验证的记忆总数 |\n| `validatedInWindow` | 时间窗口内的验证记忆 |\n| `outcomeBreakdownInWindow` | 近期操作结果分布（helpful/wrong/used） |\n| `topUsed` | 高频使用记忆 |\n| `weakest` | 信任度最低的记忆 |\n\n资料来源：[src/impact.ts:100-200]()\n\n## 扩展阅读\n\n- [快速开始指南](../guides/getting-started.md)\n- [Guard 循环详解](../guides/guard-loop.md)\n- [Python SDK 文档](../python/README.md)\n- [CLI 命令参考](../cli/commands.md)\n\n---\n\n\n\n## 记忆模型\n\n### 相关页面\n\n相关主题：[系统架构](#page-system-architecture), [Audrey Guard 安全循环](#page-audrey-guard), [数据存储](#page-data-storage)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/Evilander/Audrey/blob/main/README.md)\n- [src/impact.ts](https://github.com/Evilander/Audrey/blob/main/src/impact.ts)\n- [src/routes.ts](https://github.com/Evilander/Audrey/blob/main/src/routes.ts)\n- [src/capsule.ts](https://github.com/Evilander/Audrey/blob/main/src/capsule.ts)\n- [src/promote.ts](https://github.com/Evilander/Audrey/blob/main/src/promote.ts)\n- [src/redact.ts](https://github.com/Evilander/Audrey/blob/main/src/redact.ts)\n \n\n# 记忆模型\n\n## 概述\n\nAudrey 的记忆模型是一个专为 AI 代理设计的本地优先记忆防火墙，旨在解决代理\"遗忘昨日错误\"的核心问题。该模型通过多层次、可验证的记忆系统，使代理能够在执行操作前检查相关记忆，从而避免重复犯错、保持项目特定规则的连续性。资料来源：[README.md](https://github.com/Evilander/Audrey/blob/main/README.md)\n\n## 核心架构\n\nAudrey 记忆模型采用三层记忆架构，结合情感权重和干扰衰减机制，形成一个动态、可自适应的记忆系统。\n\n```mermaid\ngraph TD\n A[用户交互/工具执行] --> B[事件编码]\n B --> C{记忆类型分类}\n C --> D[情节记忆
Episodic]\n C --> E[语义记忆
Semantic]\n C --> F[程序记忆
Procedural]\n D --> G[记忆存储]\n E --> G\n F --> G\n G --> H[检索系统]\n H --> I{mood 影响}\n H --> J{干扰检测}\n H --> K{衰减处理}\n I --> L[最终检索结果]\n J --> L\n K --> L\n L --> M[Preflight 检查]\n M --> N{allow/warn/block}\n```\n\n## 记忆类型体系\n\nAudrey 将记忆划分为三种核心类型，每种类型具有不同的生命周期和用途。\n\n### 情节记忆 (Episodic Memory)\n\n情节记忆记录特定的观察结果、工具执行结果、用户偏好和会话事实。它是系统获取新知识的主要入口，通常来源于直接观察或用户告知。资料来源：[README.md](https://github.com/Evilander/Audrey/blob/main/README.md)\n\n| 属性 | 说明 |\n|------|------|\n| 内容 | 具体的观察、事件、偏好 |\n| 来源 | direct-observation、told-by-user |\n| 状态 | 活跃/已验证/已衰减 |\n| 置信度 | 基于证据数量和支持度计算 |\n\n### 语义记忆 (Semantic Memory)\n\n语义记忆是从重复证据中提炼出的巩固原则。它代表了系统经过验证的核心信念，要求更高的置信度门槛才能晋升为语义记忆。资料来源：[README.md](https://github.com/Evilander/Audrey/blob/main/README.md)\n\n语义记忆的晋升条件：\n\n```typescript\n// 资料来源：src/promote.ts\nif (evidence < Math.max(minEvidence, 3)) continue;\nif ((row.contradicting_count ?? 0) > 0) continue;\n```\n\n晋升要求：\n- 至少 3 条证据支持\n- 无矛盾证据记录\n- 状态为活跃 (active)\n\n### 程序记忆 (Procedural Memory)\n\n程序记忆记录\"如何行动、如何避免、如何重试、如何验证\"的具体步骤。它直接关联工具使用和操作流程。资料来源：[README.md](https://github.com/Evilander/Audrey/blob/main/README.md)\n\n程序记忆的晋升条件相对宽松，关注实用性：\n\n```typescript\n// 资料来源：src/promote.ts\nif ((row.failure_prevented ?? 0) > 0) {\n reasonParts.push(`${row.failure_prevented} failure prevented`);\n}\nif ((row.usage_count ?? 0) > 0) {\n reasonParts.push(`used ${row.usage_count} time(s)`);\n}\n```\n\n## 置信度与强化机制\n\n### 置信度计算\n\nAudrey 使用基于证据和支持度的置信度计算模型，通过 `confidence.ts` 模块实现强化公式。\n\n```mermaid\ngraph LR\n A[新证据] --> B{证据类型}\n B -->|支持性| C[supporting_count++]\n B -->|矛盾性| D[contradicting_count++]\n C --> E[置信度计算]\n D --> E\n E --> F{salience 更新}\n```\n\n### 强化反馈循环\n\nAudrey 实现了闭环反馈机制，通过 `memory_validate` 工具收集用户反馈并调整记忆权重。\n\n| 反馈结果 | 语义记忆影响 | 程序记忆影响 |\n|----------|--------------|--------------|\n| helpful | salience↑, retrieval_count↑ | salience↑ |\n| wrong | salience↓, challenge_count↑ | salience↓ |\n| used | 较小 salience 增量 | salience 增量 |\n\n资料来源：[CHANGELOG.md](https://github.com/Evilander/Audrey/blob/main/CHANGELOG.md)\n\n## 情感与显著性系统\n\n### 情感影响 (Affect)\n\n情感影响基于记忆的情感权重和唤醒度 (arousal)，影响检索结果的排序和优先级。\n\n```typescript\n// 资料来源：src/capsule.ts\nif (trustedControlSource && hashMatchesAny(lowerTags, MUST_FOLLOW_TAGS)) {\n sections.add('must_follow');\n}\n\nif (result.source === 'told-by-user') {\n sections.add('user_preferences');\n}\n```\n\n### 显著性 (Salience)\n\n显著性决定记忆在检索时的权威程度，受以下因素影响：\n\n- 使用频率 (usage_count)\n- 上次使用时间 (last_used_at)\n- 证据强度 (evidence_count)\n- 情感权重\n\n资料来源：[src/impact.ts](https://github.com/Evilander/Audrey/blob/main/src/impact.ts)\n\n## 干扰与衰减机制\n\n### 干扰检测 (Interference)\n\n当存在相互矛盾的证据时，系统不会静默覆盖，而是跟踪这些矛盾状态。资料来源：[README.md](https://github.com/Evilander/Audrey/blob/main/README.md)\n\n```mermaid\ngraph TD\n A[新记忆] --> B{与现有记忆冲突?}\n B -->|是| C[标记为 disputed]\n B -->|否| D[正常存储]\n C --> E[跟踪矛盾证据]\n E --> F[保留双方记录]\n D --> G[更新支持度]\n```\n\n### 衰减处理 (Decay)\n\n陈旧、冲突或低置信度的记忆会随时间降低权威性，确保最新、最准确的信息占据主导地位。资料来源：[README.md](https://github.com/Evilander/Audrey/blob/main/README.md)\n\n衰减考虑因素：\n- 时间间隔（半衰期）\n- 检索频率\n- 矛盾证据数量\n- 最后强化时间\n\n## 记忆胶囊 (Memory Capsule)\n\n记忆胶囊是一种 turn-sized 的记忆数据包，用于在特定上下文中快速获取相关记忆。\n\n### 胶囊分段\n\n```typescript\n// 资料来源：src/capsule.ts\nconst sections = new Set();\n\nif (trustedControlSource && hashMatchesAny(lowerTags, MUST_FOLLOW_TAGS)) {\n sections.add('must_follow');\n}\n\nif (hashMatchesAny(lowerTags, RISK_TAGS)) {\n sections.add('risks');\n}\n\nif (entry.memory_type === 'procedural') {\n sections.add('procedures');\n}\n\nif (result.confidence < 0.55) {\n sections.add('uncertain_or_disputed');\n}\n```\n\n### 胶囊分区表\n\n| 分区名称 | 触发条件 |\n|----------|----------|\n| must_follow | 可信来源 + 必须遵循标签 |\n| risks | 包含风险标签 |\n| procedures | 程序记忆类型或程序标签 |\n| user_preferences | 用户偏好标签或 told-by-user 来源 |\n| recent_changes | 最近时间窗口内的更新 |\n| uncertain_or_disputed | 争议状态或低置信度 (<0.55) |\n| project_facts | 默认语义/情节记忆 |\n\n## 记忆验证流程\n\n### Preflight 检查\n\n在执行工具操作前，系统执行预检查以确保行动的安全性。\n\n```mermaid\ngraph TD\n A[工具调用请求] --> B[检索相关记忆]\n B --> C{检查失败历史}\n B --> D{检查风险标记}\n B --> E{检查相关规则}\n B --> F{检查验证程序}\n C --> G{决策生成}\n D --> G\n E --> G\n F --> G\n G --> H{allow/warn/block}\n```\n\n### 验证反馈\n\n验证结果通过 REST API 端点收集：\n\n| 端点 | 用途 | 参数 |\n|------|------|------|\n| POST /v1/validate | 标准验证 | id, outcome |\n| POST /v1/mark-used | 遗留别名 | memory_id, outcome |\n\n资料来源：[CHANGELOG.md](https://github.com/Evilander/Audrey/blob/main/CHANGELOG.md)\n\n## 规则晋升系统\n\n高质量的程序记忆和语义记忆可以被晋升为可执行的规则文件。\n\n### 晋升条件对比\n\n| 条件 | 程序记忆 | 语义记忆 |\n|------|----------|----------|\n| 证据数量 | ≥1 | ≥3 |\n| 失败预防数 | >0 或使用次数 >0 | - |\n| 矛盾限制 | 无限制 | 必须为 0 |\n| 晋升目标 | .claude/rules/*.md | .claude/rules/*.md |\n\n资料来源：[src/promote.ts](https://github.com/Evilander/Audrey/blob/main/src/promote.ts)\n\n### 规则编译\n\n规则文件包含 YAML front matter，记录来源记忆 ID、置信度、证据数量等信息。\n\n```typescript\n// 资料来源：src/rules-compiler.ts\nexport interface RuleDoc {\n title: string;\n slug: string;\n relativePath: string;\n body: string;\n frontmatter: Record;\n}\n```\n\n## 记忆数据模型\n\n### 数据库存储\n\nAudrey 使用 SQLite 作为本地存储，结合 sqlite-vec 支持向量检索。\n\n```sql\n-- 情节记忆表结构（示意）\nCREATE TABLE episodes (\n id TEXT PRIMARY KEY,\n content TEXT NOT NULL,\n source TEXT,\n state TEXT DEFAULT 'active',\n salience REAL,\n usage_count INTEGER DEFAULT 0,\n created_at TEXT,\n last_used_at TEXT\n);\n\n-- 语义记忆表结构（示意）\nCREATE TABLE semantics (\n id TEXT PRIMARY KEY,\n content TEXT NOT NULL,\n state TEXT DEFAULT 'active',\n evidence_count INTEGER DEFAULT 0,\n supporting_count INTEGER DEFAULT 0,\n contradicting_count INTEGER DEFAULT 0,\n confidence REAL,\n salience REAL,\n created_at TEXT\n);\n```\n\n### 检索模式\n\n| 模式 | 描述 | 性能特点 |\n|------|------|----------|\n| hybrid | 混合检索（向量 + 全文） | 默认模式，平衡精度与召回 |\n| vector | 仅向量检索 | FTS 旁路快速路径 |\n\n资料来源：[CHANGELOG.md](https://github.com/Evilander/Audrey/blob/main/CHANGELOG.md)\n\n## 私有记忆与访问控制\n\n### 隐私隔离\n\nHTTP `/v1/recall` 和 `/v1/capsule` 不再将调用者选项体传播到 `audrey.recall()`，防止通过 HTTP 请求绕过私有记忆 ACL。资料来源：[CHANGELOG.md](https://github.com/Evilander/Audrey/blob/main/CHANGELOG.md)\n\n### 选项白名单\n\n```typescript\n// 资料来源：src/routes.ts\nconst ALLOWED_KEYS: Set = new Set([\n 'limit', 'offset', 'agent', 'tags', 'sources',\n 'after', 'before', 'context', 'mood', 'retrieval', 'scope'\n]);\n```\n\n## 安全机制\n\n### 敏感信息脱敏\n\n```typescript\n// 资料来源：src/redact.ts\nconst SENSITIVE_KEY_PATTERN = /(^|_|-)(password|passwd|pwd|secret|api[_-]?key|auth[_-]?token|bearer[_-]?token|...)$/i;\n```\n\n脱敏状态：\n- `clean` - 无敏感信息\n- `redacted` - 已脱敏\n\n## 影响统计与监控\n\n### 记忆统计接口\n\n```typescript\n// 资料来源：src/impact.ts\ninterface ImpactReport {\n generatedAt: string;\n windowDays: number;\n totals: {\n episodic: number;\n semantic: number;\n procedural: number;\n };\n validatedTotal: number;\n validatedInWindow: number;\n byType: {\n episodic: { validated: number; recent: number };\n semantic: { validated: number; recent: number; challenged: number };\n procedural: { validated: number; recent: number };\n };\n outcomeBreakdownInWindow: {\n helpful: number;\n wrong: number;\n used: number;\n };\n topUsed: MemoryRow[];\n weakest: MemoryRow[];\n recentActivity: MemoryRow[];\n}\n```\n\n## 梦 Consolidation\n\n`audrey dream` 命令执行记忆巩固和衰减处理，将情节记忆合并为原则并应用衰减机制。资料来源：[README.md](https://github.com/Evilander/Audrey/blob/main/README.md)\n\n建议按计划运行以保持巩固和衰减的最新状态。\n\n## 环境变量配置\n\n| 变量 | 默认值 | 用途 |\n|------|--------|------|\n| AUDREY_DATA_DIR | - | 租户/环境数据目录 |\n| AUDREY_EMBEDDING_PROVIDER | - | 嵌入提供商 |\n| AUDREY_LLM_PROVIDER | - | LLM 提供商 |\n| AUDREY_API_KEY | - | API 密钥认证 |\n\n资料来源：[README.md](https://github.com/Evilander/Audrey/blob/main/README.md)\n\n---\n\n\n\n## Audrey Guard 安全循环\n\n### 相关页面\n\n相关主题：[记忆模型](#page-memory-model), [MCP集成](#page-mcp-integration), [REST API](#page-rest-api), [CLI工具](#page-cli-tools)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/preflight.ts](https://github.com/Evilander/Audrey/blob/main/src/preflight.ts)\n- [src/reflexes.ts](https://github.com/Evilander/Audrey/blob/main/src/reflexes.ts)\n- [src/redact.ts](https://github.com/Evilander/Audrey/blob/main/src/redact.ts)\n- [src/feedback.ts](https://github.com/Evilander/Audrey/blob/main/src/feedback.ts)\n- [src/action-key.ts](https://github.com/Evilander/Audrey/blob/main/src/action-key.ts)\n- [mcp-server/index.ts](https://github.com/Evilander/Audrey/blob/main/mcp-server/index.ts)\n- [src/capsule.ts](https://github.com/Evilander/Audrey/blob/main/src/capsule.ts)\n- [src/impact.ts](https://github.com/Evilander/Audrey/blob/main/src/impact.ts)\n \n\n# Audrey Guard 安全循环\n\nAudrey Guard 是 Audrey 项目中的核心安全机制，为 AI Agent 提供内存优先的动作检查能力。在 Agent 执行任何工具调用之前，Guard 会查询持久化记忆，评估潜在风险，并根据历史经验返回允许、警告或阻止的决策。\n\n## 核心概念\n\n### 安全循环的工作原理\n\nAudrey Guard 采用**记录-记忆-检查-响应-验证**的闭环设计：\n\n1. **记忆编码** (`memory_encode`): 将 Agent 的操作经验、错误教训、项目规则编码存储\n2. **预检执行** (`memory_preflight`): 动作执行前查询相关记忆，评估风险等级\n3. **决策返回**: 输出 `allow`（允许）、`warn`（警告）或 `block`（阻止）决策\n4. **反射生成** (`memory_reflexes`): 将记忆证据转换为可执行的触发-响应指导\n5. **反馈验证** (`memory_validate`): 动作完成后收集结果，更新记忆权重\n\n```mermaid\ngraph TD\n A[Agent 工具调用请求] --> B[memory_preflight 预检]\n B --> C{查询记忆数据库}\n C --> D[评估风险与规则匹配]\n D --> E{风险等级判断}\n E -->|低风险| F[allow 允许]\n E -->|中风险| G[warn 警告 + 证据]\n E -->|高风险| H[block 阻止]\n F --> I[执行工具]\n G --> I\n H --> J[终止执行]\n I --> K[memory_validate 验证结果]\n K --> L[更新 salience 与 confidence]\n K --> M[反馈循环: helpful/used/wrong]\n```\n\n资料来源：[mcp-server/index.ts:58-75]()\n\n### 决策类型\n\n| 决策类型 | 含义 | 触发条件 |\n|---------|------|---------|\n| `allow` | 允许执行 | 无历史风险记忆、规则验证通过 |\n| `warn` | 带警告执行 | 存在低置信风险记忆、需要人工确认 |\n| `block` | 阻止执行 | 存在高风险记忆、规则明确禁止、重复失败 |\n\n资料来源：[mcp-server/index.ts:58-65]()\n\n## 预检系统 (Preflight)\n\n预检是 Guard 的核心检查模块，在动作执行前全面评估各种风险因素。\n\n### 检查维度\n\n`memory_preflight` 从多个维度进行综合评估：\n\n```typescript\ninterface PreflightOptions {\n tool: string; // 工具名称\n action?: string; // 具体动作描述\n sessionId?: string; // 会话标识\n mode?: 'normal' | 'strict'; // 检查严格程度\n failure_window_hours?: number; // 失败历史时间窗口\n recent_failure_window_hours?: number; // 最近失败窗口\n recent_change_window_hours?: number; // 最近变更窗口\n}\n```\n\n资料来源：[src/routes.ts:23-36]()\n\n### Memory Capsule 预检内容\n\n预检返回的 Memory Capsule 包含结构化的记忆分段：\n\n```mermaid\ngraph LR\n A[查询结果] --> B[recent_changes 近期变更]\n A --> C[must_follow 强制规则]\n A --> D[procedures 流程规范]\n A --> E[risks 风险提示]\n A --> F[user_preferences 用户偏好]\n A --> G[uncertain_or_disputed 不确定信息]\n A --> H[project_facts 项目事实]\n```\n\n资料来源：[src/capsule.ts:35-60]()\n\n### 风险标签系统\n\n预检模块使用标签系统标记不同类型的风险记忆：\n\n| 标签类型 | 标签值 | 记忆分段归属 |\n|---------|--------|------------|\n| 强制规则 | `MUST_FOLLOW_TAGS` | `must_follow` |\n| 风险警告 | `RISK_TAGS` | `risks` |\n| 流程规范 | `PROCEDURE_TAGS` | `procedures` |\n| 用户偏好 | `PREFERENCE_TAGS` | `user_preferences` |\n| 低置信 | `confidence < 0.55` | `uncertain_or_disputed` |\n\n资料来源：[src/capsule.ts:62-85]()\n\n### 近期失败检测\n\n预检自动查询最近 7 天内的工具失败记录，识别反复出现的错误模式：\n\n```typescript\nconst failures = recentFailures(db, {\n since: new Date(Date.now() - 7 * 24 * 60 * 60 * 1000).toISOString(),\n limit: 5\n});\n```\n\n这些失败记录会自动添加到 Capsule 的 `risks` 分段，作为动作前的警告依据。\n\n资料来源：[src/capsule.ts:52-56]()\n\n## 反射机制 (Reflexes)\n\n`memory_reflexes` 是 Audrey Guard 的触发-响应转换层，将历史记忆转化为 Agent 可直接执行的指导规则。\n\n### 反射生成流程\n\n```mermaid\ngraph TD\n A[记忆事件] --> B[提取证据内容]\n B --> C[识别触发条件]\n C --> D[生成响应规则]\n D --> E[格式化为 Markdown]\n E --> F[添加 YAML 前置元数据]\n F --> G[持久化到规则文件]\n```\n\n### 规则文件结构\n\nAudrey 将反射规则存储为 Markdown 文件，包含 YAML 前置元数据：\n\n```yaml\n---\nmemory_ids: [mem_xxx123, mem_xxx456]\nconfidence: 0.85\nevidence_count: 3\npromoted_at: \"2024-01-15T10:30:00Z\"\n---\n```\n\n资料来源：[src/rules-compiler.ts:1-30]()\n\n### 标题与 Slug 生成\n\n规则编译器使用停用词过滤生成可读的 slug：\n\n```typescript\nconst STOP_WORDS = new Set(['the', 'a', 'an', 'is', 'of', 'and', 'or', 'to', 'for', 'with', 'on', 'at', 'by', 'in', 'as']);\n\nfunction slugifyTitle(title: string): string {\n const words = lowered.split(/[^a-z0-9]+/).filter(w => w && !STOP_WORDS.has(w));\n return words.slice(0, 6).join('-');\n}\n```\n\n资料来源：[src/rules-compiler.ts:23-27]()\n\n## 数据脱敏 (Redaction)\n\nGuard 在记录工具输入输出时自动执行敏感数据脱敏，防止凭证和密钥被永久存储。\n\n### 敏感字段检测\n\n```typescript\nconst SENSITIVE_KEY_PATTERN = /(^|_|-)(password|passwd|pwd|secret|api[_-]?key|auth[_-]?token|bearer[_-]?token|access[_-]?token|refresh[_-]?token|client[_-]?secret|private[_-]?key|session[_-]?token|jwt|aws[_-]?secret|token)$/i;\n```\n\n资料来源：[src/redact.ts:35-36]()\n\n### 脱敏操作\n\n| 操作类型 | 脱敏内容 | 输出格式 |\n|---------|---------|---------|\n| JSON 键值对 | 匹配模式的键名 | `[REDACTED:api_key]` |\n| 明文密钥 | 常见密钥格式 | `[REDACTED:token]` |\n| Bearer Token | Authorization 头 | `[REDACTED:bearer]` |\n\n资料来源：[src/redact.ts:38-60]()\n\n### 脱敏状态\n\n脱敏结果包含状态标识：\n\n```typescript\ninterface RedactionResult {\n text: string; // 脱敏后的文本\n redactions: RedactionHit[]; // 脱敏操作记录\n state: 'clean' | 'redacted'; // 整体状态\n}\n```\n\n## 反馈验证 (Feedback)\n\n`memory_validate` 关闭安全循环的最后一步，通过收集执行结果反馈来更新记忆权重。\n\n### 结果类型\n\n| 结果类型 | 含义 | 权重影响 |\n|---------|------|---------|\n| `helpful` | 记忆有帮助 | salience + |\n| `used` | 记忆被使用 | usage_count + |\n| `wrong` | 记忆有误 | salience - |\n\n资料来源：[src/impact.ts:25-35]()\n\n### 反馈数据结构\n\n```typescript\ninterface EventOutcome {\n helpful?: number;\n used?: number;\n wrong?: number;\n // 或通过证据反馈映射\n evidence_feedback?: Record;\n}\n```\n\n### Impact 追踪\n\nAudrey 维护全局的 Impact 指标，用于评估记忆系统的实际效果：\n\n```typescript\ninterface ImpactReport {\n windowDays: number;\n totals: {\n episodic: number; // 情景记忆总数\n semantic: number; // 语义记忆总数\n procedural: number; // 流程记忆总数\n };\n validatedTotal: number; // 已验证记忆数\n validatedInWindow: number; // 窗口内验证数\n topUsed: MemoryEntry[]; // 高使用频率记忆\n weakest: MemoryEntry[]; // 低权重记忆\n recentActivity: MemoryEntry[]; // 近期活动\n}\n```\n\n资料来源：[src/impact.ts:40-60]()\n\n## CLI 命令行接口\n\n### guard 命令\n\n```bash\nnpx audrey guard --tool Bash \"npm run deploy\"\n```\n\n### 命令行参数\n\n| 参数 | 说明 | 示例 |\n|-----|------|-----|\n| `--tool` | 工具名称 | `--tool Bash` |\n| `--hook` | Hook 模式 | `--hook` |\n| `--fail-on-warn` | 警告时失败 | `--fail-on-warn` |\n| `--explain` | 显示决策证据 | `--explain` |\n| `--strict` | 严格模式 | `--strict` |\n| `--include-capsule` | 包含完整 Capsule | `--include-capsule` |\n| `--json` | JSON 输出格式 | `--json` |\n\n资料来源：[mcp-server/index.ts:40-55]()\n\n## 安全考虑\n\n### API 密钥保护\n\nHTTP API 的密钥比较使用时序安全比较，防止时序攻击：\n\n```typescript\ncrypto.timingSafeEqual(\n Buffer.from(providedKey),\n Buffer.from(expectedKey)\n);\n```\n\n资料来源：[mcp-server/index.ts:180-185]()\n\n### 非本地绑定限制\n\nAudrey 默认绑定到 `127.0.0.1`，拒绝在非本地地址启动而不设置 API Key：\n\n```typescript\nconst isLoopback = serveHost === '127.0.0.1' || serveHost === '::1';\nif (!isLoopback && !serveAuth && !serveAllowNoAuth) {\n // 拒绝启动并给出错误提示\n}\n```\n\n资料来源：[mcp-server/index.ts:195-205]()\n\n### 规则文件写入限制\n\n`audrey promote` 命令拒绝写入非工作目录的规则文件，防止提示注入攻击：\n\n```bash\nAUDREY_PROMOTE_ROOTS=/path/to/trusted:d:/trusted audrey promote --yes\n```\n\n资料来源：[CHANGELOG.md:28-30]()\n\n## 集成方式\n\n### Claude Code 集成\n\n```bash\nnpx audrey install --host claude-code\n```\n\n安装后会在 Claude Code 设置中添加 PreToolUse 钩子，自动执行 `audrey guard --hook --fail-on-warn`。\n\n### MCP 服务器模式\n\nAudrey 作为 MCP 服务器运行，支持 stdio 通信：\n\n```bash\nnpx audrey serve\n```\n\n服务器暴露 `/v1/preflight`、`/v1/validate` 等 REST 端点。\n\n### Python SDK 集成\n\n```python\nfrom audrey_memory import Audrey\n\nbrain = Audrey(base_url=\"http://127.0.0.1:7437\", agent=\"my-agent\")\n\n# 预检动作\nresult = brain.preflight(\n tool=\"Bash\",\n action=\"npm run deploy\"\n)\n\nif result.decision == \"block\":\n print(\"动作被阻止:\", result.evidence)\n```\n\n## 总结\n\nAudrey Guard 通过五层闭环机制为 AI Agent 提供可靠的安全防护：\n\n1. **预检层**: 动作执行前的多维度风险评估\n2. **反射层**: 历史经验转化为可执行规则\n3. **脱敏层**: 敏感数据的自动保护\n4. **验证层**: 执行结果的反馈收集\n5. **权重层**: 记忆权重的动态调整\n\n这种设计使 Agent 能够从历史错误中学习，在重复操作前获得警告，最终实现真正的\"记忆驱动的智能代理\"。\n\n---\n\n*本页面基于 Audrey 源码生成，最后更新对应仓库 commit: master 分支。*\n\n---\n\n\n\n## 数据存储\n\n### 相关页面\n\n相关主题：[系统架构](#page-system-architecture), [记忆模型](#page-memory-model)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/Evilander/Audrey/blob/main/README.md)\n- [src/impact.ts](https://github.com/Evilander/Audrey/blob/main/src/impact.ts)\n- [src/routes.ts](https://github.com/Evilander/Audrey/blob/main/src/routes.ts)\n- [src/capsule.ts](https://github.com/Evilander/Audrey/blob/main/src/capsule.ts)\n- [CHANGELOG.md](https://github.com/Evilander/Audrey/blob/main/CHANGELOG.md)\n- [python/README.md](https://github.com/Evilander/Audrey/blob/main/python/README.md)\n \n\n# 数据存储\n\nAudrey 的数据存储层是整个本地优先记忆防火墙的核心基础设施。它采用 SQLite 作为主数据库，结合 sqlite-vec 扩展实现向量检索功能，为 AI 代理提供持久化、可查询的记忆存储能力。\n\n## 存储架构概述\n\nAudrey 采用单文件本地数据库架构，所有记忆数据存储在 SQLite 数据库中，无需外部托管数据库服务。这种设计确保了：\n\n- **数据主权**：所有数据保留在本地文件系统\n- **零依赖**：不依赖 PostgreSQL、Redis 等外部服务\n- **便携性**：通过备份整个数据目录即可迁移整个记忆状态\n- **事务完整性**：SQLite 的 ACID 特性保证数据一致性\n\n资料来源：[README.md:1-30]()\n\n```mermaid\ngraph TD\n A[Audrey Server] --> B[SQLite 数据库]\n A --> C[sqlite-vec 向量索引]\n B --> D[episodic_memory 表]\n B --> E[semantic_memory 表]\n B --> F[procedural_memory 表]\n B --> G[memory_events 表]\n C --> H[向量嵌入存储]\n```\n\n## 数据库文件位置\n\n默认情况下，Audrey 将数据存储在 `$PWD/.audrey/audrey.db` 目录中，即当前工作目录下的隐藏文件夹内。通过环境变量可以自定义数据目录位置：\n\n| 环境变量 | 默认值 | 说明 |\n|---------|--------|------|\n| `AUDREY_DATA_DIR` | `$PWD/.audrey` | 数据库文件所在目录路径 |\n\n```bash\n# 示例：指定自定义数据目录\nAUDREY_DATA_DIR=/home/user/.audrey-staging npx audrey serve\n```\n\n资料来源：[README.md:环境变量部分]()\n\n## 数据库表结构\n\nAudrey 的记忆模型通过三个核心表实现，分别对应不同的记忆类型：\n\n### 情景记忆表 (episodic_memory)\n\n存储具体的观察结果、工具执行结果、用户偏好和会话事实。\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| id | TEXT | 主键，ULID 格式 |\n| content | TEXT | 记忆内容文本 |\n| embedding | BLOB | 向量嵌入数据 |\n| confidence | REAL | 置信度分数 (0-1) |\n| source | TEXT | 来源类型 (direct-observation, tool-result, user-feedback) |\n| tags | TEXT | 逗号分隔的标签列表 |\n| agent | TEXT | 关联的代理标识 |\n| state | TEXT | 状态 (active, decayed, challenged, disputed) |\n| created_at | TEXT | ISO 时间戳 |\n| last_used_at | TEXT | 上次使用时间 |\n| usage_count | INTEGER | 使用次数统计 |\n\n资料来源：[src/impact.ts:1-50]()\n\n### 语义记忆表 (semantic_memory)\n\n存储从重复证据中提取的巩固原则和规则。\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| id | TEXT | 主键 |\n| content | TEXT | 原则内容 |\n| embedding | BLOB | 向量嵌入 |\n| confidence | REAL | 置信度 |\n| evidence_count | INTEGER | 支持证据数量 |\n| challenged | INTEGER | 是否被质疑标记 |\n| created_at | TEXT | 创建时间 |\n\n### 程序记忆表 (procedural_memory)\n\n存储执行操作的已知方式、避免事项、重试策略和验证方法。\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| id | TEXT | 主键 |\n| content | TEXT | 程序步骤内容 |\n| embedding | BLOB | 向量嵌入 |\n| confidence | REAL | 置信度 |\n| trigger_conditions | TEXT | 触发条件表达式 |\n| created_at | TEXT | 创建时间 |\n\n### 记忆事件表 (memory_events)\n\n审计日志表，记录所有记忆相关的操作事件。\n\n```typescript\n// 事件类型包括:\n// - encode: 新记忆编码\n// - recall: 记忆检索\n// - feedback: 反馈更新\n// - consolidate: 记忆巩固\n// - decay: 记忆衰减\n// - promote: 记忆提升为规则\n// - forget: 记忆遗忘\n```\n\n资料来源：[src/capsule.ts:1-30]()\n\n## 向量检索配置\n\nAudrey 使用 sqlite-vec 扩展提供向量相似度搜索能力。向量检索支持两种模式：\n\n| 检索模式 | 说明 | 适用场景 |\n|----------|------|----------|\n| `hybrid` (默认) | 结合向量相似度和全文搜索的混合检索 | 平衡精度和召回率 |\n| `vector` | 仅使用向量相似度搜索 | 快速精确匹配，跳过 FTS |\n\n```typescript\n// 检索选项配置\ninterface RecallOptions {\n query: string; // 检索查询文本\n limit?: number; // 返回结果数量限制\n tags?: string[]; // 标签过滤\n sources?: string[]; // 来源类型过滤\n after?: string; // 时间范围起点 (ISO 格式)\n before?: string; // 时间范围终点\n scope?: 'shared' | 'agent'; // 共享记忆或代理专属记忆\n retrieval?: 'hybrid' | 'vector'; // 检索模式选择\n context?: Record; // 上下文参数\n mood?: RecallOptions['mood']; // 情感/优先级配置\n}\n```\n\n资料来源：[src/routes.ts:1-30]()\n\n## 数据库性能优化\n\n### PRAGMA 配置\n\nAudrey 对 SQLite 进行了性能调优配置：\n\n| PRAGMA 设置 | 说明 |\n|-------------|------|\n| `journal_mode = WAL` | 启用 WAL 模式，提高并发读写性能 |\n| `synchronous = NORMAL` | 平衡安全性和写入性能 |\n| `cache_size` | 增大缓存减少磁盘 IO |\n| `mmap_size` | 启用内存映射加速读取 |\n\n如需恢复默认配置：\n\n```bash\nAUDREY_PRAGMA_DEFAULTS=0 npx audrey serve\n```\n\n资料来源：[README.md:环境变量部分]()\n\n### 嵌入预热\n\n首次启动时，Audrey 会进行嵌入模型预热以加速后续操作：\n\n```\n冷启动首次编码: 525ms → 预热后: 28ms (约18.7倍提升)\n```\n\n| 环境变量 | 默认值 | 说明 |\n|---------|--------|------|\n| `AUDREY_DISABLE_WARMUP` | `0` | 设为 `1` 可跳过嵌入预热 |\n\n资料来源：[CHANGELOG.md:0.22.0 性能部分]()\n\n## 数据备份与恢复\n\n### 手动备份\n\n由于所有数据存储在单一数据库文件，备份非常简单：\n\n```bash\n# 停止服务后复制数据库目录\ncp -r .audrey .audrey.backup-$(date +%Y%m%d)\n```\n\n### 快照导出与恢复\n\nAudrey 支持生成和恢复记忆快照：\n\n```python\nfrom audrey_memory import Audrey\n\nbrain = Audrey(base_url=\"http://127.0.0.1:7437\", api_key=\"secret\")\n\n# 创建快照\nsnapshot = brain.snapshot()\n\n# 恢复到新的空存储\nrestore_target = Audrey(base_url=\"http://127.0.0.1:7437\", api_key=\"secret\")\nrestore_target.restore(snapshot)\nrestore_target.close()\n```\n\n**注意**：快照只能恢复到空的存储中。建议使用新的 `AUDREY_DATA_DIR` 目录作为恢复目标。\n\n资料来源：[python/README.md:1-50]()\n\n## 数据隔离与多租户\n\nAudrey 通过数据目录实现租户隔离：\n\n| 策略 | 配置方式 |\n|------|----------|\n| 按租户隔离 | 每个租户设置独立的 `AUDREY_DATA_DIR` |\n| 按环境隔离 | 开发/测试/生产使用不同数据目录 |\n| 按项目隔离 | 每个项目使用独立的数据目录 |\n\n```bash\n# 多实例运行示例\nAUDREY_DATA_DIR=/data/tenant-a audrey serve --port 7437 &\nAUDREY_DATA_DIR=/data/tenant-b audrey serve --port 7438 &\n```\n\n## 数据导入导出\n\n### 导出工具\n\n当启用管理工具时（`AUDREY_ENABLE_ADMIN_TOOLS=1`），可以通过 REST API 导出数据：\n\n| 端点 | 方法 | 说明 |\n|------|------|------|\n| `/v1/export` | POST | 导出所有记忆数据 |\n| `/v1/import` | POST | 导入记忆快照 |\n| `/v1/forget` | POST | 删除指定记忆 |\n\n```bash\n# 启用管理工具\nAUDREY_ENABLE_ADMIN_TOOLS=1 npx audrey serve\n\n# 导出数据\ncurl -X POST http://127.0.0.1:7437/v1/export \\\n -H \"Authorization: Bearer $AUDREY_API_KEY\"\n```\n\n资料来源：[README.md:环境变量部分]()\n\n## 生产环境建议\n\n| 建议项 | 说明 |\n|--------|------|\n| 定期备份 | 每次重大版本升级前备份 `AUDREY_DATA_DIR` |\n| 磁盘空间监控 | 监控数据库目录大小，避免磁盘满 |\n| 权限控制 | 确保数据库目录仅服务进程可读写 |\n| 升级前备份 | Provider 或维度变化前必须备份 |\n| 冷备份时机 | 备份时停止服务或使用只读快照 |\n\n```bash\n# 生产环境备份脚本示例\n#!/bin/bash\nAUDREY_DATA_DIR=\"${AUDREY_DATA_DIR:-.audrey}\"\nBACKUP_DIR=\"/backups/audrey\"\nTIMESTAMP=$(date +%Y%m%d_%H%M%S)\n\nmkdir -p \"$BACKUP_DIR\"\ncp -r \"$AUDREY_DATA_DIR\" \"$BACKUP_DIR/audrey-$TIMESTAMP\"\necho \"Backup completed: $BACKUP_DIR/audrey-$TIMESTAMP\"\n```\n\n资料来源：[README.md:Production Readiness 部分]()\n\n## 数据生命周期\n\n### 记忆巩固 (Consolidation)\n\nAudrey 通过定期运行 `dream` 命令执行记忆巩固：\n\n```bash\nnpx audrey dream\n```\n\n巩固过程包括：\n- 低置信度记忆衰减\n- 高频使用记忆强化\n- 矛盾记忆标记处理\n- 跨记忆类型关联更新\n\n### 记忆衰减 (Decay)\n\n置信度低于阈值的记忆会逐渐衰减，失去在检索中的优先级：\n\n| 衰减因素 | 说明 |\n|----------|------|\n| 时间衰减 | 长时间未使用的记忆置信度下降 |\n| 矛盾干扰 | 被新证据反驳的记忆进入 disputed 状态 |\n| 低使用率 | usage_count 过低的记忆逐渐淡化 |\n\n```typescript\n// 衰减配置 (half-life 机制)\ninterface ConfidenceConfig {\n halfLifeDays: number; // 置信度减半的天数\n decayThreshold: number; // 触发衰减的最小置信度\n boostOnUse: boolean; // 使用后是否提升置信度\n}\n```\n\n资料来源：[src/impact.ts:全文]()\n\n## 存储健康检查\n\n使用 CLI 检查存储状态：\n\n```bash\n# 基本状态检查\nnpx audrey status\n\n# JSON 格式输出\nnpx audrey status --json\n\n# 严格模式（不健康时退出码非零）\nnpx audrey status --json --fail-on-unhealthy\n```\n\n```json\n{\n \"status\": \"healthy\",\n \"database\": {\n \"path\": \".audrey/audrey.db\",\n \"size_bytes\": 1048576,\n \"episodic_count\": 150,\n \"semantic_count\": 23,\n \"procedural_count\": 8\n },\n \"vectorIndex\": {\n \"status\": \"ready\",\n \"dimension\": 768\n }\n}\n\n---\n\n\n\n## MCP集成\n\n### 相关页面\n\n相关主题：[Audrey Guard 安全循环](#page-audrey-guard), [REST API](#page-rest-api)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [mcp-server/index.ts](https://github.com/Evilander/Audrey/blob/main/mcp-server/index.ts)\n- [mcp-server/config.ts](https://github.com/Evilander/Audrey/blob/main/mcp-server/config.ts)\n- [src/routes.ts](https://github.com/Evilander/Audrey/blob/main/src/routes.ts)\n- [src/capsule.ts](https://github.com/Evilander/Audrey/blob/main/src/capsule.ts)\n- [src/redact.ts](https://github.com/Evilander/Audrey/blob/main/src/redact.ts)\n- [README.md](https://github.com/Evilander/Audrey/blob/main/README.md)\n \n\n# MCP集成\n\n## 概述\n\nAudrey通过Model Context Protocol (MCP)实现与各类AI代理（Codex、Claude Code、Claude Desktop、Cursor、Windsurf、VS Code、JetBrains、Ollama等）的本地优先记忆防火墙集成。MCP作为中间协议层，使Audrey能够以工具的形式嵌入到AI代理的工作流程中，在代理执行操作前进行记忆检查和决策过滤。\n\n核心工作流程为：代理请求操作 → Audrey Guard检查记忆层 → 返回`allow`（允许）、`warn`（警告）或`block`（阻止）决策及证据。\n\n资料来源：[README.md:1-20]()\n\n## 架构设计\n\n### 系统组件关系\n\n```mermaid\ngraph TD\n A[\"AI代理
(Claude Code/Cursor/Codex等)\"] -->|MCP协议| B[\"Audrey MCP Server
mcp-server/index.ts\"]\n B -->|stdio/STDIO通信| C[\"Audrey Core
内存管理层\"]\n C -->|SQLite存储| D[\"记忆存储
episodic/semantic/procedural\"]\n \n E[\"REST API
/v1/*\"] -->|HTTP调用| C\n \n F[\"CLI工具
audrey guard\"] -->|命令行接口| C\n \n B -->|工具调用| G[\"guard
记忆检查工具\"]\n B -->|工具调用| H[\"memory_encode
编码记忆\"]\n B -->|工具调用| I[\"memory_recall
检索记忆\"]\n B -->|工具调用| J[\"memory_feedback
反馈结果\"]\n```\n\n### MCP通信模式\n\nAudrey MCP Server支持两种通信模式，根据不同宿主环境选择：\n\n| 宿主类型 | 通信模式 | 配置格式 | 说明 |\n|---------|---------|---------|------|\n| Codex | stdio | TOML | 通过`command`和`args`直接启动进程 |\n| Claude Code | stdio | JSON | MCP原生JSON-RPC |\n| Claude Desktop | stdio | JSON | MCP原生JSON-RPC |\n| Cursor | stdio | JSON | MCP原生JSON-RPC |\n| Windsurf | stdio | JSON | MCP原生JSON-RPC |\n| VS Code | stdio | JSON | MCP原生JSON-RPC |\n| JetBrains | stdio | JSON | MCP原生JSON-RPC |\n| Ollama | stdio | JSON | 本地模型支持 |\n| Generic | stdio | JSON | 通用MCP宿主 |\n\n资料来源：[mcp-server/config.ts:1-50]()\n\n## MCP服务器启动\n\n### CLI参数解析\n\nMCP服务器通过命令行参数配置启动行为，支持以下选项：\n\n```mermaid\ngraph LR\n A[\"CLI Arguments\"] --> B{\"参数解析
parseArgs()\"}\n B --> C[\"--host=\"]\n B --> D[\"--dry-run\"]\n B --> D2[\"--include-secrets\"]\n \n C --> E[\"host变量
宿主标识\"]\n D --> F[\"dryRun标志\"]\n D2 --> G[\"includeSecrets标志\"]\n \n E --> H[\"返回对象
{host, dryRun, includeSecrets}\"]\n```\n\n参数处理逻辑（伪代码表示）：\n\n| 参数模式 | 示例 | 行为 |\n|---------|------|------|\n| `--host=` | `--host=claude-code` | 设置宿主标识 |\n| `--dry-run` | `audrey mcp --dry-run` | 预览配置不实际启动 |\n| `--include-secrets` | `audrey mcp --include-secrets` | 在环境变量中包含密钥 |\n| 无前缀值 | `audrey mcp claude-code` | 设置宿主标识 |\n\n资料来源：[mcp-server/index.ts:1-80]()\n\n### 子命令分发\n\n```mermaid\nstateDiagram-v2\n [*] --> HelpCheck\n HelpCheck --> VersionCheck: --help/-h/help\n HelpCheck --> [*]: 退出\n VersionCheck --> [*]: --version/-v/version\n VersionCheck --> [*]: 退出\n \n [*] --> SubcommandDispatch\n SubcommandDispatch --> install: subcommand='install'\n SubcommandDispatch --> uninstall: subcommand='uninstall'\n SubcommandDispatch --> mcp_config: subcommand='mcp-config'\n SubcommandDispatch --> hook_config: subcommand='hook-config'\n SubcommandDispatch --> demo: subcommand='demo'\n SubcommandDispatch --> reembed: subcommand='reembed'\n SubcommandDispatch --> dream: subcommand='dream'\n SubcommandDispatch --> MCP_Server: stdio_loop\n \n install --> [*]\n uninstall --> [*]\n mcp_config --> [*]\n hook_config --> [*]\n demo --> [*]\n reembed --> [*]\n dream --> [*]\n MCP_Server --> [*]\n```\n\n支持的子命令列表：\n\n| 子命令 | 功能描述 |\n|-------|---------|\n| `audrey install --host ` | 在指定宿主中注册Audrey |\n| `audrey uninstall` | 取消注册Audrey |\n| `audrey mcp-config` | 打印MCP配置文件 |\n| `audrey hook-config` | 打印/应用Hook配置 |\n| `audrey demo` | 运行演示命令 |\n| `audrey reembed` | 重新生成嵌入向量 |\n| `audrey dream` | 触发记忆整合 |\n| `audrey greeting` | 打印问候语 |\n\n资料来源：[mcp-server/index.ts:100-150]()\n\n## MCP工具接口\n\n### 工具注册与调用\n\nAudrey通过MCP暴露以下核心工具，AI代理可在执行操作前调用：\n\n| 工具名称 | 功能 | 返回类型 |\n|---------|------|---------|\n| `guard` | 记忆前置检查 | `GuardResult` |\n| `memory_encode` | 编码新记忆 | `EncodeResult` |\n| `memory_recall` | 检索相关记忆 | `RecallResult` |\n| `memory_feedback` | 记录反馈结果 | `FeedbackResult` |\n\n### Guard工具详解\n\nGuard是Audrey的核心工具，用于在代理执行操作前进行记忆检查：\n\n```mermaid\nsequenceDiagram\n participant Agent as AI代理\n participant MCP as Audrey MCP Server\n participant Core as Audrey Core\n participant DB as SQLite存储\n\n Agent->>MCP: guard(tool, action, context)\n MCP->>Core: beforeAction(options)\n Core->>DB: 查询相关记忆\n DB-->>Core: 记忆记录列表\n Core->>Core: 分析决策
allow/warn/block\n Core->>DB: 记录使用统计\n Core-->>MCP: GuardResult\n MCP-->>Agent: 决策+证据\n```\n\nGuard参数结构（`src/routes.ts`中定义）：\n\n```typescript\ninterface GuardParams {\n tool: string; // 工具名称\n action: string; // 操作描述\n cwd?: string; // 工作目录\n sessionId?: string; // 会话标识\n files?: string[]; // 相关文件列表\n json?: boolean; // JSON格式输出\n override?: boolean; // 覆盖配置\n failOnWarn?: boolean; // 警告时失败\n explain?: boolean; // 返回解释\n hook?: boolean; // Hook模式\n strict?: boolean; // 严格模式\n includeCapsule?: boolean; // 包含记忆胶囊\n}\n```\n\n资料来源：[mcp-server/index.ts:200-280]()\n资料来源：[src/routes.ts:1-60]()\n\n### Guard返回值结构\n\n| 字段 | 类型 | 说明 |\n|-----|------|------|\n| `decision` | `allow` \\| `warn` \\| `block` | 决策结果 |\n| `receipt_id` | `string` | 收据ID，用于后续反馈 |\n| `capsule` | `MemoryCapsule` | 检索到的相关记忆 |\n| `preflight` | `PreflightResult` | 前置检查结果 |\n| `confidence` | `number` | 置信度 (0-1) |\n| `evidence` | `Evidence[]` | 支持决策的证据 |\n\n### Memory Capsule结构\n\n记忆胶囊（Memory Capsule）将检索到的记忆分类组织，便于代理理解和使用：\n\n```mermaid\ngraph TD\n A[\"MemoryCapsule\"] --> B[\"sections: 各分区记忆\"]\n B --> C[\"must_follow
必须遵守的规则\"]\n B --> D[\"procedures
操作流程\"]\n B --> E[\"user_preferences
用户偏好\"]\n B --> F[\"risks
风险警告\"]\n B --> G[\"uncertain_or_disputed
不确定/争议\"]\n B --> H[\"recent_changes
近期变更\"]\n B --> I[\"project_facts
项目事实\"]\n```\n\n分区分配规则（`src/capsule.ts`）：\n\n| 记忆类型/标签 | 分配分区 | 条件 |\n|-------------|---------|------|\n| 高置信度直接观察/用户告知 | `must_follow` | 包含MUST_FOLLOW_TAGS |\n| 低置信度间接来源 | `uncertain_or_disputed` | 包含MUST_FOLLOW_TAGS但来源不可信 |\n| 包含RISK_TAGS | `risks` | 标签匹配 |\n| procedural类型或PROCEDURE_TAGS | `procedures` | 类型/标签匹配 |\n| PREFERENCE_TAGS或told-by-user | `user_preferences` | 标签/来源匹配 |\n| 状态为disputed/context_dependent | `uncertain_or_disputed` | 状态检查 |\n| 置信度 < 0.55 | `uncertain_or_disputed` | 阈值检查 |\n| 7天内创建 | `recent_changes` | 时间窗口 |\n\n资料来源：[src/capsule.ts:1-100]()\n\n## 配置生成\n\n### 宿主配置格式化\n\nMCP Server根据不同宿主类型生成对应格式的配置文件：\n\n```mermaid\ngraph LR\n A[\"宿主类型\"] --> B{\"formatMcpHostConfig()\"}\n B -->|codex| C[\"TOML格式
tomlString()\"]\n B -->|其他| D[\"JSON格式
JSON.stringify()\"]\n \n C --> E[\"[mcp_servers.audrey]
command = ...
args = [...]\"]\n D --> F[\"{\\\"mcpServers\\\": {...}}\"]\n```\n\n#### Codex配置格式（TOML）\n\n```\n[mcp_servers.audrey]\ncommand = \"/path/to/node\"\nargs = [\"/path/to/audrey\", \"mcp\"]\n\n[mcp_servers.audrey.env]\nAUDREY_DATA_DIR = \"/path/to/data\"\nAUDREY_EMBEDDING_PROVIDER = \"openai\"\n```\n\n#### 标准JSON配置格式\n\n```json\n{\n \"mcpServers\": {\n \"audrey\": {\n \"command\": \"node\",\n \"args\": [\"/path/to/mcp-server/index.ts\"],\n \"env\": {\n \"AUDREY_DATA_DIR\": \"/path/to/data\"\n }\n }\n }\n}\n```\n\n资料来源：[mcp-server/config.ts:10-60]()\n\n### 环境变量构建\n\n```typescript\nfunction buildAudreyMcpEnv(\n env: Record,\n agent: string,\n options: { includeSecrets?: boolean }\n): Record\n```\n\n| 环境变量 | 默认值 | 说明 |\n|---------|-------|------|\n| `AUDREY_DATA_DIR` | 自动 | 数据存储目录 |\n| `AUDREY_LLM_PROVIDER` | 推断 | LLM提供者 |\n| `AUDREY_EMBEDDING_PROVIDER` | 推断 | 嵌入提供者 |\n| `AUDREY_LLM_MODEL` | 推断 | LLM模型 |\n| `AUDREY_API_KEY` | 无 | API密钥（需设置includeSecrets） |\n\n资料来源：[mcp-server/config.ts:50-100]()\n\n## 安装与配置\n\n### 安装流程\n\n```mermaid\ngraph TD\n A[\"audrey install --host \"] --> B[\"buildInstallArgs()\"]\n B --> C[\"生成MCP安装参数\"]\n C --> D[\"mcp add -s user audrey -e KEY=VALUE -- node audrey mcp\"]\n D --> E[\"调用宿主MCP安装命令\"]\n E --> F{\"成功?\"}\n F -->|是| G[\"安装完成\"]\n F -->|否| H[\"错误处理\"]\n \n A2[\"--dry-run\"] --> I[\"仅预览配置
不实际安装\"]\n```\n\n### Claude Code安装步骤\n\n```bash\n# 1. 预览安装配置\nnpx audrey install --host claude-code --dry-run\n\n# 2. 实际注册Audrey MCP Server\nnpx audrey install --host claude-code\n\n# 3. 应用项目级Hook配置\nnpx audrey hook-config claude-code --apply --scope project\n\n# 4. 应用用户级Hook配置\nnpx audrey hook-config claude-code --apply --scope user\n\n# 5. 在Claude Code中验证Hook\n/hooks\n\n# 6. 验证MCP Server\nclaude mcp list\n```\n\n### Hook配置\n\nHook配置用于将Audrey集成到代理的请求-响应循环中：\n\n```typescript\ninterface HookConfigOptions {\n host: string;\n apply: boolean; // 是否应用配置\n dryRun: boolean; // 预览模式\n scope: 'project' | 'user'; // 配置作用域\n projectDir: string; // 项目目录\n settingsPath?: string; // 配置文件路径\n}\n```\n\n| 作用域 | 配置文件路径 |\n|-------|-------------|\n| `user` | `~/.claude/settings.json` |\n| `project` | `/.claude/settings.local.json` |\n\n资料来源：[mcp-server/index.ts:150-200]()\n\n## 安全与隐私\n\n### 数据脱敏\n\nAudrey MCP Server内置敏感信息检测和脱敏机制（`src/redact.ts`）：\n\n| 敏感类型 | 模式 | 替换值 |\n|---------|------|-------|\n| API密钥 | `/(api[_-]?key|apikey)[=:]\\s*['\"]?([^'\"\\s,]+)/gi` | `[REDACTED:api_key]` |\n| AWS密钥 | `/(aws[_-]?secret[_-]?access[_-]?key)[=:]\\s*['\"]?([^'\"\\s,]+)/gi` | `[REDACTED:aws_key]` |\n| Bearer令牌 | `/(bearer[_-]?token)[=:]\\s*['\"]?([^'\"\\s,]+)/gi` | `[REDACTED:bearer_token]` |\n| 密码赋值 | `/(password|passwd|pwd)[=:]\\s*['\"]?([^'\"\\s,]+)/gi` | `[REDACTED:password]` |\n| JWT | `/(jwt)[=:]\\s*['\"]?([^'\"\\s,]+)/gi` | `[REDACTED:jwt]` |\n| 会话Cookie | `/(session|sid)=[A-Za-z0-9%._-]{8,}/gi` | `[REDACTED:session]` |\n| S3签名 | `/([?&](?:X-Amz-Signature|sig)=)[^&\\s\"']+/gi` | `[REDACTED:signed_url_signature]` |\n| US SSN | `/\\b(?!000|666|9\\d{2})\\d{3}-(?!00)\\d{2}-(?!0000)\\d{4}\\b/g` | `[REDACTED:ssn]` |\n\n### HTTP API安全\n\n| 安全措施 | 说明 |\n|---------|------|\n| 绑定地址限制 | 默认为`127.0.0.1`，拒绝非localhost无API Key |\n| API Key比较 | 使用`crypto.timingSafeEqual`防止时序攻击 |\n| 选项白名单 | `sanitizeRecallOptions()`过滤不允许的HTTP Body参数 |\n| 管理员工具 | `AUDREY_ENABLE_ADMIN_TOOLS`默认禁用导出/导入/删除功能 |\n\n资料来源：[src/redact.ts:1-80]()\n资料来源：[README.md:环境变量部分]()\n\n## 诊断与调试\n\n### Doctor诊断命令\n\n```bash\nnpx audrey doctor [--json] [--override]\n```\n\n| 检查项 | 说明 |\n|-------|------|\n| `node-runtime` | Node.js版本 ≥ 20 |\n| `mcp-entrypoint` | MCP入口文件存在 |\n| `data-dir-writable` | 数据目录可写 |\n| `memory-store` | SQLite存储健康 |\n| `embedding-provider` | 嵌入提供者配置 |\n| `llm-provider` | LLM提供者配置 |\n| `host-config` | 宿主配置文件存在 |\n\n### 环境变量诊断\n\n| 环境变量 | 默认值 | 用途 |\n|---------|-------|------|\n| `AUDREY_DEBUG` | `0` | 打印MCP启动和预热日志 |\n| `AUDREY_PROFILE` | `0` | 启用诊断计时输出 |\n| `AUDREY_DISABLE_WARMUP` | `0` | 跳过嵌入向量预热 |\n| `AUDREY_ONNX_VERBOSE` | `0` | 显示ONNX运行时端点分配警告 |\n\n资料来源：[mcp-server/index.ts:doctor相关函数]()\n\n## 性能特性\n\n### 冷启动优化\n\n| 指标 | 优化前 | 优化后 | 提升倍数 |\n|-----|-------|-------|---------|\n| 编码响应时间 (p50) | 24.7ms | 15.2ms | ~1.6x |\n| 冷启动首次编码 | 525ms | 28ms | ~18.7x |\n| 混合检索 (p50) | 30.2ms | 14.3ms | ~2.1x |\n\n### 嵌入向量优化\n\n- 验证、干扰检测、情感共鸣共享主内容向量\n- 消除4次冗余嵌入调用中的3次\n- 可选`wait_for_consolidation`参数实现写后读语义\n\n资料来源：[CHANGELOG.md:0.22.0版本]()\n\n## 版本历史\n\n| 版本 | 发布日期 | 关键变更 |\n|-----|---------|---------|\n| 0.22.0 | 2026-04-28 | 性能优化，编码速度提升40%+，冷启动18.7x提升 |\n| 0.21.0 | 2026-04 | 添加`audrey doctor`诊断命令，host安装预览 |\n| 0.20.0 | 2026-03 | 记忆Preflight和Reflexes，MCP文档完善 |\n\n资料来源：[CHANGELOG.md:版本记录]()\n\n---\n\n\n\n## REST API\n\n### 相关页面\n\n相关主题：[MCP集成](#page-mcp-integration)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/routes.ts](https://github.com/Evilander/Audrey/blob/main/src/routes.ts)\n- [src/server.ts](https://github.com/Evilander/Audrey/blob/main/src/server.ts)\n- [README.md](https://github.com/Evilander/Audrey/blob/main/README.md)\n- [python/README.md](https://github.com/Evilander/Audrey/blob/main/python/README.md)\n- [src/audrey.ts](https://github.com/Evilander/Audrey/blob/main/src/audrey.ts)\n \n\n# REST API\n\nAudrey 提供了一个基于 Hono 框架构建的 REST API 服务端点，允许外部客户端（包括 Python SDK、命令行工具和其他 AI 代理）通过 HTTP 协议访问记忆功能。该 API 是 Audrey 作为本地优先记忆防火墙的核心通信接口。\n\n## 概述\n\nREST API 作为 Audrey 的远程通信层，默认监听 `http://127.0.0.1:7437`，提供健康检查、记忆编码、记忆召回、记忆胶囊获取以及管理工具等端点。资料来源：[README.md](https://github.com/Evilander/Audrey/blob/main/README.md)\n\n```mermaid\ngraph LR\n A[Python SDK] -->|HTTP 请求| B[REST API]\n C[CLI 工具] -->|HTTP 请求| B\n D[外部 Agent] -->|HTTP 请求| B\n B --> E[SQLite + sqlite-vec]\n B --> F[Embedding 服务]\n```\n\n## 核心端点\n\nAudrey REST API 遵循 `/health` 和 `/v1/*` 的路由模式，所有 API 端点都需要通过认证才能访问非本地环回地址。资料来源：[CHANGELOG.md](https://github.com/Evilander/Audrey/blob/main/CHANGELOG.md)\n\n### 健康检查\n\n| 端点 | 方法 | 说明 |\n|------|------|------|\n| `/health` | GET | 检查服务健康状态 |\n\n### 记忆操作\n\n| 端点 | 方法 | 说明 |\n|------|------|------|\n| `/v1/preflight` | POST | 执行行动前检查，返回 allow、warn 或 block 决策 |\n| `/v1/recall` | POST | 召回相关记忆上下文 |\n| `/v1/capsule` | POST | 获取回合大小的记忆数据包 |\n| `/v1/status` | GET | 获取当前记忆状态 |\n\n### 管理工具（需启用）\n\n当 `AUDREY_ENABLE_ADMIN_TOOLS=1` 时，以下端点可用：\n\n| 端点 | 方法 | 说明 |\n|------|------|------|\n| `/v1/export` | POST | 导出记忆快照 |\n| `/v1/import` | POST | 导入记忆快照 |\n| `/v1/forget` | POST | 遗忘特定记忆 |\n\n## 请求体结构\n\n所有 POST 端点使用统一的 `RouteBody` 类型定义，支持丰富的参数选项。资料来源：[src/routes.ts:1-50](https://github.com/Evilander/Audrey/blob/main/src/routes.ts)\n\n### 基础参数\n\n| 参数名 | 类型 | 说明 |\n|--------|------|------|\n| `action` | string | 执行的操作或命令 |\n| `query` | string | 查询字符串（action 的别名） |\n| `tool` | string | 工具名称（如 Bash、Write） |\n| `session_id` / `sessionId` | string | 会话标识符 |\n| `cwd` | string | 当前工作目录 |\n\n### 记忆召回参数\n\n| 参数名 | 类型 | 默认值 | 说明 |\n|--------|------|--------|------|\n| `limit` | number | - | 召回记忆数量限制 |\n| `budget_chars` / `budgetChars` | number | 4000 | 记忆胶囊字符预算 |\n| `include_capsule` / `includeCapsule` | boolean | false | 是否包含记忆胶囊 |\n| `include_status` / `includeStatus` | boolean | false | 是否包含状态信息 |\n| `include_preflight` / `includePreflight` | boolean | false | 是否包含预检结果 |\n\n### Preflight 参数\n\n| 参数名 | 类型 | 说明 |\n|--------|------|------|\n| `mode` | string | 预检模式 |\n| `failure_window_hours` | number | 失败窗口小时数 |\n| `recent_failure_window_hours` | number | 最近失败窗口小时数 |\n| `recent_change_window_hours` | number | 最近变更窗口小时数 |\n| `strict` | boolean | 是否启用严格模式 |\n| `record_event` / `recordEvent` | boolean | 是否记录事件 |\n\n### 事件反馈参数\n\n| 参数名 | 类型 | 说明 |\n|--------|------|------|\n| `receipt_id` / `receiptId` | string | 收据标识符 |\n| `input` | unknown | 输入数据 |\n| `output` | unknown | 输出数据 |\n| `outcome` | string | 结果（used/helpful/wrong） |\n| `error_summary` / `errorSummary` | string | 错误摘要 |\n| `evidence_feedback` | object | 证据反馈映射 |\n\n## 认证机制\n\n### API 密钥认证\n\n非环回地址的请求必须提供 Bearer 令牌认证：\n\n```\nAuthorization: Bearer \n```\n\nAPI 密钥通过环境变量 `AUDREY_API_KEY` 配置。资料来源：[CHANGELOG.md](https://github.com/Evilander/Audrey/blob/main/CHANGELOG.md)\n\n### 安全措施\n\n1. **时序安全比较**：HTTP API 密钥比较使用 `crypto.timingSafeEqual` 而非字符串 `!==`，防止前缀匹配时序泄露攻击。资料来源：[CHANGELOG.md](https://github.com/Evilander/Audrey/blob/main/CHANGELOG.md)\n\n2. **选项清理**：`/v1/recall` 和 `/v1/capsule` 不再将调用者选项直接传播到 `audrey.recall()`，新增的 `sanitizeRecallOptions()` 白名单函数会过滤不安全的参数，防止 `includePrivate: true` 等 ACL 绕过。资料来源：[CHANGELOG.md](https://github.com/Evilander/Audrey/blob/main/CHANGELOG.md)\n\n3. **绑定安全**：`audrey serve` 默认绑定 `127.0.0.1`（原为 `0.0.0.0`），非环回主机拒绝启动除非设置了 `AUDREY_API_KEY` 或明确设置 `AUDREY_ALLOW_NO_AUTH=1`。资料来源：[CHANGELOG.md](https://github.com/Evilander/Audrey/blob/main/CHANGELOG.md)\n\n## 环境变量配置\n\n| 变量名 | 默认值 | 说明 |\n|--------|--------|------|\n| `AUDREY_PORT` | `7437` | REST API 监听端口 |\n| `AUDREY_HOST` | `127.0.0.1` | REST API 绑定地址 |\n| `AUDREY_API_KEY` | unset | 非环回请求必需的 Bearer 令牌 |\n| `AUDREY_ALLOW_NO_AUTH` | `0` | 允许无认证的非环回绑定 |\n| `AUDREY_ENABLE_ADMIN_TOOLS` | `0` | 启用导出、导入和遗忘路由 |\n| `AUDREY_DEBUG` | `0` | 打印 MCP 信息日志 |\n| `AUDREY_PROFILE` | `0` | 通过 MCP `_meta.diagnostics` 发出每阶段计时 |\n\n## Python SDK 集成\n\nPython 客户端通过 HTTP 调用 REST API 实现所有功能。资料来源：[python/README.md](https://github.com/Evilander/Audrey/blob/main/python/README.md)\n\n### 同步客户端\n\n```python\nfrom audrey_memory import Audrey\n\nbrain = Audrey(\n base_url=\"http://127.0.0.1:7437\",\n api_key=\"secret\",\n agent=\"support-agent\",\n)\n\nmemory_id = brain.encode(\n \"Stripe returns HTTP 429 above 100 req/s\",\n source=\"direct-observation\",\n tags=[\"stripe\", \"rate-limit\"],\n)\n\nresults = brain.recall(\"stripe rate limits\", limit=5)\nsnapshot = brain.snapshot()\nbrain.close()\n```\n\n### 异步客户端\n\n```python\nimport asyncio\nfrom audrey_memory import AsyncAudrey\n\nasync def main() -> None:\n async with AsyncAudrey(base_url=\"http://127.0.0.1:7437\") as brain:\n await brain.health()\n await brain.encode(\"Deploy failed due to OOM\", source=\"direct-observation\")\n await brain.recall(\"deploy failure\", limit=3)\n\nasyncio.run(main())\n```\n\n### 关键修复\n\n- `DEFAULT_BASE_URL` 已从 `http://127.0.0.1:3487` 更正为 `http://127.0.0.1:7437`\n- `recall()` 和 `recall_response()` 现在能正确解码 `/v1/recall` 返回的裸露列表\n- `restore()` 现在将快照包装在 `{\"snapshot\": ...}` 中以匹配 `/v1/import` 处理器\n\n## 部署模式\n\n### 启动服务\n\n```bash\nnpx audrey serve\n```\n\n### Docker 部署\n\n支持通过 Docker 和 Compose 进行容器化部署，REST API 端点暴露在配置的端口上。\n\n## 数据流\n\n```mermaid\nsequenceDiagram\n participant Client as Python/CLI\n participant API as REST API\n participant Audrey as Core Engine\n participant Storage as SQLite+vec\n\n Client->>API: POST /v1/recall\n API->>API: sanitizeRecallOptions()\n API->>Audrey: recall()\n Audrey->>Storage: 混合检索查询\n Storage-->>Audrey: 相关记忆\n Audrey-->>API: 记忆结果\n API-->>Client: JSON 响应\n```\n\n## 状态报告\n\n`/v1/status` 端点返回详细的系统状态，包括：\n\n- 记忆统计（情景记忆、语义记忆、程序性记忆数量）\n- 数据库连接状态\n- 嵌入服务状态\n- LLM 提供商信息\n\n医生检查（Doctor Checks）会验证：\n\n- Node.js 运行时版本（需 >= 20）\n- 入口点文件存在性\n- 数据目录配置\n- 嵌入模型可用性\n- 服务绑定安全性\n\n当服务绑定到非环回地址但未配置 API 密钥时，系统会拒绝启动并提示安全风险。资料来源：[mcp-server/index.ts](https://github.com/Evilander/Audrey/blob/main/mcp-server/index.ts)\n\n## 错误处理\n\n### HTTP 状态码\n\n| 状态码 | 说明 |\n|--------|------|\n| 200 | 请求成功 |\n| 400 | 请求参数错误 |\n| 401 | 认证失败 |\n| 404 | 端点不存在 |\n| 500 | 服务器内部错误 |\n\n### 验证错误\n\n请求体中的参数经过验证，非法参数会被拒绝并返回详细的错误信息。资料来源：[src/routes.ts](https://github.com/Evilander/Audrey/blob/main/src/routes.ts)\n\n## 与 MCP 协议的关系\n\nREST API 与 MCP（Model Context Protocol）stdio 服务器共享相同的核心引擎，但通过不同的传输层暴露功能：\n\n| 特性 | MCP | REST API |\n|------|-----|----------|\n| 传输协议 | stdio | HTTP |\n| 主要用途 | 代理集成 | 外部客户端 |\n| 实时性 | 更高 | 标准 HTTP 延迟 |\n| 工具数量 | 20+ | 4+ |\n\n---\n\n\n\n## CLI工具\n\n### 相关页面\n\n相关主题：[Audrey Guard 安全循环](#page-audrey-guard), [快速开始](#page-quick-start)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/Evilander/Audrey/blob/main/README.md)\n- [mcp-server/index.ts](https://github.com/Evilander/Audrey/blob/main/mcp-server/index.ts)\n- [src/impact.ts](https://github.com/Evilander/Audrey/blob/main/src/impact.ts)\n- [src/routes.ts](https://github.com/Evilander/Audrey/blob/main/src/routes.ts)\n- [src/rules-compiler.ts](https://github.com/Evilander/Audrey/blob/main/src/rules-compiler.ts)\n- [src/capsule.ts](https://github.com/Evilander/Audrey/blob/main/src/capsule.ts)\n- [src/redact.ts](https://github.com/Evilander/Audrey/blob/main/src/redact.ts)\n- [CHANGELOG.md](https://github.com/Evilander/Audrey/blob/main/CHANGELOG.md)\n \n\n# CLI工具\n\nAudrey 提供了一套完整的命令行界面（CLI）工具，用于管理 AI 代理的记忆系统。通过 CLI，用户可以执行记忆检查、原则提升、影响分析、工具观察等核心操作。\n\n## 概述\n\nAudrey CLI 是与 Audrey 记忆系统交互的主要方式之一，支持多种子命令以满足不同的使用场景：\n\n- **guard** — 记忆驱动的动作预检，在执行危险操作前进行检查\n- **promote** — 将高置信度记忆提升为持久化规则文件\n- **impact** — 生成记忆系统的影响分析报告\n- **install** — 安装和配置 Audrey 与目标主机的集成\n- **doctor** — 诊断 Audrey 环境配置状态\n- **status** — 查看记忆系统当前状态\n- **dream** — 触发记忆巩固与整合过程\n- **reembed** — 重新生成向量嵌入\n- **hook-config** — 生成 Claude Code 钩子配置\n- **mcp-config** — 生成 MCP 服务器配置\n\n资料来源：[README.md](https://github.com/Evilander/Audrey/blob/main/README.md)\n\n## 命令详解\n\n### guard 命令\n\n`guard` 是 Audrey 的核心安全循环命令，用于在执行工具操作前进行记忆预检。\n\n```bash\naudrey guard --tool \"\" [options]\n```\n\n#### 参数说明\n\n| 参数 | 说明 | 类型 |\n|------|------|------|\n| `--tool` | 工具名称（如 `Bash`, `Write`） | 字符串 |\n| `--explain` | 显示决策依据 | 标志位 |\n| `--strict` | 严格模式，拒绝所有警告决策 | 标志位 |\n| `--hook` | 以钩子模式运行 | 标志位 |\n| `--json` | 输出 JSON 格式结果 | 标志位 |\n| `--fail-on-warn` | 遇到警告时返回失败 | 标志位 |\n| `--session-id` | 会话标识符 | 字符串 |\n| `--cwd` | 工作目录 | 字符串 |\n| `--include-capsule` | 在响应中包含记忆胶囊 | 标志位 |\n\n#### 返回值\n\n`guard` 命令返回三种决策结果：\n\n- **`allow`** — 允许执行，提供相关记忆上下文\n- **`warn`** — 警告执行，显示需要注意的记忆内容\n- **`block`** — 阻止执行，基于记忆中的风险标记\n\n资料来源：[mcp-server/index.ts:45-89](https://github.com/Evilander/Audrey/blob/main/mcp-server/index.ts)\n\n#### 执行流程图\n\n```mermaid\ngraph TD\n A[用户执行 guard 命令] --> B[解析工具名称和动作]\n B --> C[调用 beforeAction 预检]\n C --> D{决策结果}\n D -->|allow| E[显示上下文记忆]\n D -->|caution| F[显示警告和证据]\n D -->|block| G[阻止执行并显示原因]\n E --> H[返回允许状态]\n F --> I[根据配置决定是否阻止]\n G --> J[返回阻止状态]\n```\n\n### promote 命令\n\n`promote` 命令将高置信度的记忆提升为 Claude Code 可读取的规则文件（`.claude/rules/*.md`）。\n\n```bash\naudrey promote [--yes] [--dry-run] [--limit ]\n```\n\n#### 参数说明\n\n| 参数 | 说明 | 默认值 |\n|------|------|--------|\n| `--yes` | 跳过确认直接写入 | false |\n| `--dry-run` | 预览将要创建的文件 | false |\n| `--limit` | 最大提升数量 | 10 |\n\n#### 生成的文件格式\n\n提升后的规则文件包含 YAML 前置元数据：\n\n```yaml\n---\ntitle: Audrey semantic memory \nsource_memory_ids: []\nconfidence: 0.85\nevidence_count: 3\npromoted_at: 2025-01-15T10:30:00Z\n---\n```\n\n资料来源：[src/rules-compiler.ts:1-45](https://github.com/Evilander/Audrey/blob/main/src/rules-compiler.ts)\n\n### impact 命令\n\n`impact` 命令生成记忆系统的使用影响分析报告，帮助评估记忆系统的实际效果。\n\n```bash\naudrey impact [--window-days ] [--format ]\n```\n\n#### 报告内容\n\n| 指标 | 说明 |\n|------|------|\n| `episodic` | 情景记忆总数（来自直接观察） |\n| `semantic` | 语义记忆总数（经巩固的原则） |\n| `procedural` | 程序性记忆总数（操作步骤） |\n| `validatedTotal` | 经过验证的记忆总数 |\n| `topUsed` | 使用频率最高的记忆 |\n| `weakest` | 置信度最低的记忆 |\n| `recentActivity` | 最近的记忆活动 |\n\n#### 情绪指标\n\n报告包含基于近近期记忆的情绪分析：\n\n- **valence** — 情绪效价（积极/消极程度）\n- **arousal** — 唤醒度\n- **samples** — 用于分析的样本数量\n\n资料来源：[src/impact.ts:1-80](https://github.com/Evilander/Audrey/blob/main/src/impact.ts)\n\n### install 命令\n\n`install` 命令用于将 Audrey 与目标主机进行集成配置。\n\n```bash\naudrey install --host [--dry-run]\n```\n\n#### 支持的主机\n\n| 主机 | 说明 |\n|------|------|\n| `claude-code` | Claude Code 编辑器 |\n| 其他 | 通用 MCP 配置生成 |\n\n#### 安装流程\n\n```mermaid\ngraph TD\n A[运行 install 命令] --> B[检测主机类型]\n B --> C{主机类型}\n C -->|claude-code| D[生成 MCP 配置]\n C -->|其他| E[生成通用配置]\n D --> F[注册 Claude Code 钩子]\n E --> G[输出配置供手动添加]\n F --> H[验证安装]\n```\n\n资料来源：[mcp-server/index.ts:90-130](https://github.com/Evilander/Audrey/blob/main/mcp-server/index.ts)\n\n### hook-config 命令\n\n生成 Claude Code 的钩子配置文件。\n\n```bash\naudrey hook-config [--apply] [--scope ] [--project-dir ]\n```\n\n| 参数 | 说明 | 可选值 |\n|------|------|--------|\n| `--scope` | 钩子作用域 | `project`, `user` |\n| `--apply` | 直接应用配置 | - |\n| `--project-dir` | 项目目录路径 | 路径 |\n\n资料来源：[mcp-server/index.ts:150-200](https://github.com/Evilander/Audrey/blob/main/mcp-server/index.ts)\n\n### status 命令\n\n查看 Audrey 记忆系统的当前状态。\n\n```bash\naudrey status [--json]\n```\n\n#### 显示内容\n\n- **Mood** — 情绪指标（valence, arousal）\n- **Memory** — 各类记忆数量统计\n- **Principles** — 学习到的原则列表\n- **Identity** — 身份相关记忆\n- **Recent memories** — 最近创建的记忆\n- **Unresolved** — 未解决的矛盾线索\n\n### 其他命令\n\n| 命令 | 功能 |\n|------|------|\n| `doctor` | 诊断环境配置问题 |\n| `demo` | 运行演示模式 |\n| `mcp-config` | 打印 MCP 服务器配置 |\n| `dream` | 触发记忆巩固过程 |\n| `reembed` | 重新生成向量嵌入 |\n| `observe-tool` | 观察工具执行结果 |\n| `greeting` | 问候语生成 |\n\n## 环境变量配置\n\nCLI 行为可通过以下环境变量进行配置：\n\n| 变量 | 默认值 | 说明 |\n|------|--------|------|\n| `AUDREY_DATA_DIR` | `./audrey-data` | 数据存储目录 |\n| `AUDREY_PORT` | `7437` | REST API 端口 |\n| `AUDREY_HOST` | `127.0.0.1` | REST API 绑定地址 |\n| `AUDREY_API_KEY` | 未设置 | API 认证密钥 |\n| `AUDREY_ENABLE_ADMIN_TOOLS` | `0` | 启用导出/导入/遗忘工具 |\n| `AUDREY_DEBUG` | `0` | 调试日志输出 |\n| `AUDREY_PROFILE` | `0` | 性能分析 |\n| `AUDREY_DISABLE_WARMUP` | `0` | 跳过嵌入预热 |\n\n资料来源：[README.md](https://github.com/Evilander/Audrey/blob/main/README.md)\n\n## REST API 端点\n\nCLI 底层通过 Hono 服务器提供 REST API：\n\n| 端点 | 方法 | 功能 |\n|------|------|------|\n| `/health` | GET | 健康检查 |\n| `/v1/preflight` | POST | 动作预检（guard 功能） |\n| `/v1/recall` | POST | 记忆召回 |\n| `/v1/capsule` | POST | 获取记忆胶囊 |\n| `/v1/status` | GET | 系统状态 |\n\n资料来源：[src/routes.ts:1-50](https://github.com/Evilander/Audrey/blob/main/src/routes.ts)\n\n## 安全机制\n\n### API 密钥保护\n\n`audrey serve` 默认绑定到 `127.0.0.1`，非回环地址启动需要 `AUDREY_API_KEY`。HTTP API 使用 `crypto.timingSafeEqual` 进行密钥比较，防止时序攻击。\n\n### 写入路径限制\n\n`audrey promote --yes` 拒绝向 `process.cwd()` 之外写入 `.claude/rules/*.md`，除非目标路径在 `AUDREY_PROMOTE_ROOTS` 环境变量中明确指定。\n\n### 敏感信息脱敏\n\nCLI 内置数据脱敏功能，自动处理以下敏感字段：\n\n- 密码相关：`password`, `passwd`, `pwd`\n- 密钥相关：`api_key`, `secret`, `token`\n- 认证相关：`auth_token`, `bearer_token`, `jwt`\n- 云服务：`aws_secret`, `private_key`\n\n资料来源：[src/redact.ts:30-50](https://github.com/Evilander/Audrey/blob/main/src/redact.ts)\n\n## 使用示例\n\n### 动作预检\n\n```bash\n# 检查 Bash 命令\naudrey guard --tool Bash \"rm -rf node_modules\" --explain\n\n# JSON 格式输出\naudrey guard --tool Bash \"npm run deploy\" --json\n\n# 严格模式\naudrey guard --tool Write \"config.yaml\" --strict\n```\n\n### 提升记忆为规则\n\n```bash\n# 预览将要创建的规则\naudrey promote --dry-run\n\n# 确认并写入\naudrey promote --yes\n\n# 限制数量\naudrey promote --yes --limit 5\n```\n\n### 查看影响分析\n\n```bash\n# 默认 30 天窗口\naudrey impact\n\n# 指定窗口天数\naudrey impact --window-days 7\n\n# JSON 格式\naudrey impact --format json\n```\n\n## 版本变更\n\n| 版本 | 变更内容 |\n|------|----------|\n| 0.23.0 | 新增 `--include-capsule` 参数 |\n| 0.22.0 | 性能优化：编码时间提升 40% |\n| 0.21.0 | 新增 `usage_count` 和 `last_used_at` 追踪 |\n| 0.20.0 | CLI 表面新增 `--help`/`--version` 短路处理 |\n\n资料来源：[CHANGELOG.md](https://github.com/Evilander/Audrey/blob/main/CHANGELOG.md)\n\n---\n\n\n\n## JavaScript SDK\n\n### 相关页面\n\n相关主题：[系统架构](#page-system-architecture), [记忆模型](#page-memory-model)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/audrey.ts](https://github.com/Evilander/Audrey/blob/main/src/audrey.ts)\n- [src/index.ts](https://github.com/Evilander/Audrey/blob/main/src/index.ts)\n- [src/types.ts](https://github.com/Evilander/Audrey/blob/main/src/types.ts)\n- [mcp-server/index.ts](https://github.com/Evilander/Audrey/blob/main/mcp-server/index.ts)\n- [src/capsule.ts](https://github.com/Evilander/Audrey/blob/main/src/capsule.ts)\n- [src/reflexes.ts](https://github.com/Evilander/Audrey/blob/main/src/reflexes.ts)\n- [src/routes.ts](https://github.com/Evilander/Audrey/blob/main/src/routes.ts)\n \n\n# JavaScript SDK\n\nAudrey JavaScript SDK 是该项目的核心客户端库，提供与 Audrey 记忆运行时交互的完整 TypeScript 接口。SDK 支持同步和异步操作，可用于 Node.js 环境和 CLI 工具中。\n\n## 核心架构\n\n### 模块结构\n\n```\naudrey (SDK)\n├── Audrey # 主类，包含所有记忆操作\n├── AsyncAudrey # 异步版本\n├── AudreyError # 错误类型\n└── 类型导出 # 完整的 TypeScript 类型定义\n```\n\n### 主类概述\n\n`Audrey` 类是 SDK 的核心，封装了所有与本地记忆存储交互的功能。主要特性包括：\n\n- **记忆编码与检索**：支持三种记忆类型的写入和查询\n- **Preflight 检查**：动作执行前的记忆验证\n- **记忆胶囊构建**：上下文压缩与摘要生成\n- **因果链路管理**：记忆之间的因果关系追踪\n- **健康诊断**：运行时状态检查\n\n## 记忆类型系统\n\nAudrey 采用三层记忆架构，对应神经科学的不同记忆系统：\n\n| 记忆类型 | 用途 | 特征 | 典型场景 |\n|---------|------|------|---------|\n| **情景记忆 (episodic)** | 事件记录 | 时间戳驱动、一次性的经验 | \"上次执行 deploy 失败，报 OOM\" |\n| **语义记忆 (semantic)** | 知识存储 | 跨会话持久、基于重要性 | \"项目使用 yarn 而非 npm\" |\n| **程序记忆 (procedural)** | 流程规范 | 步骤化、可执行 | \"审查 PR 的流程是...\" |\n\n资料来源：[src/audrey.ts](https://github.com/Evilander/Audrey/blob/main/src/audrey.ts)\n\n## 核心 API\n\n### 记忆编码 (encode)\n\n将信息编码为记忆存入存储系统。\n\n```typescript\nconst memoryId = brain.encode(\n \"Stripe API 在超过 100 req/s 时返回 HTTP 429\",\n source=\"direct-observation\",\n tags=[\"stripe\", \"rate-limit\"]\n);\n```\n\n**参数说明**：\n\n| 参数 | 类型 | 必需 | 说明 |\n|-----|------|-----|------|\n| content | string | 是 | 记忆内容 |\n| source | string | 否 | 来源标识（默认值：`direct-observation`）|\n| tags | string[] | 否 | 标签数组 |\n| memoryType | 'episodic' \\\\| 'semantic' \\\\| 'procedural' | 否 | 记忆类型 |\n| wait_for_consolidation | boolean | 否 | 是否等待一致性确认 |\n\n### 记忆检索 (recall)\n\n根据查询字符串检索相关记忆。\n\n```typescript\nconst results = brain.recall(\"stripe rate limits\", limit=5);\n```\n\n**参数说明**：\n\n| 参数 | 类型 | 默认值 | 说明 |\n|-----|------|-------|------|\n| query | string | - | 检索查询 |\n| limit | number | 16 | 返回结果数量 |\n| scope | 'shared' \\\\| 'agent' | 'shared' | 检索范围 |\n| retrieval | 'hybrid' \\\\| 'vector' | 'hybrid' | 检索模式 |\n| mood | MoodOptions | - | 情感参数 |\n| context | Record | - | 额外上下文 |\n\n### 记忆快取 (snapshot/restore)\n\n支持记忆状态的导出与恢复。\n\n```typescript\n// 导出\nconst snapshot = brain.snapshot();\n\n// 恢复到空存储\nrestoreTarget.restore(snapshot);\n```\n\n资料来源：[python/README.md](https://github.com/Evilander/Audrey/blob/main/python/README.md)\n\n## Preflight 检查系统\n\nPreflight 是 Audrey 的核心安全机制，在动作执行前验证记忆状态。\n\n### 工作流程\n\n```mermaid\ngraph TD\n A[动作请求] --> B[构建 Preflight]\n B --> C{匹配记忆反射?}\n C -->|是| D[返回反射建议]\n C -->|否| E{匹配风险标签?}\n E -->|是| F[生成警告]\n E -->|否| G[检查近期失败]\n G --> H{发现失败记录?}\n H -->|是| I[标记为 caution]\n H -->|否| J[允许执行]\n D --> K[返回决策: allow/warn/block]\n F --> K\n I --> K\n J --> K\n```\n\n### 返回决策\n\n| 决策 | 含义 | 触发条件 |\n|-----|------|---------|\n| `allow` | 允许执行 | 无风险匹配 |\n| `warn` | 警告执行 | 存在低置信度风险 |\n| `block` | 阻止执行 | 高置信度风险或阻止级反射 |\n\n资料来源：[src/reflexes.ts](https://github.com/Evilander/Audrey/blob/main/src/reflexes.ts)\n资料来源：[src/preflight.ts](https://github.com/Evilander/Audrey/blob/main/src/preflight.ts)\n\n## 记忆胶囊 (Memory Capsule)\n\n记忆胶囊是上下文压缩机制，将检索到的记忆压缩为可嵌入 LLM 上下文的格式。\n\n### 胶囊结构\n\n```typescript\ninterface MemoryCapsule {\n sections: {\n must_follow: []; // 必须遵循的规则\n project_facts: []; // 项目事实\n user_preferences: []; // 用户偏好\n procedures: []; // 程序流程\n risks: []; // 风险警告\n contradictions: []; // 矛盾信息\n recent_changes: []; // 近期变更\n };\n mood: MoodState; // 情感状态\n health: HealthStatus; // 健康状态\n}\n```\n\n### 构建选项\n\n| 选项 | 类型 | 默认值 | 说明 |\n|-----|------|-------|------|\n| mode | 'conservative' \\\\| 'balanced' \\\\| 'aggressive' | 'balanced' | 压缩激进程度 |\n| budgetChars | number | 4000 | 上下文预算上限 |\n| recentChangeWindowHours | number | 24 | 近期变更时间窗口 |\n| includeRisks | boolean | true | 是否包含风险 |\n| includeContradictions | boolean | true | 是否包含矛盾信息 |\n\n资料来源：[src/capsule.ts](https://github.com/Evilander/Audrey/blob/main/src/capsule.ts)\n\n## 记忆反射 (Memory Reflexes)\n\n记忆反射是预定义的动作-响应模式，用于在 Preflight 阶段自动匹配。\n\n### 反射类型\n\n| 类型 | 响应方式 | 使用场景 |\n|-----|---------|---------|\n| `block` | 阻止执行 | 已知危险操作 |\n| `warn` | 发出警告 | 潜在风险操作 |\n| `guide` | 提供引导 | 建议性操作 |\n\n### 反射报告构建\n\n```typescript\nconst report = await buildReflexReport(audrey, \"npm run deploy\", {\n includeCapsule: true,\n includePreflight: true\n});\n```\n\n资料来源：[src/reflexes.ts](https://github.com/Evilander/Audrey/blob/main/src/reflexes.ts)\n\n## HTTP API 层\n\nSDK 底层通过 HTTP REST API 与本地服务通信。\n\n### 路由结构\n\n| 端点 | 方法 | 说明 |\n|-----|------|------|\n| `/health` | GET | 健康检查 |\n| `/v1/encode` | POST | 编码记忆 |\n| `/v1/recall` | POST | 检索记忆 |\n| `/v1/snapshot` | GET | 导出快照 |\n| `/v1/restore` | POST | 恢复快照 |\n| `/v1/guard` | POST | Preflight 检查 |\n\n### 参数清理\n\n`src/routes.ts` 中实现了严格的参数白名单机制：\n\n```typescript\nfunction sanitizeRecallOptions(opts: Record): RecallOptions {\n // 仅允许特定字段通过\n const allowedKeys = ['limit', 'tags', 'sources', 'after', 'before', \n 'context', 'mood', 'retrieval', 'scope'];\n // ...\n}\n```\n\n资料来源：[src/routes.ts](https://github.com/Evilander/Audrey/blob/main/src/routes.ts)\n\n## CLI 命令行接口\n\n### guard 命令\n\n在执行工具前运行记忆检查。\n\n```bash\naudrey guard --tool Bash \"npm run deploy\"\n```\n\n**参数说明**：\n\n| 参数 | 说明 |\n|-----|------|\n| `--tool ` | 工具名称 |\n| `--session-id ` | 会话标识 |\n| `--cwd ` | 工作目录 |\n| `--json` | JSON 输出格式 |\n| `--explain` | 显示详细解释 |\n| `--hook` | Hook 模式运行 |\n| `--strict` | 严格模式（block 决策时退出） |\n\n### hook-config 命令\n\n配置 Claude Code 等 IDE 的集成钩子。\n\n```bash\naudrey hook-config claude-code --apply --scope project\n```\n\n### doctor 命令\n\n诊断运行时健康状态。\n\n```bash\naudrey doctor [--verbose]\n```\n\n**检查项**：\n\n- Node.js 运行时版本（需 >= 20）\n- 数据目录存在性\n- MCP 入口点配置\n- LLM 提供商配置\n- Embedding 提供商配置\n\n资料来源：[mcp-server/index.ts](https://github.com/Evilander/Audrey/blob/main/mcp-server/index.ts)\n\n## 类型系统\n\n### 核心类型定义\n\n```typescript\n// 记忆条目\ninterface MemoryEntry {\n id: string;\n content: string;\n memory_type: 'episodic' | 'semantic' | 'procedural';\n created_at: string;\n updated_at?: string;\n salience?: number;\n tags?: string[];\n}\n\n// Preflight 结果\ninterface PreflightResult {\n decision: 'allow' | 'warn' | 'block';\n warnings: PreflightWarning[];\n reflexReport?: MemoryReflexReport;\n capsule?: MemoryCapsule;\n}\n\n// 检索选项\ninterface RecallOptions {\n limit?: number;\n tags?: string[];\n sources?: string[];\n after?: string;\n before?: string;\n context?: Record;\n mood?: MoodOptions;\n retrieval?: 'hybrid' | 'vector';\n scope?: 'shared' | 'agent';\n}\n```\n\n资料来源：[src/types.ts](https://github.com/Evilander/Audrey/blob/main/src/types.ts)\n\n## 错误处理\n\n### 错误类型\n\n| 错误类型 | 说明 |\n|---------|------|\n| `AudreyError` | 基础错误类型 |\n| 验证错误 | 参数校验失败 |\n| 存储错误 | 数据库操作失败 |\n| LLM 错误 | AI 提供商调用失败 |\n\n### 错误处理示例\n\n```typescript\ntry {\n await brain.recall(\"query\", { limit: -1 });\n} catch (error) {\n if (error instanceof AudreyError) {\n console.error(`SDK Error: ${error.message}`);\n }\n}\n```\n\n## 情感状态 (Mood)\n\nAudrey 支持情感状态追踪，用于调整检索和响应行为。\n\n```typescript\ninterface MoodState {\n valence: number; // -1.0 到 1.0，情感正负\n arousal: number; // 0.0 到 1.0，激活程度\n samples: number; // 采样数量\n}\n```\n\n## 信任评估 (Confidence)\n\n记忆具有置信度评分，影响检索权重和决策。\n\n### 衰减机制\n\n```typescript\nfunction recencyDecay(\n createdAt: Date,\n halfLifeDays: number = 30\n): number {\n // 基于时间的衰减计算\n}\n```\n\n**规则**：\n- `halfLifeDays <= 0` 时抛出 `RangeError`\n- 默认半衰期为 30 天\n- 置信度基于记忆年龄、验证次数、使用频率综合计算\n\n资料来源：[src/causal.ts](https://github.com/Evilander/Audrey/blob/main/src/causal.ts)\n\n## 因果链路 (Causal Links)\n\n记忆之间可以建立因果关系。\n\n```typescript\ninterface CausalLink {\n linkId: string;\n causeId: string;\n effectId: string;\n linkType: 'correlational' | 'causal' | 'counterfactual';\n mechanism: string;\n confidence: number;\n spurious: boolean;\n}\n```\n\n### LLM 驱动的因果推断\n\n系统使用 LLM 分析记忆对之间的关系，判断是否为因果链接：\n\n1. 构建因果分析 prompt\n2. LLM 返回 JSON 格式分析结果\n3. 验证响应格式完整性\n4. 创建或拒绝因果链路\n\n**格式要求**：\n- `spurious`: boolean\n- `mechanism`: string\n- `linkType`: string（可选）\n- `confidence`: number（必须为有限数值）\n\n## 数据安全\n\n### 敏感信息脱敏\n\n`src/redact.ts` 实现了多层脱敏机制：\n\n```typescript\nconst SENSITIVE_KEY_PATTERN = /(password|secret|api_key|token|...)/i;\n```\n\n**脱敏规则**：\n\n| 类别 | 检测方式 |\n|-----|---------|\n| API 密钥 | 键名模式匹配 |\n| 密码凭证 | 键名 + 值模式 |\n| Bearer Token | 值内容检测 |\n| JWT | 结构化检测 |\n| AWS 密钥 | 特定前缀匹配 |\n\n### JSON 递归遍历\n\n脱敏系统递归遍历 JSON 结构，对象、数组、字符串分别处理，保留原始数据结构。\n\n资料来源：[src/redact.ts](https://github.com/Evilander/Audrey/blob/main/src/redact.ts)\n\n## 配置与环境变量\n\n### 关键环境变量\n\n| 变量 | 说明 | 默认值 |\n|-----|------|-------|\n| `AUDREY_DATA_DIR` | 数据存储目录 | `~/.audrey` |\n| `AUDREY_LLM_PROVIDER` | LLM 提供商 | 自动检测 |\n| `AUDREY_EMBEDDING_PROVIDER` | Embedding 提供商 | `local` |\n| `AUDREY_API_KEY` | API 认证密钥 | - |\n| `AUDREY_ALLOW_NO_AUTH` | 允许无认证 | `false` |\n\n### 提供商支持\n\n**LLM 提供商**：\n- OpenAI\n- Anthropic\n- 本地 Ollama\n- 自定义端点\n\n**Embedding 提供商**：\n- `local`：本地 GPU 加速（默认）\n- 云端服务\n\n## 性能优化\n\n### 近期版本性能改进 (0.22.0)\n\n| 指标 | 改进幅度 |\n|-----|---------|\n| 编码响应时间 | 40% 提升 (24.7ms → 15.2ms) |\n| 冷启动首次编码 | 18.7x 加速 (525ms → 28ms) |\n| 混合检索 | 2.1x 加速 (30.2ms → 14.3ms) |\n\n### 优化策略\n\n1. **复用 Embedding**：验证、干扰检测、情感共鸣共享主内容向量\n2. **预热机制**：冷启动时执行预热，避免首次延迟\n3. **流式检索**：`recallStream` 支持流式响应\n\n资料来源：[CHANGELOG.md](https://github.com/Evilander/Audrey/blob/main/CHANGELOG.md)\n\n## 使用示例\n\n### 基础同步使用\n\n```typescript\nimport { Audrey } from 'audrey';\n\nconst brain = new Audrey({\n baseUrl: 'http://127.0.0.1:7437',\n apiKey: 'secret',\n agent: 'support-agent'\n});\n\n// 编码新记忆\nconst memoryId = brain.encode(\n \"Deploy 失败是因为 OOM\",\n source: \"direct-observation\",\n tags: [\"deploy\", \"error\"]\n);\n\n// 检索相关记忆\nconst results = brain.recall(\"deploy failure\", limit: 3);\n\n// 获取快照\nconst snapshot = brain.snapshot();\n\n// 关闭连接\nbrain.close();\n```\n\n### 异步使用\n\n```typescript\nimport { AsyncAudrey } from 'audrey';\n\nasync function main() {\n const brain = new AsyncAudrey({\n baseUrl: 'http://127.0.0.1:7437',\n apiKey: 'secret'\n });\n\n await brain.health();\n await brain.encode(\"Stripe 返回 HTTP 429\");\n \n brain.close();\n}\n```\n\n### Preflight 检查\n\n```typescript\nconst result = await brain.beforeAction({\n tool: 'Bash',\n action: 'npm run deploy',\n cwd: '/project',\n sessionId: 'session-123'\n});\n\nif (result.decision === 'block') {\n console.error('操作被阻止:', result.warnings);\n process.exit(1);\n}\n```\n\n## MCP 服务器集成\n\nAudrey 通过 MCP (Model Context Protocol) 与各种 AI 代理集成：\n\n```mermaid\ngraph LR\n A[Claude Code] -->|MCP| B[Audrey MCP Server]\n A[Cursor] -->|MCP| B\n A[Windsurf] -->|MCP| B\n B --> C[Local Audrey Service]\n C --> D[(SQLite DB)]\n```\n\n### 支持的 IDE/工具\n\n- Claude Code\n- Claude Desktop\n- Cursor\n- Windsurf\n- VS Code (通过扩展)\n- JetBrains IDEs\n- Ollama 后端代理\n- 自定义代理服务\n\n资料来源：[README.md](https://github.com/Evilander/Audrey/blob/main/README.md)\n\n## 版本历史关键变更\n\n### 0.23.0\n\n- 移除 `hybrid_strict` 检索模式（曾是 `hybrid` 的别名）\n- 新增 `closeAsync(timeoutMs?)` 方法\n- 新增 `sanitizeRecallOptions()` 参数白名单工具\n\n### 0.22.0\n\n- 新增 `wait_for_consolidation` 参数\n- 新增 `retrieval` 参数（`hybrid` / `vector`）\n- 性能大幅优化\n\n资料来源：[CHANGELOG.md](https://github.com/Evilander/Audrey/blob/main/CHANGELOG.md)\n\n---\n\n---\n\n## Doramagic 踩坑日志\n\n项目：Evilander/Audrey\n\n摘要：发现 14 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：安装坑 - 来源证据：Audrey 1.0.1 — honest GuardBench gate, Guard time decay, structured validate errors。\n\n## 1. 安装坑 · 来源证据：Audrey 1.0.1 — honest GuardBench gate, Guard time decay, structured validate errors\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Audrey 1.0.1 — honest GuardBench gate, Guard time decay, structured validate errors\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_135b992964ae468aa28f88ee639816d1 | https://github.com/Evilander/Audrey/releases/tag/v1.0.1 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。\n\n## 2. 安装坑 · 来源证据：Audrey Guard 0.23.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Audrey Guard 0.23.0\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_9c913c644e2c4c099ea01523623f080e | https://github.com/Evilander/Audrey/releases/tag/v0.23.0 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 3. 安装坑 · 来源证据：v0.16.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v0.16.0\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_a7c5c62d4f034e50ba2e9c36e0798882 | https://github.com/Evilander/Audrey/releases/tag/v0.16.0 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。\n\n## 4. 安装坑 · 来源证据：v0.16.1 — Windows MCP fix\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v0.16.1 — Windows MCP fix\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_c0141ccf0a3245ec8c8ba112af7948e0 | https://github.com/Evilander/Audrey/releases/tag/v0.16.1 | 来源讨论提到 windows 相关条件，需在安装/试用前复核。\n\n## 5. 安装坑 · 来源证据：v0.17.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v0.17.0\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_9617863b3f954035926b8670b5bbea29 | https://github.com/Evilander/Audrey/releases/tag/v0.17.0 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 6. 配置坑 · 可能修改宿主 AI 配置\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。\n- 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。\n- 建议检查：列出会写入的配置文件、目录和卸载/回滚步骤。\n- 防护动作：涉及宿主配置目录时必须给回滚路径，不能只给安装命令。\n- 证据：capability.host_targets | github_repo:1161444210 | https://github.com/Evilander/Audrey | host_targets=mcp_host, claude, claude_code\n\n## 7. 能力坑 · 能力判断依赖假设\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:1161444210 | https://github.com/Evilander/Audrey | README/documentation is current enough for a first validation pass.\n\n## 8. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | github_repo:1161444210 | https://github.com/Evilander/Audrey | last_activity_observed missing\n\n## 9. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作：下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | github_repo:1161444210 | https://github.com/Evilander/Audrey | no_demo; severity=medium\n\n## 10. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | github_repo:1161444210 | https://github.com/Evilander/Audrey | no_demo; severity=medium\n\n## 11. 安全/权限坑 · 来源证据：Audrey 1.0.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Audrey 1.0.0\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_d30d964956da40a2b5e26dc7404861f8 | https://github.com/Evilander/Audrey/releases/tag/v1.0.0 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 12. 安全/权限坑 · 来源证据：v0.22.2 — correctness pass + legitimate benchmarking\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v0.22.2 — correctness pass + legitimate benchmarking\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_f9c004c97d31437ebdc3699d6f1ba2f4 | https://github.com/Evilander/Audrey/releases/tag/v0.22.2 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 13. 维护坑 · 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:1161444210 | https://github.com/Evilander/Audrey | issue_or_pr_quality=unknown\n\n## 14. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | github_repo:1161444210 | https://github.com/Evilander/Audrey | release_recency=unknown\n\n\n",
"markdown_key": "audrey",
"pages": "draft",
"source_refs": [
{
"evidence_id": "github_repo:1161444210",
"kind": "repo",
"supports_claim_ids": [
"claim_identity",
"claim_distribution",
"claim_capability"
],
"url": "https://github.com/Evilander/Audrey"
},
{
"evidence_id": "art_08565dd035d847d3b742eed1801b7f8a",
"kind": "docs",
"supports_claim_ids": [
"claim_identity",
"claim_distribution",
"claim_capability"
],
"url": "https://github.com/Evilander/Audrey#readme"
}
],
"summary": "DeepWiki/Human Wiki 完整输出，末尾追加 Discovery Agent 踩坑日志。",
"title": "Audrey 说明书",
"toc": [
"https://github.com/Evilander/Audrey 项目说明书",
"目录",
"项目概述",
"核心定位",
"功能架构",
"记忆模型",
"REST API",
"部署模式",
"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": "82b0e9979680acf751b9e80f6f90f8c6ac74befb",
"repo_inspection_error": null,
"repo_inspection_files": [
"Dockerfile",
"package.json",
"README.md",
"docker-compose.yml",
"docs/PRODUCTION_BACKLOG.md",
"docs/MEMORY_BENCHMARKING.md",
"docs/AUDREY_PAPER_OUTLINE.md",
"docs/paper/06-implementation.md",
"docs/paper/browser-launch-plan.schema.json",
"docs/paper/00-master.md",
"docs/paper/publication-pack.json",
"docs/paper/03-problem-definition.md",
"docs/paper/claim-register.schema.json",
"docs/paper/publication-pack.schema.json",
"docs/paper/02-related-work.md",
"docs/paper/01-introduction.md",
"docs/paper/08-discussion-limitations.md",
"docs/paper/evidence-ledger.md",
"docs/paper/arxiv-source.schema.json",
"docs/paper/audrey-paper-v1.md",
"docs/paper/07-evaluation.md",
"docs/paper/claim-register.json",
"docs/paper/arxiv-compile-report.schema.json",
"docs/paper/04-design.md",
"docs/paper/browser-launch-results.json",
"docs/paper/browser-launch-results.schema.json",
"docs/paper/SUBMISSION_README.md",
"docs/paper/05-guardbench-spec.md",
"docs/paper/browser-launch-plan.json",
"docs/paper/paper-submission-bundle.schema.json",
"docs/paper/09-conclusion.md",
"docs/paper/appendix-a-demo-transcript.md",
"docs/superpowers/specs/2026-05-05-audrey-guard-controller-design.md",
"docs/superpowers/plans/2026-05-05-audrey-guard-controller-implementation.md",
"examples/healthcare-ops-demo.js",
"examples/fintech-ops-demo.js",
"examples/stripe-demo.js",
"examples/ollama-memory-agent.js",
"src/feedback.ts",
"src/events.ts"
],
"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": "# audrey - Doramagic AI Context Pack\n\n> 定位：安装前体验与判断资产。它帮助宿主 AI 有一个好的开始，但不代表已经安装、执行或验证目标项目。\n\n## 充分原则\n\n- **充分原则，不是压缩原则**：AI Context Pack 应该充分到让宿主 AI 在开工前理解项目价值、能力边界、使用入口、风险和证据来源；它可以分层组织，但不以最短摘要为目标。\n- **压缩策略**：只压缩噪声和重复内容，不压缩会影响判断和开工质量的上下文。\n\n## 给宿主 AI 的使用方式\n\n你正在读取 Doramagic 为 audrey 编译的 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- **AI 研究者或研究型 Agent 构建者**：README 明确围绕研究、实验或论文工作流展开。 证据：`README.md` Claim：`clm_0002` supported 0.86\n- **正在使用 Claude/Codex/Cursor/Gemini 等宿主 AI 的开发者**：README 或插件配置提到多个宿主 AI。 证据：`README.md` Claim：`clm_0003` supported 0.86\n\n## 它能做什么\n\n- **命令行启动或安装流程**（需要安装后验证）：项目文档中存在可执行命令，真实使用需要在本地或宿主环境中运行这些命令。 证据：`README.md` Claim：`clm_0001` supported 0.86\n\n## 怎么开始\n\n- `npx audrey doctor` 证据：`README.md` Claim：`clm_0004` supported 0.86, `clm_0019` supported 0.86\n- `npx audrey demo --scenario repeated-failure` 证据：`README.md` Claim：`clm_0005` supported 0.86\n- `npx audrey guard --tool Bash \"npm run deploy\"` 证据：`README.md` Claim：`clm_0006` supported 0.86\n- `npx audrey install --host codex --dry-run` 证据：`README.md` Claim：`clm_0007` supported 0.86\n- `npx audrey install --host claude-code --dry-run` 证据：`README.md` Claim：`clm_0008` supported 0.86\n- `npx audrey install --host generic --dry-run` 证据：`README.md` Claim：`clm_0009` supported 0.86\n- `npx audrey mcp-config codex` 证据：`README.md` Claim：`clm_0010` supported 0.86\n- `npx audrey mcp-config generic` 证据：`README.md` Claim：`clm_0011` supported 0.86\n- `npx audrey mcp-config vscode` 证据：`README.md` Claim：`clm_0012` supported 0.86\n- `npx audrey hook-config claude-code` 证据：`README.md` Claim：`clm_0013` supported 0.86\n\n## 继续前判断卡\n\n- **当前建议**：需要管理员/安全审批\n- **为什么**：继续前可能涉及密钥、账号、外部服务或敏感上下文，建议先经过管理员或安全审批。\n\n### 30 秒判断\n\n- **现在怎么做**：需要管理员/安全审批\n- **最小安全下一步**：先跑 Prompt Preview；若涉及凭证或企业环境，先审批再试装\n- **先别相信**：角色质量和任务匹配不能直接相信。\n- **继续会触碰**：角色选择偏差、命令执行、本地环境或项目文件\n\n### 现在可以相信\n\n- **适合人群线索：AI 研究者或研究型 Agent 构建者**（supported）：有 supported claim 或项目证据支撑，但仍不等于真实安装效果。 证据：`README.md` Claim：`clm_0002` supported 0.86\n- **适合人群线索：正在使用 Claude/Codex/Cursor/Gemini 等宿主 AI 的开发者**（supported）：有 supported claim 或项目证据支撑，但仍不等于真实安装效果。 证据：`README.md` Claim：`clm_0003` supported 0.86\n- **能力存在：命令行启动或安装流程**（supported）：可以相信项目包含这类能力线索；是否适合你的具体任务仍要试用或安装后验证。 证据：`README.md` Claim：`clm_0001` supported 0.86\n- **存在 Quick Start / 安装命令线索**（supported）：可以相信项目文档出现过启动或安装入口；不要因此直接在主力环境运行。 证据：`README.md` Claim：`clm_0004` supported 0.86, `clm_0019` 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 或账号凭证配置。 原因：如果真实安装需要凭证，应先使用测试凭证并经过权限/合规判断。 证据：`CHANGELOG.md`, `README.md`, `benchmarks/adapters/registry.json`, `docs/PRODUCTION_BACKLOG.md` 等\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_0028` inferred 0.45\n- **命令执行会修改本地环境**：安装命令可能写入用户主目录、宿主插件目录或项目配置。 处理方式：先在隔离环境或测试账号中运行。 证据：`README.md` Claim：`clm_0029` 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- 文件总数：220\n- 重要文件覆盖：40/220\n- 证据索引条目：80\n- 角色 / Skill 条目：25\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请基于 audrey 的 AI Context Pack，先问我 3 个必要问题，然后判断它是否适合我的任务。回答必须包含：适合谁、能做什么、不能做什么、是否值得安装、证据来自哪里。所有项目事实必须引用 evidence_refs、source_paths 或 claim_id。\n```\n\n### 安装前体验\n\n- 目标：让用户在安装前感受核心工作流，同时避免把预览包装成真实能力或营销承诺。\n- 预期输出：一段带边界标签的体验剧本、安装后验证清单和谨慎建议；不含真实运行承诺或强营销表述。\n\n```text\n请把 audrey 当作安装前体验资产，而不是已安装工具或真实运行环境。\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请基于 audrey 的 AI Context Pack，生成一段我可以粘贴给宿主 AI 的开工前指令。这段指令必须遵守 not_runtime=true，不能声称项目已经安装、运行或产生真实结果。\n```\n\n\n## 角色 / Skill 索引\n\n- 共索引 25 个角色 / Skill / 项目文档条目。\n\n- **Why Audrey Exists**（project_doc）：The local-first memory firewall for AI agents. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`README.md`\n- **Audrey Python SDK**（project_doc）：Typed Python client for the Audrey REST API. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`python/README.md`\n- **Contributing**（project_doc）：Audrey is a production-focused memory layer, so contributions should optimize for correctness, observability, and safe operations. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`CONTRIBUTING.md`\n- **Audrey Paper Outline**（project_doc）：Audrey Guard: Local-First Pre-Action Memory Control for Tool-Using Agents 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/AUDREY_PAPER_OUTLINE.md`\n- **Audrey Memory Benchmarking Strategy**（project_doc）：Audrey Memory Benchmarking Strategy 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/MEMORY_BENCHMARKING.md`\n- **Audrey Production Backlog**（project_doc）：Updated: 2026-05-13 after the Audrey 1.0 release-cut and paper-gate pass. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/PRODUCTION_BACKLOG.md`\n- **Agent Memory Should Control Tool Use: Audrey Guard and Pre-Action Memory Control**（project_doc）：Agent Memory Should Control Tool Use: Audrey Guard and Pre-Action Memory Control 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/paper/00-master.md`\n- **1. Introduction**（project_doc）：Tool-using agents fail in ways that ordinary chat-memory evaluation does not measure. They repeat broken shell commands after a previous run already exposed the error. They ignore project-specific setup rules that were learned in an earlier session. They lose the causal link between a failed action and the fix that made a later action safe. They treat degraded retrieval as complete memory and act anyway. In Audrey's… 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/paper/01-introduction.md`\n- **2. Related Work**（project_doc）：This section organizes prior work by the behavior each system optimizes. The point of comparison is not whether a system has memory. It is whether memory runs before tool use and produces an evidence-linked action decision. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/paper/02-related-work.md`\n- **3. Problem Definition: Pre-Action Memory Control**（project_doc）：3. Problem Definition: Pre-Action Memory Control 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/paper/03-problem-definition.md`\n- **4. Design: Audrey Guard as a Pre-Action Memory Controller**（project_doc）：4. Design: Audrey Guard as a Pre-Action Memory Controller 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/paper/04-design.md`\n- **5. GuardBench Specification**（project_doc）：GuardBench is a benchmark specification for pre-action memory control. It evaluates whether memory changes a future tool action before the tool is invoked, not only whether a system retrieves relevant text. The benchmark target is an agent-memory system that receives a proposed action and returns a decision, evidence, and an auditable rationale. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/paper/05-guardbench-spec.md`\n- **6. Implementation**（project_doc）：Audrey is implemented as a local-first Node and TypeScript runtime with SQLite storage, vector and full-text indexes, MCP stdio tools, a REST sidecar, a Python client, a CLI, and release gates. The implementation is small enough to inspect directly, which is why this paper treats source-linked evidence as part of the artifact. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/paper/06-implementation.md`\n- **7. Evaluation**（project_doc）：This Stage-A evaluation reports implemented Audrey artifacts and local GuardBench adapters only. Section 5 specifies GuardBench as a reproducibility contract for pre-action memory control. The empirical claims below come from the repository's existing performance snapshot, the current behavioral regression output, the local comparative GuardBench runner, source-linked implementation inspection, and a freshly capture… 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/paper/07-evaluation.md`\n- **8. Discussion and Limitations**（project_doc）：Repeated-failure prevention is the clearest implemented behavior. The demo records one failed npm run deploy , stores the operational lesson that Prisma generation must run first, and blocks the identical future action before tool use. The guard output includes a BLOCKED decision, risk score 0.90 , two blocking reflexes, one warning reflex, evidence IDs, concrete recommendations, and impact accounting Ledger: E25, E… 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/paper/08-discussion-limitations.md`\n- **9. Conclusion**（project_doc）：Agent memory should be judged by whether it changes future tool actions. Audrey implements that claim for local agents through a host-side memory controller that runs before tool use and returns an auditable allow , warn , or block decision with evidence. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/paper/09-conclusion.md`\n- **Submission README**（project_doc）：- Nine drafted body sections in 01-introduction.md through 09-conclusion.md . - Consolidated Markdown master: audrey-paper-v1.md . - Evidence ledger with 97 rows: evidence-ledger.md . - Machine-readable claim register: claim-register.json . - Machine-readable publication pack: publication-pack.json . - Machine-readable browser launch plan: browser-launch-plan.json . - Machine-readable browser launch results ledger:… 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/paper/SUBMISSION_README.md`\n- **Appendix A. Repeated-Failure Demo Transcript**（project_doc）：Appendix A. Repeated-Failure Demo Transcript 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/paper/appendix-a-demo-transcript.md`\n- **Agent Memory Should Control Tool Use: Audrey Guard and Pre-Action Memory Control**（project_doc）：Agent Memory Should Control Tool Use: Audrey Guard and Pre-Action Memory Control 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/paper/audrey-paper-v1.md`\n- **Audrey Paper Evidence Ledger**（project_doc）：Every implementation claim in the paper should point to one or more ledger IDs in this file. Use the JSON snapshot as the canonical benchmark source for paper numbers; the README sample table is tracked as a follow-up below. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/paper/evidence-ledger.md`\n- **Audrey Guard Controller Implementation Plan**（project_doc）：Audrey Guard Controller Implementation Plan 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/superpowers/plans/2026-05-05-audrey-guard-controller-implementation.md`\n- **Audrey Guard Controller Design**（project_doc）：Date: 2026-05-05 Status: draft for user review Target release: v0.23 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/superpowers/specs/2026-05-05-audrey-guard-controller-design.md`\n- **Summary**（project_doc）：Describe the problem this PR fixes and the user-facing or operator-facing outcome. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`.github/pull_request_template.md`\n- **Changelog**（project_doc）：- GuardBench pass gate rewritten. The passed check no longer requires Audrey-specific lineage substrings \"failed before\" , \"recall:\" , \"must-follow\" , etc. in the subject's summary . A scenario passes when the decision matches the expected verdict, no seeded secrets leak, and for block / warn scenarios the subject returns at least one evidence id. The prior phrase-substring gate was structurally biased toward Audrey… 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`CHANGELOG.md`\n- **Security Policy**（project_doc）：Security fixes are best-effort for the current published release line and the current default branch. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`SECURITY.md`\n\n## 证据索引\n\n- 共索引 80 条证据。\n\n- **Why Audrey Exists**（documentation）：The local-first memory firewall for AI agents. 证据：`README.md`\n- **Audrey Python SDK**（documentation）：Typed Python client for the Audrey REST API. 证据：`python/README.md`\n- **Package**（package_manifest）：{ \"name\": \"audrey\", \"version\": \"1.0.1\", \"description\": \"Local-first memory runtime for AI agents with recall, consolidation, memory reflexes, contradiction detection, and tool-trace learning\", \"type\": \"module\", \"main\": \"dist/src/index.js\", \"types\": \"dist/src/index.d.ts\", \"exports\": { \".\": { \"types\": \"./dist/src/index.d.ts\", \"default\": \"./dist/src/index.js\" }, \"./mcp\": { \"types\": \"./dist/mcp-server/index.d.ts\", \"default\": \"./dist/mcp-server/index.js\" }, \"./server\": { \"types\": \"./dist/src/server.d.ts\", \"default\": \"./dist/src/server.js\" } }, \"bin\": { \"audrey\": \"dist/mcp-server/index.js\", \"audrey-mcp\": \"dist/mcp-server/index.js\" }, \"files\": \"dist/\", \"benchmarks/ .js\", \"benchmarks/ .mjs\", \"bench… 证据：`package.json`\n- **Contributing**（documentation）：Audrey is a production-focused memory layer, so contributions should optimize for correctness, observability, and safe operations. 证据：`CONTRIBUTING.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- **Audrey Paper Outline**（documentation）：Audrey Guard: Local-First Pre-Action Memory Control for Tool-Using Agents 证据：`docs/AUDREY_PAPER_OUTLINE.md`\n- **Audrey Memory Benchmarking Strategy**（documentation）：Audrey Memory Benchmarking Strategy 证据：`docs/MEMORY_BENCHMARKING.md`\n- **Audrey Production Backlog**（documentation）：Updated: 2026-05-13 after the Audrey 1.0 release-cut and paper-gate pass. 证据：`docs/PRODUCTION_BACKLOG.md`\n- **Agent Memory Should Control Tool Use: Audrey Guard and Pre-Action Memory Control**（documentation）：Agent Memory Should Control Tool Use: Audrey Guard and Pre-Action Memory Control 证据：`docs/paper/00-master.md`\n- **1. Introduction**（documentation）：Tool-using agents fail in ways that ordinary chat-memory evaluation does not measure. They repeat broken shell commands after a previous run already exposed the error. They ignore project-specific setup rules that were learned in an earlier session. They lose the causal link between a failed action and the fix that made a later action safe. They treat degraded retrieval as complete memory and act anyway. In Audrey's repeated-failure demo, an agent first runs npm run deploy and fails because the Prisma client was not generated. Audrey records the failed tool event, stores the operational rule, and blocks the same action when it is proposed again. The transcript ends with the intended behavio… 证据：`docs/paper/01-introduction.md`\n- **2. Related Work**（documentation）：This section organizes prior work by the behavior each system optimizes. The point of comparison is not whether a system has memory. It is whether memory runs before tool use and produces an evidence-linked action decision. 证据：`docs/paper/02-related-work.md`\n- **3. Problem Definition: Pre-Action Memory Control**（documentation）：3. Problem Definition: Pre-Action Memory Control 证据：`docs/paper/03-problem-definition.md`\n- **4. Design: Audrey Guard as a Pre-Action Memory Controller**（documentation）：4. Design: Audrey Guard as a Pre-Action Memory Controller 证据：`docs/paper/04-design.md`\n- **5. GuardBench Specification**（documentation）：GuardBench is a benchmark specification for pre-action memory control. It evaluates whether memory changes a future tool action before the tool is invoked, not only whether a system retrieves relevant text. The benchmark target is an agent-memory system that receives a proposed action and returns a decision, evidence, and an auditable rationale. 证据：`docs/paper/05-guardbench-spec.md`\n- **6. Implementation**（documentation）：Audrey is implemented as a local-first Node and TypeScript runtime with SQLite storage, vector and full-text indexes, MCP stdio tools, a REST sidecar, a Python client, a CLI, and release gates. The implementation is small enough to inspect directly, which is why this paper treats source-linked evidence as part of the artifact. 证据：`docs/paper/06-implementation.md`\n- **7. Evaluation**（documentation）：This Stage-A evaluation reports implemented Audrey artifacts and local GuardBench adapters only. Section 5 specifies GuardBench as a reproducibility contract for pre-action memory control. The empirical claims below come from the repository's existing performance snapshot, the current behavioral regression output, the local comparative GuardBench runner, source-linked implementation inspection, and a freshly captured repeated-failure demo transcript. 证据：`docs/paper/07-evaluation.md`\n- **8. Discussion and Limitations**（documentation）：Repeated-failure prevention is the clearest implemented behavior. The demo records one failed npm run deploy , stores the operational lesson that Prisma generation must run first, and blocks the identical future action before tool use. The guard output includes a BLOCKED decision, risk score 0.90 , two blocking reflexes, one warning reflex, evidence IDs, concrete recommendations, and impact accounting Ledger: E25, E42 . The change is not better recall in a chat answer. The change is that the second tool call does not happen. 证据：`docs/paper/08-discussion-limitations.md`\n- **9. Conclusion**（documentation）：Agent memory should be judged by whether it changes future tool actions. Audrey implements that claim for local agents through a host-side memory controller that runs before tool use and returns an auditable allow , warn , or block decision with evidence. 证据：`docs/paper/09-conclusion.md`\n- **Submission README**（documentation）：- Nine drafted body sections in 01-introduction.md through 09-conclusion.md . - Consolidated Markdown master: audrey-paper-v1.md . - Evidence ledger with 97 rows: evidence-ledger.md . - Machine-readable claim register: claim-register.json . - Machine-readable publication pack: publication-pack.json . - Machine-readable browser launch plan: browser-launch-plan.json . - Machine-readable browser launch results ledger: browser-launch-results.json . - Machine-readable arXiv source package: docs/paper/output/arxiv/ . - Machine-readable arXiv compile report: docs/paper/output/arxiv-compile-report.json . - Compiled arXiv PDF and compile log: docs/paper/output/arxiv-compile/main.pdf , docs/paper/out… 证据：`docs/paper/SUBMISSION_README.md`\n- **Appendix A. Repeated-Failure Demo Transcript**（documentation）：Appendix A. Repeated-Failure Demo Transcript 证据：`docs/paper/appendix-a-demo-transcript.md`\n- **Agent Memory Should Control Tool Use: Audrey Guard and Pre-Action Memory Control**（documentation）：Agent Memory Should Control Tool Use: Audrey Guard and Pre-Action Memory Control 证据：`docs/paper/audrey-paper-v1.md`\n- **Audrey Paper Evidence Ledger**（documentation）：Every implementation claim in the paper should point to one or more ledger IDs in this file. Use the JSON snapshot as the canonical benchmark source for paper numbers; the README sample table is tracked as a follow-up below. 证据：`docs/paper/evidence-ledger.md`\n- **Audrey Guard Controller Implementation Plan**（documentation）：Audrey Guard Controller Implementation Plan 证据：`docs/superpowers/plans/2026-05-05-audrey-guard-controller-implementation.md`\n- **Audrey Guard Controller Design**（documentation）：Date: 2026-05-05 Status: draft for user review Target release: v0.23 证据：`docs/superpowers/specs/2026-05-05-audrey-guard-controller-design.md`\n- **Summary**（documentation）：Describe the problem this PR fixes and the user-facing or operator-facing outcome. 证据：`.github/pull_request_template.md`\n- **Changelog**（documentation）：- GuardBench pass gate rewritten. The passed check no longer requires Audrey-specific lineage substrings \"failed before\" , \"recall:\" , \"must-follow\" , etc. in the subject's summary . A scenario passes when the decision matches the expected verdict, no seeded secrets leak, and for block / warn scenarios the subject returns at least one evidence id. The prior phrase-substring gate was structurally biased toward Audrey because only its controller emitted those exact tokens; baselines or external adapters that produced semantically correct decisions could still fail the gate on phrasing alone. The Audrey-style lineage match is preserved as a separate lineageTextMatched field per row and lineage… 证据：`CHANGELOG.md`\n- **Security Policy**（documentation）：Security fixes are best-effort for the current published release line and the current default branch. 证据：`SECURITY.md`\n- **Tsconfig**（structured_config）：{ \"compilerOptions\": { \"target\": \"ES2022\", \"module\": \"Node16\", \"moduleResolution\": \"Node16\", \"lib\": \"ES2022\" , \"outDir\": \"./dist\", \"rootDir\": \".\", \"declaration\": true, \"declarationMap\": true, \"sourceMap\": true, \"strict\": true, \"esModuleInterop\": true, \"skipLibCheck\": true, \"forceConsistentCasingInFileNames\": true, \"resolveJsonModule\": true, \"isolatedModules\": true, \"noUncheckedIndexedAccess\": true, \"noUnusedLocals\": false, \"noUnusedParameters\": false }, \"include\": \"src/ / .ts\", \"mcp-server/ / .ts\" , \"exclude\": \"node modules\", \"dist\", \"tests\", \"benchmarks\", \"examples\" } 证据：`tsconfig.json`\n- **Registry**（structured_config）：{ \"schemaVersion\": \"1.0.0\", \"suite\": \"GuardBench adapter registry\", \"adapters\": { \"id\": \"example-allow\", \"name\": \"Example Allow Adapter\", \"path\": \"benchmarks/adapters/example-allow.mjs\", \"status\": \"reference\", \"credentialMode\": \"none\", \"requiredEnv\": , \"description\": \"Credential-free reference adapter for validating module loading, self-test generation, and report validation.\", \"commands\": { \"moduleValidate\": \"npm run bench:guard:adapter-module:validate -- --adapter benchmarks/adapters/example-allow.mjs\", \"selfTest\": \"npm run bench:guard:adapter-self-test -- --adapter benchmarks/adapters/example-allow.mjs\", \"selfTestValidate\": \"npm run bench:guard:adapter-self-test:validate -- --report benc… 证据：`benchmarks/adapters/registry.json`\n- **Guardbench Adapter Registry.Schema**（structured_config）：{ \"$schema\": \"https://json-schema.org/draft/2020-12/schema\", \"$id\": \"https://audrey-memory.org/schemas/guardbench-adapter-registry.schema.json\", \"title\": \"GuardBench Adapter Registry\", \"type\": \"object\", \"additionalProperties\": false, \"required\": \"schemaVersion\", \"suite\", \"adapters\" , \"properties\": { \"schemaVersion\": { \"const\": \"1.0.0\" }, \"suite\": { \"const\": \"GuardBench adapter registry\" }, \"adapters\": { \"type\": \"array\", \"minItems\": 1, \"items\": { \"$ref\": \" /$defs/adapter\" } } }, \"$defs\": { \"adapter\": { \"type\": \"object\", \"additionalProperties\": false, \"required\": \"id\", \"name\", \"path\", \"status\", \"credentialMode\", \"requiredEnv\", \"description\", \"commands\" , \"properties\": { \"id\": { \"type\": \"strin… 证据：`benchmarks/schemas/guardbench-adapter-registry.schema.json`\n- **Guardbench Adapter Self Test.Schema**（structured_config）：{ \"$schema\": \"https://json-schema.org/draft/2020-12/schema\", \"$id\": \"https://audrey-memory.org/schemas/guardbench-adapter-self-test.schema.json\", \"title\": \"GuardBench Adapter Self-Test\", \"type\": \"object\", \"additionalProperties\": false, \"required\": \"schemaVersion\", \"suite\", \"generatedAt\", \"ok\", \"adapter\", \"conformance\", \"score\", \"contract\", \"failures\" , \"properties\": { \"schemaVersion\": { \"const\": \"1.0.0\" }, \"suite\": { \"const\": \"GuardBench adapter self-test\" }, \"generatedAt\": { \"type\": \"string\", \"minLength\": 1 }, \"ok\": { \"type\": \"boolean\" }, \"adapter\": { \"$ref\": \" /$defs/adapter\" }, \"conformance\": { \"$ref\": \" /$defs/conformance\" }, \"score\": { \"$ref\": \" /$defs/score\" }, \"contract\": { \"$ref\": \"… 证据：`benchmarks/schemas/guardbench-adapter-self-test.schema.json`\n- **Guardbench Conformance Card.Schema**（structured_config）：{ \"$schema\": \"https://json-schema.org/draft/2020-12/schema\", \"$id\": \"https://audrey-memory.org/schemas/guardbench-conformance-card.schema.json\", \"title\": \"GuardBench Conformance Card\", \"type\": \"object\", \"additionalProperties\": false, \"required\": \"schemaVersion\", \"suite\", \"generatedAt\", \"sourceDir\", \"manifestVersion\", \"suiteId\", \"subject\", \"run\", \"score\", \"conformance\", \"integrity\", \"provenance\" , \"properties\": { \"schemaVersion\": { \"const\": \"1.0.0\" }, \"suite\": { \"const\": \"GuardBench conformance card\" }, \"generatedAt\": { \"type\": \"string\", \"minLength\": 1 }, \"sourceDir\": { \"type\": \"string\", \"minLength\": 1 }, \"manifestVersion\": { \"type\": \"string\", \"minLength\": 1 }, \"suiteId\": { \"type\": \"string\",… 证据：`benchmarks/schemas/guardbench-conformance-card.schema.json`\n- **Guardbench External Dry Run.Schema**（structured_config）：{ \"$schema\": \"https://json-schema.org/draft/2020-12/schema\", \"$id\": \"https://audrey-memory.org/schemas/guardbench-external-dry-run.schema.json\", \"title\": \"GuardBench External Adapter Dry-Run Matrix\", \"type\": \"object\", \"additionalProperties\": false, \"required\": \"schemaVersion\", \"suite\", \"generatedAt\", \"ok\", \"registry\", \"outRoot\", \"adapters\", \"failures\" , \"properties\": { \"schemaVersion\": { \"const\": \"1.0.0\" }, \"suite\": { \"const\": \"GuardBench external adapter dry-run matrix\" }, \"generatedAt\": { \"type\": \"string\", \"minLength\": 1 }, \"ok\": { \"type\": \"boolean\" }, \"registry\": { \"type\": \"string\", \"minLength\": 1 }, \"outRoot\": { \"type\": \"string\", \"minLength\": 1 }, \"adapters\": { \"type\": \"array\", \"minItem… 证据：`benchmarks/schemas/guardbench-external-dry-run.schema.json`\n- **Guardbench External Evidence.Schema**（structured_config）：{ \"$schema\": \"https://json-schema.org/draft/2020-12/schema\", \"$id\": \"https://audrey-memory.org/schemas/guardbench-external-evidence.schema.json\", \"title\": \"GuardBench External Evidence Verification\", \"type\": \"object\", \"additionalProperties\": false, \"required\": \"schemaVersion\", \"suite\", \"generatedAt\", \"ok\", \"allowPending\", \"registry\", \"outRoot\", \"adapters\", \"failures\" , \"properties\": { \"schemaVersion\": { \"const\": \"1.0.0\" }, \"suite\": { \"const\": \"GuardBench external evidence verification\" }, \"generatedAt\": { \"type\": \"string\", \"minLength\": 1 }, \"ok\": { \"type\": \"boolean\" }, \"allowPending\": { \"type\": \"boolean\" }, \"registry\": { \"type\": \"string\", \"minLength\": 1 }, \"outRoot\": { \"type\": \"string\", \"mi… 证据：`benchmarks/schemas/guardbench-external-evidence.schema.json`\n- **Guardbench External Run.Schema**（structured_config）：{ \"$schema\": \"https://json-schema.org/draft/2020-12/schema\", \"$id\": \"https://audrey-memory.org/schemas/guardbench-external-run.schema.json\", \"title\": \"GuardBench External Run Metadata\", \"type\": \"object\", \"additionalProperties\": false, \"required\": \"suite\", \"startedAt\", \"adapter\", \"adapterPath\", \"outDir\", \"requiredEnv\", \"missingEnv\", \"command\", \"validationCommand\", \"dryRun\", \"status\" , \"properties\": { \"suite\": { \"const\": \"GuardBench external adapter run\" }, \"startedAt\": { \"type\": \"string\", \"minLength\": 1 }, \"completedAt\": { \"type\": \"string\", \"minLength\": 1 }, \"adapter\": { \"type\": \"string\", \"minLength\": 1 }, \"adapterPath\": { \"type\": \"string\", \"minLength\": 1 }, \"outDir\": { \"type\": \"string\", \"mi… 证据：`benchmarks/schemas/guardbench-external-run.schema.json`\n- **Guardbench Leaderboard.Schema**（structured_config）：{ \"$schema\": \"https://json-schema.org/draft/2020-12/schema\", \"$id\": \"https://audrey-memory.org/schemas/guardbench-leaderboard.schema.json\", \"title\": \"GuardBench Leaderboard\", \"type\": \"object\", \"additionalProperties\": false, \"required\": \"schemaVersion\", \"suite\", \"generatedAt\", \"ranking\", \"rows\", \"failures\" , \"properties\": { \"schemaVersion\": { \"const\": \"1.0.0\" }, \"suite\": { \"const\": \"GuardBench leaderboard\" }, \"generatedAt\": { \"type\": \"string\", \"minLength\": 1 }, \"ranking\": { \"type\": \"array\", \"minItems\": 1, \"items\": { \"type\": \"string\", \"minLength\": 1 } }, \"rows\": { \"type\": \"array\", \"items\": { \"$ref\": \" /$defs/row\" } }, \"failures\": { \"type\": \"array\", \"items\": { \"type\": \"string\" } } }, \"$defs\":… 证据：`benchmarks/schemas/guardbench-leaderboard.schema.json`\n- **Guardbench Manifest.Schema**（structured_config）：{ \"$schema\": \"https://json-schema.org/draft/2020-12/schema\", \"$id\": \"https://audrey-memory.org/schemas/guardbench-manifest.schema.json\", \"title\": \"GuardBench Manifest\", \"type\": \"object\", \"additionalProperties\": false, \"required\": \"manifestVersion\", \"suiteId\", \"suiteName\", \"generatedBy\", \"decisionVocabulary\", \"subjects\", \"metrics\", \"contract\", \"scenarios\" , \"properties\": { \"manifestVersion\": { \"type\": \"string\", \"minLength\": 1 }, \"suiteId\": { \"type\": \"string\", \"minLength\": 1 }, \"suiteName\": { \"type\": \"string\", \"minLength\": 1 }, \"generatedBy\": { \"type\": \"string\", \"minLength\": 1 }, \"decisionVocabulary\": { \"type\": \"array\", \"minItems\": 3, \"items\": { \"enum\": \"allow\", \"warn\", \"block\" }, \"contains\":… 证据：`benchmarks/schemas/guardbench-manifest.schema.json`\n- **Guardbench Publication Verification.Schema**（structured_config）：{ \"$schema\": \"https://json-schema.org/draft/2020-12/schema\", \"$id\": \"https://audrey-memory.org/schemas/guardbench-publication-verification.schema.json\", \"title\": \"GuardBench Publication Artifact Verification\", \"type\": \"object\", \"additionalProperties\": false, \"required\": \"schemaVersion\", \"suite\", \"generatedAt\", \"ok\", \"checks\", \"failures\" , \"properties\": { \"schemaVersion\": { \"const\": \"1.0.0\" }, \"suite\": { \"const\": \"GuardBench publication artifact verification\" }, \"generatedAt\": { \"type\": \"string\", \"minLength\": 1 }, \"ok\": { \"type\": \"boolean\" }, \"checks\": { \"type\": \"object\", \"additionalProperties\": false, \"required\": \"registry\", \"adapterModule\", \"selfTest\", \"artifacts\", \"bundle\", \"externalDryRu… 证据：`benchmarks/schemas/guardbench-publication-verification.schema.json`\n- **Guardbench Raw.Schema**（structured_config）：{ \"$schema\": \"https://json-schema.org/draft/2020-12/schema\", \"$id\": \"https://audrey-memory.org/schemas/guardbench-raw.schema.json\", \"title\": \"GuardBench Raw Output\", \"type\": \"object\", \"additionalProperties\": false, \"required\": \"suite\", \"generatedAt\", \"manifestVersion\", \"provenance\", \"cases\", \"artifactRedactionSweep\" , \"properties\": { \"suite\": { \"const\": \"GuardBench comparative\" }, \"generatedAt\": { \"type\": \"string\", \"minLength\": 1 }, \"manifestVersion\": { \"type\": \"string\", \"minLength\": 1 }, \"provenance\": { \"$ref\": \" /$defs/provenance\" }, \"cases\": { \"type\": \"array\", \"minItems\": 10, \"items\": { \"$ref\": \" /$defs/caseResult\" } }, \"artifactRedactionSweep\": { \"$ref\": \" /$defs/artifactRedactionSweep\"… 证据：`benchmarks/schemas/guardbench-raw.schema.json`\n- **Guardbench Submission Manifest.Schema**（structured_config）：{ \"$schema\": \"https://json-schema.org/draft/2020-12/schema\", \"$id\": \"https://audrey-memory.org/schemas/guardbench-submission-manifest.schema.json\", \"title\": \"GuardBench Submission Manifest\", \"type\": \"object\", \"additionalProperties\": false, \"required\": \"schemaVersion\", \"suite\", \"generatedAt\", \"sourceDir\", \"subject\", \"score\", \"conformance\", \"validation\", \"files\" , \"properties\": { \"schemaVersion\": { \"const\": \"1.0.0\" }, \"suite\": { \"const\": \"GuardBench submission bundle\" }, \"generatedAt\": { \"type\": \"string\", \"minLength\": 1 }, \"sourceDir\": { \"type\": \"string\", \"minLength\": 1 }, \"subject\": { \"$ref\": \" /$defs/subject\" }, \"score\": { \"$ref\": \" /$defs/score\" }, \"conformance\": { \"$ref\": \" /$defs/conform… 证据：`benchmarks/schemas/guardbench-submission-manifest.schema.json`\n- **Guardbench Summary.Schema**（structured_config）：{ \"$schema\": \"https://json-schema.org/draft/2020-12/schema\", \"$id\": \"https://audrey-memory.org/schemas/guardbench-summary.schema.json\", \"title\": \"GuardBench Summary\", \"type\": \"object\", \"additionalProperties\": false, \"required\": \"suite\", \"generatedAt\", \"manifest\", \"provenance\", \"subjects\", \"scenarios\", \"passed\", \"passRate\", \"preventionRate\", \"falseBlockRate\", \"decisionAccuracy\", \"evidenceRecall\", \"redactionLeaks\", \"recallDegradationDetectionRate\", \"latency\", \"systemSummaries\", \"comparisons\", \"rows\", \"cases\", \"artifactRedactionSweep\" , \"properties\": { \"suite\": { \"const\": \"GuardBench comparative\" }, \"generatedAt\": { \"type\": \"string\", \"minLength\": 1 }, \"manifest\": { \"type\": \"object\" }, \"provena… 证据：`benchmarks/schemas/guardbench-summary.schema.json`\n- **Perf 0.22.2**（structured_config）：{ \"generatedAt\": \"2026-05-01T02:15:29.400Z\", \"durationMs\": 4600, \"audreyVersion\": null, \"gitSha\": \"e2e821b\", \"methodology\": { \"embedding\": \"mock provider, 64 dimensions in-process, no network \", \"llm\": \"mock provider in-process \", \"retrieval\": \"hybrid vector + lexical with limit=5\", \"sizes\": 100, 1000, 5000 , \"recallRunsPerSize\": 50, \"notes\": \"Latency is wall-clock for a single call from a JS caller. Cloud and local 384-dim providers will report higher recall latency dominated by embedding cost and network. Run on your own hardware before quoting.\" }, \"machine\": { \"node\": \"25.5.0\", \"v8\": \"14.1.146.11-node.18\", \"platform\": \"win32\", \"arch\": \"x64\", \"osRelease\": \"10.0.26200\", \"cpuCount\": 24, \"c… 证据：`benchmarks/snapshots/perf-0.22.2.json`\n- **Perf 0.23.0**（structured_config）：{ \"generatedAt\": \"2026-05-05T17:32:45.578Z\", \"durationMs\": 1042, \"audreyVersion\": \"0.23.0\", \"gitSha\": \"20cdde0\", \"methodology\": { \"embedding\": \"mock provider, 64 dimensions in-process, no network \", \"llm\": \"mock provider in-process \", \"retrieval\": \"hybrid vector + lexical with limit=5\", \"sizes\": 100, 1000, 5000 , \"recallRunsPerSize\": 50, \"notes\": \"Latency is wall-clock for a single call from a JS caller. Cloud and local 384-dim providers will report higher recall latency dominated by embedding cost and network. Run on your own hardware before quoting.\" }, \"machine\": { \"node\": \"25.9.0\", \"v8\": \"14.1.146.11-node.25\", \"platform\": \"darwin\", \"arch\": \"arm64\", \"osRelease\": \"25.4.0\", \"cpuCount\": 18,… 证据：`benchmarks/snapshots/perf-0.23.0.json`\n- **Arxiv Compile Report.Schema**（structured_config）：{ \"$schema\": \"https://json-schema.org/draft/2020-12/schema\", \"$id\": \"https://audrey-memory.org/schemas/audrey-arxiv-compile-report.schema.json\", \"title\": \"Audrey arXiv Compile Report\", \"type\": \"object\", \"additionalProperties\": false, \"required\": \"schemaVersion\", \"suite\", \"generatedAt\", \"source\", \"outputDir\", \"status\", \"compiler\", \"outputPdf\", \"outputPdfSha256\", \"logFile\", \"blockers\", \"failures\" , \"properties\": { \"schemaVersion\": { \"const\": \"1.0.0\" }, \"suite\": { \"const\": \"Audrey arXiv compile check\" }, \"generatedAt\": { \"type\": \"string\", \"minLength\": 1 }, \"source\": { \"anyOf\": { \"type\": \"null\" }, { \"type\": \"object\", \"additionalProperties\": false, \"required\": \"sourceDir\", \"manifest\", \"manifestS… 证据：`docs/paper/arxiv-compile-report.schema.json`\n- **Arxiv Source.Schema**（structured_config）：{ \"$schema\": \"https://json-schema.org/draft/2020-12/schema\", \"$id\": \"https://audrey-memory.org/schemas/audrey-arxiv-source-manifest.schema.json\", \"title\": \"Audrey arXiv Source Manifest\", \"type\": \"object\", \"additionalProperties\": false, \"required\": \"schemaVersion\", \"suite\", \"generatedAt\", \"sourceMarkdown\", \"publicationPack\", \"sourceHashes\", \"files\", \"tex\" , \"properties\": { \"schemaVersion\": { \"const\": \"1.0.0\" }, \"suite\": { \"const\": \"Audrey arXiv source package\" }, \"generatedAt\": { \"type\": \"string\", \"minLength\": 1 }, \"sourceMarkdown\": { \"type\": \"string\", \"minLength\": 1 }, \"publicationPack\": { \"type\": \"string\", \"minLength\": 1 }, \"sourceHashes\": { \"type\": \"object\", \"additionalProperties\": false,… 证据：`docs/paper/arxiv-source.schema.json`\n- **Browser Launch Plan**（structured_config）：{ \"schemaVersion\": \"1.0.0\", \"suite\": \"Audrey browser launch plan\", \"checkedAt\": \"2026-05-13\", \"publicationPack\": \"docs/paper/publication-pack.json\", \"sources\": { \"id\": \"arxiv-submission-guidelines\", \"url\": \"https://info.arxiv.org/help/submit/index.html\", \"checkedAt\": \"2026-05-13\", \"notes\": \"Use the registered-author user page to start a new submission; verify uploaded files and metadata before final submit.\" }, { \"id\": \"arxiv-category-taxonomy\", \"url\": \"https://arxiv.org/category taxonomy\", \"checkedAt\": \"2026-05-13\", \"notes\": \"cs.AI covers artificial intelligence; cs.CR covers cryptography and security. Use cs.AI primary and cs.CR secondary only if the final paper framing still matches both… 证据：`docs/paper/browser-launch-plan.json`\n- **Browser Launch Plan.Schema**（structured_config）：{ \"$schema\": \"https://json-schema.org/draft/2020-12/schema\", \"$id\": \"https://audrey-memory.org/schemas/audrey-browser-launch-plan.schema.json\", \"title\": \"Audrey Browser Launch Plan\", \"type\": \"object\", \"additionalProperties\": false, \"required\": \"schemaVersion\", \"suite\", \"checkedAt\", \"publicationPack\", \"sources\", \"preflightCommands\", \"targets\" , \"properties\": { \"schemaVersion\": { \"const\": \"1.0.0\" }, \"suite\": { \"const\": \"Audrey browser launch plan\" }, \"checkedAt\": { \"type\": \"string\", \"minLength\": 1 }, \"publicationPack\": { \"type\": \"string\", \"minLength\": 1 }, \"sources\": { \"type\": \"array\", \"minItems\": 1, \"items\": { \"$ref\": \" /$defs/source\" } }, \"preflightCommands\": { \"type\": \"array\", \"minItems\":… 证据：`docs/paper/browser-launch-plan.schema.json`\n- **Browser Launch Results**（structured_config）：{ \"schemaVersion\": \"1.0.0\", \"suite\": \"Audrey browser launch results\", \"capturedAt\": \"2026-05-13\", \"plan\": \"docs/paper/browser-launch-plan.json\", \"targets\": { \"id\": \"arxiv-preprint\", \"platform\": \"arxiv\", \"status\": \"pending\", \"publicUrl\": null, \"artifactUrl\": \"https://paper-site-r3jdakujn-evilanders-projects.vercel.app\", \"submittedAt\": null, \"operatorVerified\": false, \"manualRuleCheckCompleted\": true, \"postSubmitChecksCompleted\": , \"blocker\": \"arXiv accepted the paper as submit/7591154, but the account page currently shows status on hold, so no public arXiv identifier or public abstract URL has been assigned yet.\", \"notes\": \"arXiv support confirmed the active username is Evilands and suspende… 证据：`docs/paper/browser-launch-results.json`\n- **Browser Launch Results.Schema**（structured_config）：{ \"$schema\": \"https://json-schema.org/draft/2020-12/schema\", \"$id\": \"https://audrey-memory.org/schemas/audrey-browser-launch-results.schema.json\", \"title\": \"Audrey Browser Launch Results\", \"type\": \"object\", \"additionalProperties\": false, \"required\": \"schemaVersion\", \"suite\", \"capturedAt\", \"plan\", \"targets\" , \"properties\": { \"schemaVersion\": { \"const\": \"1.0.0\" }, \"suite\": { \"const\": \"Audrey browser launch results\" }, \"capturedAt\": { \"type\": \"string\", \"minLength\": 1 }, \"plan\": { \"type\": \"string\", \"minLength\": 1 }, \"targets\": { \"type\": \"array\", \"minItems\": 1, \"items\": { \"$ref\": \" /$defs/targetResult\" } } }, \"$defs\": { \"nullableHttpsUrl\": { \"anyOf\": { \"type\": \"null\" }, { \"type\": \"string\", \"patt… 证据：`docs/paper/browser-launch-results.schema.json`\n- **Claim Register**（structured_config）：{ \"schemaVersion\": \"1.0.0\", \"suite\": \"Audrey paper claim register\", \"claims\": { \"id\": \"C01\", \"status\": \"supported\", \"claim\": \"Audrey Guard passes the local Stage-A GuardBench comparative suite without leaking seeded secrets in published artifacts.\", \"evidence\": \"benchmarks/output/guardbench-summary.json\", \"benchmarks/output/guardbench-raw.json\", \"docs/paper/evidence-ledger.md E46\", \"docs/paper/evidence-ledger.md E65\" , \"artifactChecks\": \"guardbench-local-passed\", \"no-published-secret-leaks\" , \"requiredText\": { \"path\": \"README.md\", \"text\": \"Latest local result in this checkout: 10/10 scenarios passed\" }, { \"path\": \"docs/paper/audrey-paper-v1.md\", \"text\": \"Local comparative GuardBench reports… 证据：`docs/paper/claim-register.json`\n- **Claim Register.Schema**（structured_config）：{ \"$schema\": \"https://json-schema.org/draft/2020-12/schema\", \"$id\": \"https://audrey-memory.org/schemas/audrey-paper-claim-register.schema.json\", \"title\": \"Audrey Paper Claim Register\", \"type\": \"object\", \"additionalProperties\": false, \"required\": \"schemaVersion\", \"suite\", \"claims\" , \"properties\": { \"schemaVersion\": { \"const\": \"1.0.0\" }, \"suite\": { \"const\": \"Audrey paper claim register\" }, \"claims\": { \"type\": \"array\", \"minItems\": 1, \"items\": { \"$ref\": \" /$defs/claim\" } } }, \"$defs\": { \"claim\": { \"type\": \"object\", \"additionalProperties\": false, \"required\": \"id\", \"status\", \"claim\", \"evidence\", \"artifactChecks\", \"requiredText\", \"forbiddenText\" , \"properties\": { \"id\": { \"type\": \"string\", \"pattern… 证据：`docs/paper/claim-register.schema.json`\n- **Paper Submission Bundle.Schema**（structured_config）：{ \"$schema\": \"https://json-schema.org/draft/2020-12/schema\", \"$id\": \"https://audrey-memory.org/schemas/audrey-paper-submission-bundle.schema.json\", \"title\": \"Audrey Paper Submission Bundle\", \"type\": \"object\", \"additionalProperties\": false, \"required\": \"schemaVersion\", \"suite\", \"generatedAt\", \"sourceRoot\", \"outDir\", \"claimVerification\", \"publicationPackVerification\", \"guardBenchSnapshot\", \"files\" , \"properties\": { \"schemaVersion\": { \"const\": \"1.0.0\" }, \"suite\": { \"const\": \"Audrey paper submission bundle\" }, \"generatedAt\": { \"type\": \"string\", \"minLength\": 1 }, \"sourceRoot\": { \"type\": \"string\", \"minLength\": 1 }, \"outDir\": { \"type\": \"string\", \"minLength\": 1 }, \"claimVerification\": { \"$ref\": \" /… 证据：`docs/paper/paper-submission-bundle.schema.json`\n- **Publication Pack**（structured_config）：{ \"schemaVersion\": \"1.0.0\", \"suite\": \"Audrey publication pack\", \"claimRegister\": \"docs/paper/claim-register.json\", \"entries\": { \"id\": \"arxiv-title\", \"platform\": \"arxiv\", \"kind\": \"title\", \"claimIds\": \"C01\", \"C03\" , \"maxChars\": 180, \"text\": \"Audrey: Local-First Pre-Action Memory Control for AI Agents\" }, { \"id\": \"arxiv-abstract\", \"platform\": \"arxiv\", \"kind\": \"abstract\", \"claimIds\": \"C01\", \"C02\", \"C03\", \"C04\" , \"maxChars\": 1920, \"text\": \"AI agents increasingly rely on long-running tool use, but most memory systems are evaluated as retrieval layers rather than as pre-action control systems. Audrey is a local-first memory runtime that records episodes, procedures, contradictions, tool traces, va… 证据：`docs/paper/publication-pack.json`\n- **Publication Pack.Schema**（structured_config）：{ \"$schema\": \"https://json-schema.org/draft/2020-12/schema\", \"$id\": \"https://audrey-memory.org/schemas/audrey-publication-pack.schema.json\", \"title\": \"Audrey Publication Pack\", \"type\": \"object\", \"additionalProperties\": false, \"required\": \"schemaVersion\", \"suite\", \"claimRegister\", \"entries\" , \"properties\": { \"schemaVersion\": { \"const\": \"1.0.0\" }, \"suite\": { \"const\": \"Audrey publication pack\" }, \"claimRegister\": { \"type\": \"string\", \"minLength\": 1 }, \"entries\": { \"type\": \"array\", \"minItems\": 1, \"items\": { \"$ref\": \" /$defs/entry\" } } }, \"$defs\": { \"entry\": { \"type\": \"object\", \"additionalProperties\": false, \"required\": \"id\", \"platform\", \"kind\", \"claimIds\", \"maxChars\", \"text\" , \"properties\": { \"i… 证据：`docs/paper/publication-pack.schema.json`\n- **Build artifacts and dependencies — rebuilt inside the image**（source_file）：Build artifacts and dependencies — rebuilt inside the image node modules dist .tsbuildinfo 证据：`.dockerignore`\n- **Docker-specific Audrey configuration**（source_file）：Docker-specific Audrey configuration Copy to .env and edit before running: docker compose up -d --build 证据：`.env.docker.example`\n- **Audrey Memory Configuration**（source_file）：Audrey Memory Configuration Copy to .env or set as environment variables 证据：`.env.example`\n- **.gitattributes**（source_file）：.js text eol=lf .json text eol=lf .md text eol=lf .svg text eol=lf .yml text eol=lf 证据：`.gitattributes`\n- **Node build output**（source_file）：node modules/ .npm-cache/ .tmp-npm-cache/ .audrey-demo-tmp/ .claude/settings.local.json audrey-data/ .tmp/ .tmp-vitest/ .archive/ .worktrees/ .db .db-wal .db-shm .env CLAUDE.md benchmarks/output/ benchmarks/.tmp/ benchmarks/.tmp-guardbench/ docs/paper/output/ memorybench/ windows-smoke-job- .log gcm-diagnose.log .log audrey-arxiv-preview.png 证据：`.gitignore`\n- **.npmignore**（source_file）：tests/ docs/ examples/ node modules/ test- -data/ .git/ .gitignore .env CLAUDE.md vitest.config.js package-lock.json .db .db-wal .db-shm 证据：`.npmignore`\n- 其余 20 条证据见 `AI_CONTEXT_PACK.json` 或 `EVIDENCE_INDEX.json`。\n\n## 宿主 AI 必须遵守的规则\n\n- **把本资产当作开工前上下文，而不是运行环境。**：AI Context Pack 只包含证据化项目理解，不包含目标项目的可执行状态。 证据：`README.md`, `python/README.md`, `package.json`\n- **回答用户时区分可预览内容与必须安装后才能验证的内容。**：安装前体验的消费者价值来自降低误装和误判，而不是伪装成真实运行。 证据：`README.md`, `python/README.md`, `package.json`\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- **项目概述**：importance `high`\n - source_paths: README.md, package.json\n- **快速开始**：importance `high`\n - source_paths: README.md, package.json\n- **系统架构**：importance `high`\n - source_paths: src/audrey.ts, src/controller.ts, src/db.ts, mcp-server/index.ts, src/server.ts\n- **记忆模型**：importance `high`\n - source_paths: src/encode.ts, src/recall.ts, src/consolidate.ts, src/decay.ts, src/interference.ts\n- **Audrey Guard 安全循环**：importance `high`\n - source_paths: src/preflight.ts, src/reflexes.ts, src/redact.ts, src/feedback.ts, src/action-key.ts\n- **数据存储**：importance `medium`\n - source_paths: src/db.ts, src/fts.ts, src/hybrid-recall.ts, src/embedding.ts\n- **MCP集成**：importance `high`\n - source_paths: mcp-server/index.ts, mcp-server/config.ts, src/routes.ts\n- **REST API**：importance `medium`\n - source_paths: src/routes.ts, src/server.ts, src/validate.ts\n\n## Repo Inspection Evidence / 源码检查证据\n\n- repo_clone_verified: true\n- repo_inspection_verified: true\n- repo_commit: `82b0e9979680acf751b9e80f6f90f8c6ac74befb`\n- inspected_files: `Dockerfile`, `package.json`, `README.md`, `docker-compose.yml`, `docs/PRODUCTION_BACKLOG.md`, `docs/MEMORY_BENCHMARKING.md`, `docs/AUDREY_PAPER_OUTLINE.md`, `docs/paper/06-implementation.md`, `docs/paper/browser-launch-plan.schema.json`, `docs/paper/00-master.md`, `docs/paper/publication-pack.json`, `docs/paper/03-problem-definition.md`, `docs/paper/claim-register.schema.json`, `docs/paper/publication-pack.schema.json`, `docs/paper/02-related-work.md`, `docs/paper/01-introduction.md`, `docs/paper/08-discussion-limitations.md`, `docs/paper/evidence-ledger.md`, `docs/paper/arxiv-source.schema.json`, `docs/paper/audrey-paper-v1.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: 来源证据：Audrey 1.0.1 — honest GuardBench gate, Guard time decay, structured validate errors\n\n- Trigger: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Audrey 1.0.1 — honest GuardBench gate, Guard time decay, structured validate errors\n- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_135b992964ae468aa28f88ee639816d1 | https://github.com/Evilander/Audrey/releases/tag/v1.0.1 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 2: 来源证据：Audrey Guard 0.23.0\n\n- Trigger: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Audrey Guard 0.23.0\n- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_9c913c644e2c4c099ea01523623f080e | https://github.com/Evilander/Audrey/releases/tag/v0.23.0 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 3: 来源证据：v0.16.0\n\n- Trigger: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v0.16.0\n- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_a7c5c62d4f034e50ba2e9c36e0798882 | https://github.com/Evilander/Audrey/releases/tag/v0.16.0 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 4: 来源证据：v0.16.1 — Windows MCP fix\n\n- Trigger: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v0.16.1 — Windows MCP fix\n- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_c0141ccf0a3245ec8c8ba112af7948e0 | https://github.com/Evilander/Audrey/releases/tag/v0.16.1 | 来源讨论提到 windows 相关条件，需在安装/试用前复核。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 5: 来源证据：v0.17.0\n\n- Trigger: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v0.17.0\n- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_9617863b3f954035926b8670b5bbea29 | https://github.com/Evilander/Audrey/releases/tag/v0.17.0 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 6: 可能修改宿主 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:1161444210 | https://github.com/Evilander/Audrey | host_targets=mcp_host, claude, claude_code\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 7: 能力判断依赖假设\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:1161444210 | https://github.com/Evilander/Audrey | README/documentation is current enough for a first validation pass.\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 8: 维护活跃度未知\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:1161444210 | https://github.com/Evilander/Audrey | last_activity_observed missing\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 9: 下游验证发现风险项\n\n- Trigger: no_demo\n- Host AI rule: 进入安全/权限治理复核队列。\n- Why it matters: 下游已经要求复核，不能在页面中弱化。\n- Evidence: downstream_validation.risk_items | github_repo:1161444210 | https://github.com/Evilander/Audrey | no_demo; severity=medium\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 10: 存在评分风险\n\n- Trigger: no_demo\n- Host AI rule: 把风险写入边界卡，并确认是否需要人工复核。\n- Why it matters: 风险会影响是否适合普通用户安装。\n- Evidence: risks.scoring_risks | github_repo:1161444210 | https://github.com/Evilander/Audrey | no_demo; severity=medium\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项目：Evilander/Audrey\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 是否匹配：mcp_host, claude, claude_code\n- 官方安装入口状态：已发现官方入口\n- 是否在临时目录、临时宿主或容器中验证：必须是\n- 是否能回滚配置改动：必须能\n- 是否需要 API Key、网络访问、读写文件或修改宿主配置：未确认前按高风险处理\n- 是否记录了安装命令、实际输出和失败日志：必须记录\n\n## 当前阻塞项\n\n- 无阻塞项。\n\n## 项目专属踩坑\n\n- 来源证据：Audrey 1.0.1 — honest GuardBench gate, Guard time decay, structured validate errors（medium）：可能增加新用户试用和生产接入成本。 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 来源证据：Audrey Guard 0.23.0（medium）：可能增加新用户试用和生产接入成本。 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 来源证据：v0.16.0（medium）：可能增加新用户试用和生产接入成本。 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 来源证据：v0.16.1 — Windows MCP fix（medium）：可能增加新用户试用和生产接入成本。 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 来源证据：v0.17.0（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/Evilander/Audrey 项目说明书\n\n生成时间：2026-05-16 03:41:21 UTC\n\n## 目录\n\n- [项目概述](#page-overview)\n- [快速开始](#page-quick-start)\n- [系统架构](#page-system-architecture)\n- [记忆模型](#page-memory-model)\n- [Audrey Guard 安全循环](#page-audrey-guard)\n- [数据存储](#page-data-storage)\n- [MCP集成](#page-mcp-integration)\n- [REST API](#page-rest-api)\n- [CLI工具](#page-cli-tools)\n- [JavaScript SDK](#page-javascript-sdk)\n\n\n\n## 项目概述\n\n### 相关页面\n\n相关主题：[系统架构](#page-system-architecture), [快速开始](#page-quick-start)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/Evilander/Audrey/blob/main/README.md)\n- [CHANGELOG.md](https://github.com/Evilander/Audrey/blob/main/CHANGELOG.md)\n- [python/README.md](https://github.com/Evilander/Audrey/blob/main/python/README.md)\n- [src/routes.ts](https://github.com/Evilander/Audrey/blob/main/src/routes.ts)\n- [src/capsule.ts](https://github.com/Evilander/Audrey/blob/main/src/capsule.ts)\n- [src/rules-compiler.ts](https://github.com/Evilander/Audrey/blob/main/src/rules-compiler.ts)\n- [mcp-server/index.ts](https://github.com/Evilander/Audrey/blob/main/mcp-server/index.ts)\n \n\n# 项目概述\n\nAudrey 是一个为 AI 代理（AI Agents）设计的本地优先（local-first）记忆防火墙项目。它为 Codex、Claude Code、Claude Desktop、Cursor、Windsurf、VS Code、JetBrains、Ollama 后端代理以及自定义代理服务提供了一层持久的记忆层，使这些代理能够在执行工具操作前检查记忆内容。\n\n## 核心定位\n\n### 问题背景\n\nAI 代理在长时间运行和跨会话工作时面临以下挑战：\n\n- **记忆缺失**：代理会忘记昨天犯下的具体错误\n- **重复错误**：代理会重复执行之前失败过的命令\n- **规则丢失**：项目特定的规则在不同会话间丢失\n- **矛盾忽略**：代理忽视上下文中的矛盾信息\n- **冷启动**：每次新会话都像从零开始\n\n### 解决方案\n\nAudrey Guard 是项目的核心循环机制，其工作流程如下：\n\n1. **记录**（Record）：记录代理的操作和结果\n2. **记忆**（Remember）：记住重要的内容\n3. **检查**（Check）：在行动前进行检查\n4. **决策**（Decide）：返回 `allow`（允许）、`warn`（警告）或 `block`（阻止）决策，并附带证据\n5. **验证**（Validate）：验证记忆是否真正帮助了代理\n\n资料来源：[README.md:1-25]()\n\n```mermaid\ngraph TD\n A[代理执行工具] --> B{Audrey Guard 检查}\n B -->|允许| C[执行工具]\n B -->|警告| D[返回警告+证据]\n B -->|阻止| E[阻止执行]\n C --> F[记录结果到记忆]\n D --> F\n F --> G{验证成功?}\n G -->|是| H[强化记忆+置信度↑]\n G -->|否| I[弱化记忆+衰减]\n```\n\n## 功能架构\n\n### 多层客户端支持\n\n| 客户端类型 | 状态 | 说明 |\n|-----------|------|------|\n| MCP stdio server | ✅ 稳定 | 提供 20 个工具，以及 status/recent/principles 资源和 briefing/recall/reflection 提示 |\n| CLI | ✅ 稳定 | 支持 doctor、demo、guard、install、mcp-config、hook-config、status、dream、reembed、observe-tool、promote、impact 等命令 |\n| REST API | ✅ 稳定 | 基于 Hono 框架构建，提供 `/health` 和 `/v1/*` 路由 |\n| JavaScript SDK | ✅ 稳定 | 支持直接从 `audrey` 包进行 TypeScript/Node 导入 |\n| Python client | ✅ 稳定 | 通过 `pip install audrey-memory` 安装，调用 REST sidecar |\n\n资料来源：[README.md:88-95]()\n\n### 存储架构\n\nAudrey 采用本地存储方案，无需托管数据库：\n\n- **SQLite**：主数据库，使用 WAL 模式\n- **sqlite-vec**：向量检索扩展\n\n```mermaid\ngraph LR\n A[代理应用] -->|REST API| B[Hono Server]\n A -->|MCP| B\n B --> C[SQLite + WAL]\n B --> D[sqlite-vec]\n```\n\n**重要约束**：SQLite 使用 WAL 模式但无咨询锁，两个进程共享同一目录会导致写竞争。多代理场景下，每个租户、代理身份或并发主机必须设置独立的 `AUDREY_DATA_DIR`。\n\n资料来源：[README.md:107-109]()\n\n## 记忆模型\n\nAudrey 内置了针对代理场景优化的多维度记忆系统：\n\n### 记忆类型\n\n| 记忆类型 | 描述 | 示例 |\n|---------|------|------|\n| 情景记忆 (Episodic) | 具体的观察、工具结果、偏好和会话事实 | \"上次 npm run deploy 因权限失败\" |\n| 语义记忆 (Semantic) | 从重复证据中提炼的概括性原则 | \"在部署前检查权限配置\" |\n| 程序记忆 (Procedural) | 记住的执行方式、规避方法、重试策略和验证流程 | \"恢复失败时使用 git revert\" |\n| 情感与显著性 (Affect & Salience) | 情感权重和重要性影响召回 | 反复失败的命令标记为高显著性 |\n\n资料来源：[README.md:111-120]()\n\n### 记忆生命周期\n\n```mermaid\ngraph TD\n A[新记忆写入] --> B{首次编码}\n B --> C[验证循环]\n C -->|收到反馈| D[置信度更新]\n C -->|重复触发| E[证据积累]\n D --> F[巩固 Consolidation]\n E --> F\n F --> G[衰减 Decay 检查]\n G -->|过期/低置信度| H[降级处理]\n G -->|活跃| I[高优先级召回]\n```\n\n### 高级特性\n\n- **干扰与衰减**（Interference & Decay）：过时、冲突或低置信度的记忆会随时间失去权威性\n- **矛盾处理**（Contradiction Handling）：对竞争的声明进行追踪而非静默覆盖\n- **工具追踪学习**（Tool-trace Learning）：从工具执行轨迹中提取学习模式\n\n资料来源：[README.md:121-124]()\n\n## REST API\n\n### 端点概览\n\n| 方法 | 端点 | 功能 |\n|------|------|------|\n| POST | `/v1/encode` | 编码记忆 |\n| POST | `/v1/recall` | 召回相关记忆 |\n| POST | `/v1/capsule` | 获取回合级记忆包 |\n| GET | `/v1/status` | 健康检查 |\n| GET | `/health` | 基础健康状态 |\n\n资料来源：[README.md:85-87]()\n\n### 请求示例\n\n```typescript\nimport Audrey from 'audrey';\n\nconst brain = new Audrey({\n base_url: \"http://127.0.0.1:7437\",\n agent: \"support-agent\"\n});\n\nbrain.encode(\n \"Stripe returns HTTP 429 above 100 req/s\",\n source: \"direct-observation\",\n tags: [\"stripe\", \"rate-limit\"]\n);\n\nconst results = brain.recall(\"stripe rate limits\", limit: 5);\nbrain.close();\n```\n\n资料来源：[python/README.md:30-45]()\n\n## 部署模式\n\n### 部署方式\n\n| 方式 | 说明 |\n|------|------|\n| npm 包 | `npm install audrey` |\n| Docker | 容器化部署 |\n| Compose | docker-compose 编排 |\n| MCP 配置生成 | 针对不同主机的 MCP 配置自动生成 |\n\n### MCP 配置\n\nAudrey 提供针对多种主机的 MCP 配置生成：\n\n```bash\nnpx audrey mcp-config codex\nnpx audrey mcp-config generic\nnpx audrey mcp-config vscode\n```\n\nClaude Code 还可以直接注册：\n\n```bash\nnpx audrey install\nclaude mcp list\n```\n\n资料来源：[README.md:96-102]()\n\n### Claude Code 钩子配置\n\n```mermaid\ngraph LR\n A[Claude Code] -->|PreToolUse| B[audrey guard --hook]\n A -->|PostToolUse| C[记录脱敏工具轨迹]\n A -->|PostToolUseFailure| C\n B --> D{决策}\n D -->|allow| E[继续执行]\n D -->|warn| F[警告+证据]\n D -->|block| G[阻止执行]\n```\n\n预览钩子配置：\n```bash\nnpx audrey hook-config claude-code\n```\n\n应用钩子配置：\n```bash\nnpx audrey hook-config claude-code --apply --scope project\nnpx audrey hook-config claude-code --apply --scope user\n```\n\n资料来源：[mcp-server/index.ts:1-50]()\n\n## 安全机制\n\n### 认证与授权\n\n| 配置项 | 默认值 | 用途 |\n|--------|--------|------|\n| `AUDREY_HOST` | `127.0.0.0.1` | REST sidecar 绑定地址 |\n| `AUDREY_API_KEY` | 未设置 | 非回环 REST 流量的 Bearer token |\n| `AUDREY_ALLOW_NO_AUTH` | `0` | 允许非回环绑定时无需 API key |\n| `AUDREY_ENABLE_ADMIN_TOOLS` | `0` | 启用导出、导入、遗忘路由/工具 |\n\n> ⚠️ 除非设置 `AUDREY_API_KEY`，否则只能绑定到 `0.0.0.0`。\n\n资料来源：[README.md:127-133]()\n\n### 安全改进（v0.22+）\n\n- HTTP `/v1/recall` 和 `/v1/capsule` 不再将调用者选项体展开到 `audrey.recall()`，防止 `includePrivate: true` 和 `confidenceConfig` 覆盖绕过私有记忆 ACL\n- `audrey serve` 默认为 `127.0.0.1` 绑定，非回环主机无 API key 拒绝启动\n- HTTP API key 比较使用 `crypto.timingSafeEqual` 防止前缀匹配时序泄露\n- `audrey promote --yes` 拒绝写入 `process.cwd()` 之外的 `.claude/rules/*.md`，防止恶意 MCP 调用者注入持久化提示\n\n资料来源：[CHANGELOG.md:1-100]()\n\n## 环境变量配置\n\n### 核心配置\n\n| 变量 | 默认值 | 用途 |\n|------|--------|------|\n| `AUDREY_DATA_DIR` | `.audrey-data/` | 数据存储目录 |\n| `AUDREY_EMBEDDING_PROVIDER` | 自动检测 | 向量嵌入提供者 |\n| `AUDREY_LLM_PROVIDER` | 自动检测 | LLM 提供者 |\n| `AUDREY_DEBUG` | `0` | 启用 MCP 信息日志 |\n| `AUDREY_PROFILE` | `0` | 通过 MCP `_meta.diagnostics` 发出各阶段计时 |\n| `AUDREY_DISABLE_WARMUP` | `0` | 跳过 MCP 启动时的后台嵌入预热 |\n| `AUDREY_PRAGMA_DEFAULTS` | `1` | 是否恢复 SQLite PRAGMA 到 better-sqlite3 默认值 |\n\n### 记忆配置\n\n| 变量 | 默认值 | 用途 |\n|------|--------|------|\n| `AUDREY_CONTEXT_BUDGET_CHARS` | `4000` | 记忆胶囊默认字符预算 |\n| `AUDREY_PROMOTE_ROOTS` | 未设置 | `audrey promote --yes` 写入的额外根目录 |\n\n资料来源：[README.md:134-145]()\n\n## 性能指标\n\n### v0.22.0 性能改进\n\n| 指标 | 改进前 | 改进后 | 提升幅度 |\n|------|--------|--------|----------|\n| 编码响应时间 p50 | 24.7ms | 15.2ms | ~40% |\n| 冷启动首次编码 | 525ms | 28ms（预热后） | 18.7x |\n| 混合召回 | 30.2ms | 14.3ms | 2.1x |\n\n**优化策略**：编码过程中消除了 4 个冗余嵌入调用中的 3 个，验证、干扰和情感共鸣现在复用主内容向量。\n\n资料来源：[CHANGELOG.md:25-50]()\n\n## 规则编译与推广\n\n当记忆达到足够置信度时，可通过 `audrey promote` 将记忆提升为持久化规则文件：\n\n```mermaid\ngraph TD\n A[高置信度记忆] --> B[PromotionCandidate]\n B --> C{rules-compiler.ts}\n C --> D[.claude/rules/.md]\n D --> E[YAML frontmatter]\n E --> F[source memory_ids]\n E --> G[confidence + evidence_count]\n E --> H[promotion_timestamp]\n```\n\n每个规则文件包含：\n- 标题：从记忆中推断\n- Slug：自动生成\n- 相对路径：`.claude/rules/.md`\n- 正文：规则内容\n- Frontmatter：源记忆追踪信息\n\n资料来源：[src/rules-compiler.ts:1-30]()\n\n## 记忆胶囊（Capsule）\n\nCapsule 是回合级记忆数据包，按不同分类组织记忆：\n\n| 分类 | 来源条件 |\n|------|----------|\n| `recent_changes` | 最近变化窗口内创建或强化的记忆 |\n| `must_follow` | 标记为必须遵守的规则 |\n| `procedures` | 程序性记忆或标记为程序的记忆 |\n| `user_preferences` | 用户声明的偏好或标记为用户偏好的记忆 |\n| `risks` | 标记为风险或警告的记忆 + 最近工具失败 |\n| `uncertain_or_disputed` | 争议性记忆或低置信度记忆 |\n\n资料来源：[src/capsule.ts:1-80]()\n\n## 生产就绪检查\n\n### 发布门控\n\n```bash\nnpm run release:gate\npython -m unittest discover -s python/tests -v\nnpm run python:release:check\nnpm run bench:guard:card\nnpm run bench:guard:validate\nnpx audrey doctor\nnpx audrey demo\n```\n\n### 生产环境建议\n\n1. 每个租户、环境或隔离边界设置独立的 `AUDREY_DATA_DIR`\n2. 明确指定 `AUDREY_EMBEDDING_PROVIDER` 和 `AUDREY_LLM_PROVIDER`\n3. 提供者或维度变更前备份 SQLite 数据目录\n4. 编码记忆内容中排除 API key 和原始凭证\n5. REST sidecar 可被本地进程外访问时使用 `AUDREY_API_KEY`\n6. 定期运行 `npx audrey dream` 以保持巩固和衰减活跃\n7. 监管环境需添加应用级加密、保留策略、访问控制和审计日志\n\n资料来源：[README.md:70-85]()\n\n## 技术栈\n\n| 层级 | 技术选型 |\n|------|----------|\n| 运行时 | Node.js / TypeScript |\n| CLI 框架 | 未知（基于 mcp-server/index.ts） |\n| REST 框架 | Hono |\n| 数据库 | SQLite + sqlite-vec |\n| Python SDK | httpx + pydantic |\n\n资料来源：[python/README.md:1-30]()\n\n## 许可\n\nAudrey 采用 MIT 许可证开源。\n\n资料来源：[README.md:1]()\n\n---\n\n\n\n## 快速开始\n\n### 相关页面\n\n相关主题：[项目概述](#page-overview), [CLI工具](#page-cli-tools)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/Evilander/Audrey/blob/main/README.md)\n- [python/README.md](https://github.com/Evilander/Audrey/blob/main/python/README.md)\n- [src/routes.ts](https://github.com/Evilander/Audrey/blob/main/src/routes.ts)\n- [src/impact.ts](https://github.com/Evilander/Audrey/blob/main/src/impact.ts)\n- [mcp-server/index.ts](https://github.com/Evilander/Audrey/blob/main/mcp-server/index.ts)\n- [src/rules-compiler.ts](https://github.com/Evilander/Audrey/blob/main/src/rules-compiler.ts)\n \n\n# 快速开始\n\nAudrey 是一个本地优先的 AI 代理内存防火墙，为 Codex、Claude Code、Claude Desktop、Cursor、Windsurf、VS Code、JetBrains、Ollama 后端代理以及自定义代理服务提供持久的内存层。代理可以在执行工具操作前查询此内存层，从而避免重复犯错的命令、保留项目特定规则、发现矛盾信息。\n\n本页面将引导您完成 Audrey 的完整安装、配置和基础使用流程。\n\n## 环境要求\n\n| 组件 | 版本要求 | 说明 |\n|------|----------|------|\n| Node.js | ≥18.0.0 | 用于运行 CLI 和 MCP 服务器 |\n| npm | ≥9.0.0 | 包管理器 |\n| Python | ≥3.10 | 如需使用 Python SDK |\n| SQLite | 3.39+ | 内置支持，，无需单独安装 |\n\n资料来源：[README.md:1-15]()\n\n## 安装方式\n\n### npm 全局安装\n\nAudrey 作为 npm 包发布，可通过 npx 直接运行：\n\n```bash\nnpx audrey serve\n```\n\n或全局安装以获得更好的离线体验：\n\n```bash\nnpm install -g audrey\n```\n\n资料来源：[README.md:88-92]()\n\n### Python SDK 安装\n\n如需在 Python 项目中使用 Audrey：\n\n```bash\npip install audrey-memory\n```\n\n本地开发模式安装：\n\n```bash\ncd python\npython -m pip install -e .\n```\n\n资料来源：[python/README.md:1-18]()\n\n## 启动服务\n\n### 启动 REST API 服务\n\nAudrey 的 REST API 是核心通信接口，CLI、Python SDK 和 MCP 服务器都依赖此接口：\n\n```bash\nnpx audrey serve\n```\n\n服务默认绑定到 `127.0.0.1:7437`，可通过环境变量修改：\n\n| 环境变量 | 默认值 | 说明 |\n|----------|--------|------|\n| `AUDREY_PORT` | `7437` | REST API 监听端口 |\n| `AUDREY_HOST` | `127.0.0.1` | REST API 绑定地址，仅在设置 `AUDREY_API_KEY` 时可设为 `0.0.0.0` |\n| `AUDREY_API_KEY` | 未设置 | 非本地流量需要 Bearer token 认证 |\n| `AUDREY_DATA_DIR` | `./audrey-data` | SQLite 数据库存储目录 |\n\n资料来源：[README.md:98-115]()\n\n### 启动 MCP 服务器\n\nMCP 服务器提供 20 个工具和多个资源端点：\n\n```bash\nnpx audrey mcp-config \n```\n\n支持的 host 类型：\n- `codex` — Codex 代理\n- `generic` — 通用 MCP 客户端\n- `vscode` — VS Code 代理\n\n资料来源：[mcp-server/index.ts:1-30]()\n\n## 基础使用流程\n\n### 架构概览\n\n```mermaid\ngraph TD\n subgraph 客户端层\n CLI[CLI
audrey 命令]\n MCP[MCP 服务器
stdio 连接]\n REST[REST API
HTTP 请求]\n Python[Python SDK
Python 客户端]\n end\n \n subgraph 核心服务\n Server[Hono 服务器
:7437]\n Audrey[Audrey 核心引擎
记忆处理]\n end\n \n subgraph 存储层\n SQLite[(SQLite
主数据库)]\n Vec[(sqlite-vec
向量索引)]\n end\n \n CLI --> Server\n MCP --> Server\n REST --> Server\n Python --> Server\n Server --> Audrey\n Audrey --> SQLite\n Audrey --> Vec\n```\n\n### 内存编码与检索\n\n#### Python SDK 使用\n\n```python\nfrom audrey_memory import Audrey\n\nbrain = Audrey(\n base_url=\"http://127.0.0.1:7437\",\n api_key=\"secret\",\n agent=\"support-agent\",\n)\n\n# 编码记忆\nmemory_id = brain.encode(\n \"Stripe 返回 HTTP 429 超过 100 req/s\",\n source=\"direct-observation\",\n tags=[\"stripe\", \"rate-limit\"],\n)\n\n# 检索相关记忆\nresults = brain.recall(\"stripe rate limit\", limit=5)\n\n# 获取快照\nsnapshot = brain.snapshot()\nbrain.close()\n```\n\n资料来源：[python/README.md:20-60]()\n\n#### REST API 调用\n\n| 端点 | 方法 | 功能 |\n|------|------|------|\n| `/v1/encode` | POST | 编码新记忆 |\n| `/v1/recall` | POST | 检索相关记忆 |\n| `/v1/capsule` | POST | 获取回合级记忆包 |\n| `/v1/status` | GET | 健康检查 |\n\n资料来源：[README.md:68-74]()\n\n### 异步使用\n\n```python\nimport asyncio\nfrom audrey_memory import AsyncAudrey\n\nasync def main() -> None:\n async with AsyncAudrey(base_url=\"http://127.0.0.1:7437\") as brain:\n await brain.health()\n await brain.encode(\"部署失败因 OOM\", source=\"direct-observation\")\n await brain.recall(\"部署失败\", limit=3)\n\nasyncio.run(main())\n```\n\n资料来源：[python/README.md:62-75]()\n\n## Guard 模式：记忆前置检查\n\nAudrey Guard 是核心反馈循环：在执行工具操作前检查记忆，返回 `allow`、`warn` 或 `block` 并附带证据。\n\n### CLI Guard 命令\n\n```bash\nnpx audrey guard --tool Bash \"npm run deploy\"\n```\n\n### 集成 Claude Code\n\n预览钩子配置：\n\n```bash\nnpx audrey hook-config claude-code\n```\n\n应用钩子配置：\n\n```bash\n# 项目级钩子\nnpx audrey hook-config claude-code --apply --scope project\n\n# 用户级钩子\nnpx audrey hook-config claude-code --apply --scope user\n```\n\n生成的 `PreToolUse` 钩子运行 `audrey guard --hook --fail-on-warn`，`PostToolUse` 和 `PostToolUseFailure` 钩子记录脱敏的工具追踪。\n\n资料来源：[README.md:75-82]()\n\n### Guard 工作流程\n\n```mermaid\ngraph TD\n A[代理执行工具] --> B{PreToolUse 钩子}\n B --> C[调用 audrey guard]\n C --> D[查询记忆库]\n D --> E{决策判断}\n E -->|allow| F[允许执行]\n E -->|warn| G[警告执行]\n E -->|block| H[阻止执行]\n G --> I{用户确认?}\n I -->|是| F\n I -->|否| H\n F --> J[PostToolUse 钩子]\n H --> K[记录阻止事件]\n J --> L[编码执行结果]\n K --> L\n```\n\n## 开发环境配置\n\n### 从源码构建\n\n```bash\nnpm ci\nnpm run build\nnpm test\n```\n\n构建后，CLI 子命令解析本地 `dist/` 输出。\n\n资料来源：[README.md:135-145]()\n\n### 完整发布门控\n\n```bash\nnpm run release:gate\npython -m unittest discover -s python/tests -v\nnpm run python:release:check\n```\n\n## 诊断与验证\n\n### 健康检查\n\n```bash\nnpx audrey doctor\nnpx audrey doctor --json\n```\n\n### 状态检查\n\n```bash\nnpx audrey status --json --fail-on-unhealthy\n```\n\n### 影响评估\n\nAudrey 提供影响评估功能，跟踪记忆的验证状态和使用情况：\n\n```bash\nnpx audrey impact --window 30\n```\n\n返回内容包括：\n- 按类型统计（情景记忆、语义记忆、程序记忆）\n- 窗口期内的验证数量\n- 结果分布（helpful、wrong、used）\n- 高频使用的记忆条目\n- 活跃度最弱的记忆条目\n\n资料来源：[src/impact.ts:1-50]()\n\n## 规则编译与提升\n\n### 规则编译\n\nAudrey 支持将记忆提升为可审查的 Markdown 规则文件：\n\n```bash\nnpx audrey promote\n```\n\n生成的规则文件位于 `.claude/rules/` 目录，包含 YAML 前置元数据，记录源记忆 ID、置信度、证据数量和提升时间戳。\n\n资料来源：[src/rules-compiler.ts:1-30]()\n\n### 规则文件结构\n\n```yaml\n---\ntitle: \"Audrey semantic memory xxx\"\nmemory_ids: [\"01ARZ3NDEKTSV4RRFFQ69G5FAV\"]\nconfidence: 0.85\nevidence_count: 5\npromoted_at: \"2025-01-15T10:30:00Z\"\n---\n\n# 规则正文\n```\n\n## 内存模型\n\nAudrey 的内存模型包含以下维度：\n\n| 内存类型 | 说明 | 示例 |\n|----------|------|------|\n| 情景记忆 | 具体观察、工具结果、偏好、会话事实 | \"用户在 macOS 上运行，遇到权限错误\" |\n| 语义记忆 | 从重复证据中提取的巩固原则 | \"macOS 需要 sudo 才能安装全局 npm 包\" |\n| 程序记忆 | 记住的执行方式、避免事项、重试或验证方法 | \"先检查 --dry-run，再实际执行\" |\n| 情感与显著性 | 情感权重和重要性影响召回 | 高情绪记忆更容易被保留 |\n| 干扰与衰减 | 陈旧、冲突或低置信度记忆逐渐失去权威性 | 长时间未使用的记忆降低权重 |\n| 矛盾处理 | 竞争性声明被追踪而非静默覆盖 | 多条相互矛盾的规则同时标记为待验证 |\n\n资料来源：[README.md:53-68]()\n\n## 数据恢复\n\n### 创建快照\n\n```python\nsnapshot = brain.snapshot()\n# 快照可序列化并保存到外部存储\n```\n\n### 恢复快照\n\n```python\nrestore_target = Audrey(base_url=\"http://127.0.0.1:7437\", api_key=\"secret\")\nrestore_target.restore(snapshot)\nrestore_target.close()\n```\n\n恢复只能导入到空的 Audrey 存储，例如使用新的 `AUDREY_DATA_DIR` 启动的 sidecar。\n\n资料来源：[python/README.md:48-57]()\n\n## 生产环境注意事项\n\n| 检查项 | 说明 |\n|--------|------|\n| 数据目录隔离 | 每个租户、环境或隔离边界设置独立的 `AUDREY_DATA_DIR` |\n| 嵌入模型锁定 | 明确锁定 `AUDREY_EMBEDDING_PROVIDER` 和 `AUDREY_LLM_PROVIDER` |\n| 数据备份 | 提供商或维度变更前备份 SQLite 数据目录 |\n| API 密钥保护 | 保持 API 密钥和原始凭据不在编码记忆内容中 |\n| 网络访问控制 | REST sidecar 可被外部访问时必须设置 `AUDREY_API_KEY` |\n| 定期整合 | 按计划运行 `npx audrey dream` 以保持整合和衰减更新 |\n| 监管环境 | 添加应用级加密、保留、访问控制和审计日志 |\n\n资料来源：[README.md:116-132]()\n\n## 常见问题\n\n### Q: 启动时报错 `bind: address already in use`\n\n端口 7437 被占用，可通过 `AUDREY_PORT` 环境变量指定其他端口：\n\n```bash\nAUDREY_PORT=7438 npx audrey serve\n```\n\n### Q: 远程连接被拒绝\n\n默认情况下服务仅绑定 `127.0.0.1`，如需远程访问：\n\n1. 设置 API 密钥：`AUDREY_API_KEY=your-secret`\n2. 修改绑定地址：`AUDREY_HOST=0.0.0.0`\n\n警告：不推荐在生产环境中禁用认证。\n\n### Q: 记忆检索结果不准确\n\n1. 运行 `npx audrey reembed` 重新生成向量索引\n2. 调整 `memory_recall` 参数的 `retrieval` 模式（`hybrid` 或 `vector`）\n3. 检查相关记忆的置信度是否过低（可能被衰减）\n\n资料来源：[README.md:98-115]()\n\n### Q: MCP 服务器连接失败\n\n确保 MCP 配置正确生成：\n\n```bash\nnpx audrey mcp-config --dry-run\n```\n\n验证 MCP 服务器已启动并监听 stdio。\n\n---\n\n\n\n## 系统架构\n\n### 相关页面\n\n相关主题：[项目概述](#page-overview), [记忆模型](#page-memory-model), [数据存储](#page-data-storage)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/audrey.ts](https://github.com/Evilander/Audrey/blob/main/src/audrey.ts)\n- [src/routes.ts](https://github.com/Evilander/Audrey/blob/main/src/routes.ts)\n- [src/db.ts](https://github.com/Evilander/Audrey/blob/main/src/db.ts)\n- [mcp-server/index.ts](https://github.com/Evilander/Audrey/blob/main/mcp-server/index.ts)\n- [src/server.ts](https://github.com/Evilander/Audrey/blob/main/src/server.ts)\n- [src/capsule.ts](https://github.com/Evilander/Audrey/blob/main/src/capsule.ts)\n- [src/redact.ts](https://github.com/Evilander/Audrey/blob/main/src/redact.ts)\n- [src/rules-compiler.ts](https://github.com/Evilander/Audrey/blob/main/src/rules-compiler.ts)\n- [src/impact.ts](https://github.com/Evilander/Audrey/blob/main/src/impact.ts)\n \n\n# 系统架构\n\n## 概述\n\nAudrey 是一个本地优先的 AI 代理内存防火墙（local-first memory firewall），为 Codex、Claude Code、Cursor、Windsurf 等 AI 代理提供持久化的记忆层。其核心设计目标是在代理执行操作前检查记忆，在操作后记录经验，形成闭环的学习-验证机制。\n\n系统架构采用分层设计，核心层基于 TypeScript 实现，通过 MCP（Model Context Protocol）协议与各类 AI 代理集成，同时提供 REST API 和 Python SDK 供外部调用。\n\n## 架构总览\n\n```mermaid\ngraph TB\n subgraph 代理层\n A[Claude Code] \n B[Codex] \n C[Cursor] \n D[VS Code]\n end\n \n subgraph 协议层\n E[MCP stdio 服务器]\n F[REST API 服务器]\n G[CLI 接口]\n end\n \n subgraph 核心引擎\n H[Audrey 核心]\n I[记忆模型]\n J[检索引擎]\n end\n \n subgraph 存储层\n K[SQLite]\n L[sqlite-vec 向量索引]\n end\n \n A --> E\n B --> E\n C --> E\n D --> E\n \n F --> H\n E --> H\n G --> H\n \n H --> I\n H --> J\n \n I --> K\n J --> L\n J --> K\n```\n\n## 核心组件\n\n### Audrey 核心引擎\n\n核心引擎位于 `src/audrey.ts`，是整个系统的心脏，负责记忆的编码、检索、衰减和一致性管理。\n\n| 组件 | 职责 | 关键方法 |\n|------|------|----------|\n| 记忆编码 | 将观察和经验转化为可存储的记忆 | `encode()`, `consolidate()` |\n| 检索引擎 | 基于向量和关键词的混合检索 | `recall()`, `recallStream()` |\n| 信任度管理 | 基于时间的衰减和证据强化 | `decay()`, `reinforce()` |\n| 矛盾处理 | 追踪竞争性记忆而非静默覆盖 | 资料来源：[src/audrey.ts:1-200]() |\n\n### 数据库层\n\n数据持久化采用双索引架构，同时支持 SQLite 原生查询和向量相似度检索。\n\n| 数据库 | 位置 | 用途 |\n|--------|------|------|\n| SQLite 主库 | `AUDREY_DATA_DIR/memory.db` | 结构化记忆存储 |\n| sqlite-vec | `AUDREY_DATA_DIR/vectors.db` | 向量嵌入索引 |\n\n> **重要**：SQLite 使用 WAL 模式但无咨询锁，多进程共享同一目录会产生写竞争。每个租户或代理必须设置独立的 `AUDREY_DATA_DIR`。\n\n资料来源：[src/db.ts:1-100]()\n\n### MCP 服务器\n\nMCP 服务器（`mcp-server/index.ts`）提供标准化的工具接口，使 Audrey 能以 stdio 模式与各类 AI 代理通信。\n\n**支持的 MCP 工具集**（共 20 个工具）：\n\n| 工具分类 | 工具名称 |\n|----------|----------|\n| 记忆操作 | `memory_encode`, `memory_recall`, `memory_snapshot` |\n| 安全防护 | `guard_preflight`, `guard_postflight` |\n| 管理功能 | `status`, `introspect`, `dream` |\n\nMCP 服务器通过以下步骤与代理集成：\n\n1. 解析命令行参数（host 类型、dry-run 模式等）\n2. 生成特定代理的配置文件\n3. 启动 stdio 连接循环\n4. 处理工具调用请求\n\n资料来源：[mcp-server/index.ts:1-150]()\n\n### REST API 服务器\n\nREST API 基于 Hono 框架构建，提供轻量级的 HTTP 接口。\n\n**可用路由**：\n\n| 方法 | 路径 | 功能 |\n|------|------|------|\n| `GET` | `/health` | 健康检查 |\n| `POST` | `/v1/encode` | 编码记忆 |\n| `POST` | `/v1/recall` | 检索相关记忆 |\n| `POST` | `/v1/capsule` | 获取回合级记忆包 |\n| `GET` | `/v1/status` | 获取系统状态 |\n\n**安全特性**：\n- 默认绑定 `127.0.0.1`，禁止非本地访问\n- 非环回地址必须提供 `AUDREY_API_KEY`\n- HTTP API Key 比较使用 `crypto.timingSafeEqual` 防止时序攻击\n\n资料来源：[src/routes.ts:1-100](), [src/server.ts:1-80]()\n\n## 记忆模型\n\nAudrey 实现了一套多维记忆模型，模拟人类记忆的复杂性。\n\n```mermaid\ngraph LR\n A[观察/交互] --> B[编码]\n B --> C[情景记忆]\n B --> D[语义记忆]\n B --> E[程序记忆]\n C --> F[信任度计算]\n D --> F\n E --> F\n F --> G{衰减/强化}\n G -->|高信任| H[长期记忆]\n G -->|低信任| I[遗忘]\n```\n\n### 记忆类型\n\n| 类型 | 说明 | 典型来源 |\n|------|------|----------|\n| 情景记忆 | 特定观察、工具结果、偏好、会话事实 | `direct-observation` |\n| 语义记忆 | 从重复证据中提取的固化原则 | `consolidated` |\n| 程序记忆 | 记住的行动方式、规避策略、验证方法 | `procedure` |\n\n### 信任度与衰减\n\n每条记忆关联一个信任度分数（0-1），通过以下公式计算：\n\n```\nnew_confidence = old_confidence + (evidence_weight * reinforcement_factor)\n```\n\n衰减采用半衰期模型：\n\n```\ndecayed = original * 0.5^(days_elapsed / half_life_days)\n```\n\n> 半衰期必须大于 0，否则抛出 `RangeError`。\n\n资料来源：[src/audrey.ts:200-350](), [src/impact.ts:50-120]()\n\n## 工作流程\n\n### Guard 循环（核心安全环）\n\n```mermaid\nsequenceDiagram\n participant Agent as AI 代理\n participant Guard as Audrey Guard\n participant Memory as 记忆存储\n participant User as 用户\n \n Agent->>Guard: 执行操作前请求\n Guard->>Memory: 检索相关记忆\n Memory-->>Guard: 历史经验和规则\n Guard->>Guard: 分析风险和矛盾\n Guard-->>Agent: allow / warn / block + 证据\n \n alt allow\n Agent->>User: 执行操作\n Agent->>Guard: 操作结果\n Guard->>Memory: 记录经验\n else warn\n Agent->>Agent: 显示警告给用户\n User-->>Agent: 确认/取消\n end\n```\n\n**Guard 命令行用法**：\n\n```bash\naudrey guard --tool Bash \"npm run deploy\"\naudrey guard --hook --fail-on-warn # MCP 钩子模式\n```\n\n资料来源：[mcp-server/index.ts:150-300]()\n\n### 记忆编码流程\n\n```mermaid\ngraph TD\n A[输入文本] --> B[生成 ULID]\n B --> C[计算向量嵌入]\n C --> D[情感分析]\n D --> E[检查矛盾]\n E --> F{发现矛盾?}\n F -->|是| G[标记为 disputed]\n F -->|否| H[正常状态]\n G --> I[存储记忆]\n H --> I\n I --> J[更新向量索引]\n J --> K[返回 memory_id]\n```\n\n记忆编码支持以下元数据：\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| `source` | string | 记忆来源（direct-observation, told-by-user 等） |\n| `tags` | string[] | 标签数组 |\n| `memory_type` | enum | episodic / semantic / procedural |\n| `private` | boolean | 是否私有（仅创建者可读） |\n\n资料来源：[src/audrey.ts:350-500]()\n\n### 检索流程\n\nAudrey 支持三种检索模式：\n\n| 模式 | 说明 | 性能 |\n|------|------|------|\n| `hybrid`（默认） | 向量 + FTS 混合检索 | 约 14.3ms p50 |\n| `vector` | 纯向量检索（绕过 FTS） | 更快 |\n\n**检索选项白名单**（HTTP API 强制校验）：\n\n- `query`、`limit`、`scope`\n- `tags`、`sources`（数组）\n- `after`、`before`（时间范围）\n- `retrieval`（hybrid/vector）\n\n资料来源：[src/routes.ts:50-150]()\n\n## 数据流与隐私\n\n### 工具调用脱敏\n\n在记录工具调用结果前，系统自动脱敏敏感信息：\n\n```typescript\nconst SENSITIVE_KEY_PATTERN = /(password|secret|api[_-]?key|token)$/i;\n```\n\n脱敏规则覆盖：\n- API 密钥和令牌\n- 密码和私钥\n- Bearer Token\n- AWS 密钥\n- JWT\n\n资料来源：[src/redact.ts:50-100]()\n\n### 私有记忆隔离\n\n私有记忆通过 `private: true` 标记，仅创建者 `agent` 可检索。HTTP API 的 `/v1/recall` 端点实施 ACL 检查，防止跨代理泄露。\n\n> 注意：`includePrivate: true` 不能通过 HTTP 请求体传入（安全修复 v0.22.0）。\n\n## 部署架构\n\n### 多租户隔离\n\n```mermaid\ngraph TB\n subgraph 主机 A\n A1[Agent 1]\n A2[AUDREY_DATA_DIR=/data/agent1]\n end\n \n subgraph 主机 B\n B1[Agent 2]\n B2[AUDREY_DATA_DIR=/data/agent2]\n end\n \n subgraph 主机 C\n C1[Agent 3]\n C2[AUDREY_DATA_DIR=/data/agent3]\n end\n \n A1 --> A2\n B1 --> B2\n C1 --> C2\n```\n\n### 环境变量配置\n\n| 变量 | 默认值 | 说明 |\n|------|--------|------|\n| `AUDREY_DATA_DIR` | `./audrey-data` | 数据存储目录 |\n| `AUDREY_API_KEY` | unset | 非本地访问的 Bearer 令牌 |\n| `AUDREY_HOST` | `127.0.0.1` | REST 服务绑定地址 |\n| `AUDREY_ENABLE_ADMIN_TOOLS` | `0` | 启用导出/导入/遗忘工具 |\n| `AUDREY_CONTEXT_BUDGET_CHARS` | `4000` | 记忆胶囊默认字符预算 |\n| `AUDREY_DEBUG` | `0` | 打印 MCP 调试日志 |\n\n### 启动方式\n\n| 方式 | 命令 | 用途 |\n|------|------|------|\n| MCP stdio | `npx audrey` | 直接集成 AI 代理 |\n| REST 服务 | `npx audrey serve` | 供 Python SDK 或外部调用 |\n| CLI 工具 | `npx audrey guard ...` | 终端手动检查 |\n\n## 规则编译与推广\n\n当需要将记忆固化为持久规则时，Audrey 提供规则编译功能：\n\n```mermaid\ngraph LR\n A[PromotionCandidate] --> B[规则编译]\n B --> C[Markdown 文件]\n C --> D[.claude/rules/]\n D --> E[Claude Code 提示]\n```\n\n规则文件格式：\n```markdown\n---\ntitle: \"警告：高风险操作\"\nsource_memory_ids: [\"01AR...\",\"01AS...\"]\nconfidence: 0.85\nevidence_count: 5\npromoted_at: \"2024-01-15T10:30:00Z\"\n---\n\n内容正文...\n```\n\n资料来源：[src/rules-compiler.ts:1-100]()\n\n## 影响评估\n\nAudrey 提供 `impact` 命令分析记忆库的健康状态：\n\n| 指标 | 说明 |\n|------|------|\n| `validatedTotal` | 经过验证的记忆总数 |\n| `validatedInWindow` | 时间窗口内的验证记忆 |\n| `outcomeBreakdownInWindow` | 近期操作结果分布（helpful/wrong/used） |\n| `topUsed` | 高频使用记忆 |\n| `weakest` | 信任度最低的记忆 |\n\n资料来源：[src/impact.ts:100-200]()\n\n## 扩展阅读\n\n- [快速开始指南](../guides/getting-started.md)\n- [Guard 循环详解](../guides/guard-loop.md)\n- [Python SDK 文档](../python/README.md)\n- [CLI 命令参考](../cli/commands.md)\n\n---\n\n\n\n## 记忆模型\n\n### 相关页面\n\n相关主题：[系统架构](#page-system-architecture), [Audrey Guard 安全循环](#page-audrey-guard), [数据存储](#page-data-storage)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/Evilander/Audrey/blob/main/README.md)\n- [src/impact.ts](https://github.com/Evilander/Audrey/blob/main/src/impact.ts)\n- [src/routes.ts](https://github.com/Evilander/Audrey/blob/main/src/routes.ts)\n- [src/capsule.ts](https://github.com/Evilander/Audrey/blob/main/src/capsule.ts)\n- [src/promote.ts](https://github.com/Evilander/Audrey/blob/main/src/promote.ts)\n- [src/redact.ts](https://github.com/Evilander/Audrey/blob/main/src/redact.ts)\n \n\n# 记忆模型\n\n## 概述\n\nAudrey 的记忆模型是一个专为 AI 代理设计的本地优先记忆防火墙，旨在解决代理\"遗忘昨日错误\"的核心问题。该模型通过多层次、可验证的记忆系统，使代理能够在执行操作前检查相关记忆，从而避免重复犯错、保持项目特定规则的连续性。资料来源：[README.md](https://github.com/Evilander/Audrey/blob/main/README.md)\n\n## 核心架构\n\nAudrey 记忆模型采用三层记忆架构，结合情感权重和干扰衰减机制，形成一个动态、可自适应的记忆系统。\n\n```mermaid\ngraph TD\n A[用户交互/工具执行] --> B[事件编码]\n B --> C{记忆类型分类}\n C --> D[情节记忆
Episodic]\n C --> E[语义记忆
Semantic]\n C --> F[程序记忆
Procedural]\n D --> G[记忆存储]\n E --> G\n F --> G\n G --> H[检索系统]\n H --> I{mood 影响}\n H --> J{干扰检测}\n H --> K{衰减处理}\n I --> L[最终检索结果]\n J --> L\n K --> L\n L --> M[Preflight 检查]\n M --> N{allow/warn/block}\n```\n\n## 记忆类型体系\n\nAudrey 将记忆划分为三种核心类型，每种类型具有不同的生命周期和用途。\n\n### 情节记忆 (Episodic Memory)\n\n情节记忆记录特定的观察结果、工具执行结果、用户偏好和会话事实。它是系统获取新知识的主要入口，通常来源于直接观察或用户告知。资料来源：[README.md](https://github.com/Evilander/Audrey/blob/main/README.md)\n\n| 属性 | 说明 |\n|------|------|\n| 内容 | 具体的观察、事件、偏好 |\n| 来源 | direct-observation、told-by-user |\n| 状态 | 活跃/已验证/已衰减 |\n| 置信度 | 基于证据数量和支持度计算 |\n\n### 语义记忆 (Semantic Memory)\n\n语义记忆是从重复证据中提炼出的巩固原则。它代表了系统经过验证的核心信念，要求更高的置信度门槛才能晋升为语义记忆。资料来源：[README.md](https://github.com/Evilander/Audrey/blob/main/README.md)\n\n语义记忆的晋升条件：\n\n```typescript\n// 资料来源：src/promote.ts\nif (evidence < Math.max(minEvidence, 3)) continue;\nif ((row.contradicting_count ?? 0) > 0) continue;\n```\n\n晋升要求：\n- 至少 3 条证据支持\n- 无矛盾证据记录\n- 状态为活跃 (active)\n\n### 程序记忆 (Procedural Memory)\n\n程序记忆记录\"如何行动、如何避免、如何重试、如何验证\"的具体步骤。它直接关联工具使用和操作流程。资料来源：[README.md](https://github.com/Evilander/Audrey/blob/main/README.md)\n\n程序记忆的晋升条件相对宽松，关注实用性：\n\n```typescript\n// 资料来源：src/promote.ts\nif ((row.failure_prevented ?? 0) > 0) {\n reasonParts.push(`${row.failure_prevented} failure prevented`);\n}\nif ((row.usage_count ?? 0) > 0) {\n reasonParts.push(`used ${row.usage_count} time(s)`);\n}\n```\n\n## 置信度与强化机制\n\n### 置信度计算\n\nAudrey 使用基于证据和支持度的置信度计算模型，通过 `confidence.ts` 模块实现强化公式。\n\n```mermaid\ngraph LR\n A[新证据] --> B{证据类型}\n B -->|支持性| C[supporting_count++]\n B -->|矛盾性| D[contradicting_count++]\n C --> E[置信度计算]\n D --> E\n E --> F{salience 更新}\n```\n\n### 强化反馈循环\n\nAudrey 实现了闭环反馈机制，通过 `memory_validate` 工具收集用户反馈并调整记忆权重。\n\n| 反馈结果 | 语义记忆影响 | 程序记忆影响 |\n|----------|--------------|--------------|\n| helpful | salience↑, retrieval_count↑ | salience↑ |\n| wrong | salience↓, challenge_count↑ | salience↓ |\n| used | 较小 salience 增量 | salience 增量 |\n\n资料来源：[CHANGELOG.md](https://github.com/Evilander/Audrey/blob/main/CHANGELOG.md)\n\n## 情感与显著性系统\n\n### 情感影响 (Affect)\n\n情感影响基于记忆的情感权重和唤醒度 (arousal)，影响检索结果的排序和优先级。\n\n```typescript\n// 资料来源：src/capsule.ts\nif (trustedControlSource && hashMatchesAny(lowerTags, MUST_FOLLOW_TAGS)) {\n sections.add('must_follow');\n}\n\nif (result.source === 'told-by-user') {\n sections.add('user_preferences');\n}\n```\n\n### 显著性 (Salience)\n\n显著性决定记忆在检索时的权威程度，受以下因素影响：\n\n- 使用频率 (usage_count)\n- 上次使用时间 (last_used_at)\n- 证据强度 (evidence_count)\n- 情感权重\n\n资料来源：[src/impact.ts](https://github.com/Evilander/Audrey/blob/main/src/impact.ts)\n\n## 干扰与衰减机制\n\n### 干扰检测 (Interference)\n\n当存在相互矛盾的证据时，系统不会静默覆盖，而是跟踪这些矛盾状态。资料来源：[README.md](https://github.com/Evilander/Audrey/blob/main/README.md)\n\n```mermaid\ngraph TD\n A[新记忆] --> B{与现有记忆冲突?}\n B -->|是| C[标记为 disputed]\n B -->|否| D[正常存储]\n C --> E[跟踪矛盾证据]\n E --> F[保留双方记录]\n D --> G[更新支持度]\n```\n\n### 衰减处理 (Decay)\n\n陈旧、冲突或低置信度的记忆会随时间降低权威性，确保最新、最准确的信息占据主导地位。资料来源：[README.md](https://github.com/Evilander/Audrey/blob/main/README.md)\n\n衰减考虑因素：\n- 时间间隔（半衰期）\n- 检索频率\n- 矛盾证据数量\n- 最后强化时间\n\n## 记忆胶囊 (Memory Capsule)\n\n记忆胶囊是一种 turn-sized 的记忆数据包，用于在特定上下文中快速获取相关记忆。\n\n### 胶囊分段\n\n```typescript\n// 资料来源：src/capsule.ts\nconst sections = new Set();\n\nif (trustedControlSource && hashMatchesAny(lowerTags, MUST_FOLLOW_TAGS)) {\n sections.add('must_follow');\n}\n\nif (hashMatchesAny(lowerTags, RISK_TAGS)) {\n sections.add('risks');\n}\n\nif (entry.memory_type === 'procedural') {\n sections.add('procedures');\n}\n\nif (result.confidence < 0.55) {\n sections.add('uncertain_or_disputed');\n}\n```\n\n### 胶囊分区表\n\n| 分区名称 | 触发条件 |\n|----------|----------|\n| must_follow | 可信来源 + 必须遵循标签 |\n| risks | 包含风险标签 |\n| procedures | 程序记忆类型或程序标签 |\n| user_preferences | 用户偏好标签或 told-by-user 来源 |\n| recent_changes | 最近时间窗口内的更新 |\n| uncertain_or_disputed | 争议状态或低置信度 (<0.55) |\n| project_facts | 默认语义/情节记忆 |\n\n## 记忆验证流程\n\n### Preflight 检查\n\n在执行工具操作前，系统执行预检查以确保行动的安全性。\n\n```mermaid\ngraph TD\n A[工具调用请求] --> B[检索相关记忆]\n B --> C{检查失败历史}\n B --> D{检查风险标记}\n B --> E{检查相关规则}\n B --> F{检查验证程序}\n C --> G{决策生成}\n D --> G\n E --> G\n F --> G\n G --> H{allow/warn/block}\n```\n\n### 验证反馈\n\n验证结果通过 REST API 端点收集：\n\n| 端点 | 用途 | 参数 |\n|------|------|------|\n| POST /v1/validate | 标准验证 | id, outcome |\n| POST /v1/mark-used | 遗留别名 | memory_id, outcome |\n\n资料来源：[CHANGELOG.md](https://github.com/Evilander/Audrey/blob/main/CHANGELOG.md)\n\n## 规则晋升系统\n\n高质量的程序记忆和语义记忆可以被晋升为可执行的规则文件。\n\n### 晋升条件对比\n\n| 条件 | 程序记忆 | 语义记忆 |\n|------|----------|----------|\n| 证据数量 | ≥1 | ≥3 |\n| 失败预防数 | >0 或使用次数 >0 | - |\n| 矛盾限制 | 无限制 | 必须为 0 |\n| 晋升目标 | .claude/rules/*.md | .claude/rules/*.md |\n\n资料来源：[src/promote.ts](https://github.com/Evilander/Audrey/blob/main/src/promote.ts)\n\n### 规则编译\n\n规则文件包含 YAML front matter，记录来源记忆 ID、置信度、证据数量等信息。\n\n```typescript\n// 资料来源：src/rules-compiler.ts\nexport interface RuleDoc {\n title: string;\n slug: string;\n relativePath: string;\n body: string;\n frontmatter: Record;\n}\n```\n\n## 记忆数据模型\n\n### 数据库存储\n\nAudrey 使用 SQLite 作为本地存储，结合 sqlite-vec 支持向量检索。\n\n```sql\n-- 情节记忆表结构（示意）\nCREATE TABLE episodes (\n id TEXT PRIMARY KEY,\n content TEXT NOT NULL,\n source TEXT,\n state TEXT DEFAULT 'active',\n salience REAL,\n usage_count INTEGER DEFAULT 0,\n created_at TEXT,\n last_used_at TEXT\n);\n\n-- 语义记忆表结构（示意）\nCREATE TABLE semantics (\n id TEXT PRIMARY KEY,\n content TEXT NOT NULL,\n state TEXT DEFAULT 'active',\n evidence_count INTEGER DEFAULT 0,\n supporting_count INTEGER DEFAULT 0,\n contradicting_count INTEGER DEFAULT 0,\n confidence REAL,\n salience REAL,\n created_at TEXT\n);\n```\n\n### 检索模式\n\n| 模式 | 描述 | 性能特点 |\n|------|------|----------|\n| hybrid | 混合检索（向量 + 全文） | 默认模式，平衡精度与召回 |\n| vector | 仅向量检索 | FTS 旁路快速路径 |\n\n资料来源：[CHANGELOG.md](https://github.com/Evilander/Audrey/blob/main/CHANGELOG.md)\n\n## 私有记忆与访问控制\n\n### 隐私隔离\n\nHTTP `/v1/recall` 和 `/v1/capsule` 不再将调用者选项体传播到 `audrey.recall()`，防止通过 HTTP 请求绕过私有记忆 ACL。资料来源：[CHANGELOG.md](https://github.com/Evilander/Audrey/blob/main/CHANGELOG.md)\n\n### 选项白名单\n\n```typescript\n// 资料来源：src/routes.ts\nconst ALLOWED_KEYS: Set = new Set([\n 'limit', 'offset', 'agent', 'tags', 'sources',\n 'after', 'before', 'context', 'mood', 'retrieval', 'scope'\n]);\n```\n\n## 安全机制\n\n### 敏感信息脱敏\n\n```typescript\n// 资料来源：src/redact.ts\nconst SENSITIVE_KEY_PATTERN = /(^|_|-)(password|passwd|pwd|secret|api[_-]?key|auth[_-]?token|bearer[_-]?token|...)$/i;\n```\n\n脱敏状态：\n- `clean` - 无敏感信息\n- `redacted` - 已脱敏\n\n## 影响统计与监控\n\n### 记忆统计接口\n\n```typescript\n// 资料来源：src/impact.ts\ninterface ImpactReport {\n generatedAt: string;\n windowDays: number;\n totals: {\n episodic: number;\n semantic: number;\n procedural: number;\n };\n validatedTotal: number;\n validatedInWindow: number;\n byType: {\n episodic: { validated: number; recent: number };\n semantic: { validated: number; recent: number; challenged: number };\n procedural: { validated: number; recent: number };\n };\n outcomeBreakdownInWindow: {\n helpful: number;\n wrong: number;\n used: number;\n };\n topUsed: MemoryRow[];\n weakest: MemoryRow[];\n recentActivity: MemoryRow[];\n}\n```\n\n## 梦 Consolidation\n\n`audrey dream` 命令执行记忆巩固和衰减处理，将情节记忆合并为原则并应用衰减机制。资料来源：[README.md](https://github.com/Evilander/Audrey/blob/main/README.md)\n\n建议按计划运行以保持巩固和衰减的最新状态。\n\n## 环境变量配置\n\n| 变量 | 默认值 | 用途 |\n|------|--------|------|\n| AUDREY_DATA_DIR | - | 租户/环境数据目录 |\n| AUDREY_EMBEDDING_PROVIDER | - | 嵌入提供商 |\n| AUDREY_LLM_PROVIDER | - | LLM 提供商 |\n| AUDREY_API_KEY | - | API 密钥认证 |\n\n资料来源：[README.md](https://github.com/Evilander/Audrey/blob/main/README.md)\n\n---\n\n\n\n## Audrey Guard 安全循环\n\n### 相关页面\n\n相关主题：[记忆模型](#page-memory-model), [MCP集成](#page-mcp-integration), [REST API](#page-rest-api), [CLI工具](#page-cli-tools)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/preflight.ts](https://github.com/Evilander/Audrey/blob/main/src/preflight.ts)\n- [src/reflexes.ts](https://github.com/Evilander/Audrey/blob/main/src/reflexes.ts)\n- [src/redact.ts](https://github.com/Evilander/Audrey/blob/main/src/redact.ts)\n- [src/feedback.ts](https://github.com/Evilander/Audrey/blob/main/src/feedback.ts)\n- [src/action-key.ts](https://github.com/Evilander/Audrey/blob/main/src/action-key.ts)\n- [mcp-server/index.ts](https://github.com/Evilander/Audrey/blob/main/mcp-server/index.ts)\n- [src/capsule.ts](https://github.com/Evilander/Audrey/blob/main/src/capsule.ts)\n- [src/impact.ts](https://github.com/Evilander/Audrey/blob/main/src/impact.ts)\n \n\n# Audrey Guard 安全循环\n\nAudrey Guard 是 Audrey 项目中的核心安全机制，为 AI Agent 提供内存优先的动作检查能力。在 Agent 执行任何工具调用之前，Guard 会查询持久化记忆，评估潜在风险，并根据历史经验返回允许、警告或阻止的决策。\n\n## 核心概念\n\n### 安全循环的工作原理\n\nAudrey Guard 采用**记录-记忆-检查-响应-验证**的闭环设计：\n\n1. **记忆编码** (`memory_encode`): 将 Agent 的操作经验、错误教训、项目规则编码存储\n2. **预检执行** (`memory_preflight`): 动作执行前查询相关记忆，评估风险等级\n3. **决策返回**: 输出 `allow`（允许）、`warn`（警告）或 `block`（阻止）决策\n4. **反射生成** (`memory_reflexes`): 将记忆证据转换为可执行的触发-响应指导\n5. **反馈验证** (`memory_validate`): 动作完成后收集结果，更新记忆权重\n\n```mermaid\ngraph TD\n A[Agent 工具调用请求] --> B[memory_preflight 预检]\n B --> C{查询记忆数据库}\n C --> D[评估风险与规则匹配]\n D --> E{风险等级判断}\n E -->|低风险| F[allow 允许]\n E -->|中风险| G[warn 警告 + 证据]\n E -->|高风险| H[block 阻止]\n F --> I[执行工具]\n G --> I\n H --> J[终止执行]\n I --> K[memory_validate 验证结果]\n K --> L[更新 salience 与 confidence]\n K --> M[反馈循环: helpful/used/wrong]\n```\n\n资料来源：[mcp-server/index.ts:58-75]()\n\n### 决策类型\n\n| 决策类型 | 含义 | 触发条件 |\n|---------|------|---------|\n| `allow` | 允许执行 | 无历史风险记忆、规则验证通过 |\n| `warn` | 带警告执行 | 存在低置信风险记忆、需要人工确认 |\n| `block` | 阻止执行 | 存在高风险记忆、规则明确禁止、重复失败 |\n\n资料来源：[mcp-server/index.ts:58-65]()\n\n## 预检系统 (Preflight)\n\n预检是 Guard 的核心检查模块，在动作执行前全面评估各种风险因素。\n\n### 检查维度\n\n`memory_preflight` 从多个维度进行综合评估：\n\n```typescript\ninterface PreflightOptions {\n tool: string; // 工具名称\n action?: string; // 具体动作描述\n sessionId?: string; // 会话标识\n mode?: 'normal' | 'strict'; // 检查严格程度\n failure_window_hours?: number; // 失败历史时间窗口\n recent_failure_window_hours?: number; // 最近失败窗口\n recent_change_window_hours?: number; // 最近变更窗口\n}\n```\n\n资料来源：[src/routes.ts:23-36]()\n\n### Memory Capsule 预检内容\n\n预检返回的 Memory Capsule 包含结构化的记忆分段：\n\n```mermaid\ngraph LR\n A[查询结果] --> B[recent_changes 近期变更]\n A --> C[must_follow 强制规则]\n A --> D[procedures 流程规范]\n A --> E[risks 风险提示]\n A --> F[user_preferences 用户偏好]\n A --> G[uncertain_or_disputed 不确定信息]\n A --> H[project_facts 项目事实]\n```\n\n资料来源：[src/capsule.ts:35-60]()\n\n### 风险标签系统\n\n预检模块使用标签系统标记不同类型的风险记忆：\n\n| 标签类型 | 标签值 | 记忆分段归属 |\n|---------|--------|------------|\n| 强制规则 | `MUST_FOLLOW_TAGS` | `must_follow` |\n| 风险警告 | `RISK_TAGS` | `risks` |\n| 流程规范 | `PROCEDURE_TAGS` | `procedures` |\n| 用户偏好 | `PREFERENCE_TAGS` | `user_preferences` |\n| 低置信 | `confidence < 0.55` | `uncertain_or_disputed` |\n\n资料来源：[src/capsule.ts:62-85]()\n\n### 近期失败检测\n\n预检自动查询最近 7 天内的工具失败记录，识别反复出现的错误模式：\n\n```typescript\nconst failures = recentFailures(db, {\n since: new Date(Date.now() - 7 * 24 * 60 * 60 * 1000).toISOString(),\n limit: 5\n});\n```\n\n这些失败记录会自动添加到 Capsule 的 `risks` 分段，作为动作前的警告依据。\n\n资料来源：[src/capsule.ts:52-56]()\n\n## 反射机制 (Reflexes)\n\n`memory_reflexes` 是 Audrey Guard 的触发-响应转换层，将历史记忆转化为 Agent 可直接执行的指导规则。\n\n### 反射生成流程\n\n```mermaid\ngraph TD\n A[记忆事件] --> B[提取证据内容]\n B --> C[识别触发条件]\n C --> D[生成响应规则]\n D --> E[格式化为 Markdown]\n E --> F[添加 YAML 前置元数据]\n F --> G[持久化到规则文件]\n```\n\n### 规则文件结构\n\nAudrey 将反射规则存储为 Markdown 文件，包含 YAML 前置元数据：\n\n```yaml\n---\nmemory_ids: [mem_xxx123, mem_xxx456]\nconfidence: 0.85\nevidence_count: 3\npromoted_at: \"2024-01-15T10:30:00Z\"\n---\n```\n\n资料来源：[src/rules-compiler.ts:1-30]()\n\n### 标题与 Slug 生成\n\n规则编译器使用停用词过滤生成可读的 slug：\n\n```typescript\nconst STOP_WORDS = new Set(['the', 'a', 'an', 'is', 'of', 'and', 'or', 'to', 'for', 'with', 'on', 'at', 'by', 'in', 'as']);\n\nfunction slugifyTitle(title: string): string {\n const words = lowered.split(/[^a-z0-9]+/).filter(w => w && !STOP_WORDS.has(w));\n return words.slice(0, 6).join('-');\n}\n```\n\n资料来源：[src/rules-compiler.ts:23-27]()\n\n## 数据脱敏 (Redaction)\n\nGuard 在记录工具输入输出时自动执行敏感数据脱敏，防止凭证和密钥被永久存储。\n\n### 敏感字段检测\n\n```typescript\nconst SENSITIVE_KEY_PATTERN = /(^|_|-)(password|passwd|pwd|secret|api[_-]?key|auth[_-]?token|bearer[_-]?token|access[_-]?token|refresh[_-]?token|client[_-]?secret|private[_-]?key|session[_-]?token|jwt|aws[_-]?secret|token)$/i;\n```\n\n资料来源：[src/redact.ts:35-36]()\n\n### 脱敏操作\n\n| 操作类型 | 脱敏内容 | 输出格式 |\n|---------|---------|---------|\n| JSON 键值对 | 匹配模式的键名 | `[REDACTED:api_key]` |\n| 明文密钥 | 常见密钥格式 | `[REDACTED:token]` |\n| Bearer Token | Authorization 头 | `[REDACTED:bearer]` |\n\n资料来源：[src/redact.ts:38-60]()\n\n### 脱敏状态\n\n脱敏结果包含状态标识：\n\n```typescript\ninterface RedactionResult {\n text: string; // 脱敏后的文本\n redactions: RedactionHit[]; // 脱敏操作记录\n state: 'clean' | 'redacted'; // 整体状态\n}\n```\n\n## 反馈验证 (Feedback)\n\n`memory_validate` 关闭安全循环的最后一步，通过收集执行结果反馈来更新记忆权重。\n\n### 结果类型\n\n| 结果类型 | 含义 | 权重影响 |\n|---------|------|---------|\n| `helpful` | 记忆有帮助 | salience + |\n| `used` | 记忆被使用 | usage_count + |\n| `wrong` | 记忆有误 | salience - |\n\n资料来源：[src/impact.ts:25-35]()\n\n### 反馈数据结构\n\n```typescript\ninterface EventOutcome {\n helpful?: number;\n used?: number;\n wrong?: number;\n // 或通过证据反馈映射\n evidence_feedback?: Record;\n}\n```\n\n### Impact 追踪\n\nAudrey 维护全局的 Impact 指标，用于评估记忆系统的实际效果：\n\n```typescript\ninterface ImpactReport {\n windowDays: number;\n totals: {\n episodic: number; // 情景记忆总数\n semantic: number; // 语义记忆总数\n procedural: number; // 流程记忆总数\n };\n validatedTotal: number; // 已验证记忆数\n validatedInWindow: number; // 窗口内验证数\n topUsed: MemoryEntry[]; // 高使用频率记忆\n weakest: MemoryEntry[]; // 低权重记忆\n recentActivity: MemoryEntry[]; // 近期活动\n}\n```\n\n资料来源：[src/impact.ts:40-60]()\n\n## CLI 命令行接口\n\n### guard 命令\n\n```bash\nnpx audrey guard --tool Bash \"npm run deploy\"\n```\n\n### 命令行参数\n\n| 参数 | 说明 | 示例 |\n|-----|------|-----|\n| `--tool` | 工具名称 | `--tool Bash` |\n| `--hook` | Hook 模式 | `--hook` |\n| `--fail-on-warn` | 警告时失败 | `--fail-on-warn` |\n| `--explain` | 显示决策证据 | `--explain` |\n| `--strict` | 严格模式 | `--strict` |\n| `--include-capsule` | 包含完整 Capsule | `--include-capsule` |\n| `--json` | JSON 输出格式 | `--json` |\n\n资料来源：[mcp-server/index.ts:40-55]()\n\n## 安全考虑\n\n### API 密钥保护\n\nHTTP API 的密钥比较使用时序安全比较，防止时序攻击：\n\n```typescript\ncrypto.timingSafeEqual(\n Buffer.from(providedKey),\n Buffer.from(expectedKey)\n);\n```\n\n资料来源：[mcp-server/index.ts:180-185]()\n\n### 非本地绑定限制\n\nAudrey 默认绑定到 `127.0.0.1`，拒绝在非本地地址启动而不设置 API Key：\n\n```typescript\nconst isLoopback = serveHost === '127.0.0.1' || serveHost === '::1';\nif (!isLoopback && !serveAuth && !serveAllowNoAuth) {\n // 拒绝启动并给出错误提示\n}\n```\n\n资料来源：[mcp-server/index.ts:195-205]()\n\n### 规则文件写入限制\n\n`audrey promote` 命令拒绝写入非工作目录的规则文件，防止提示注入攻击：\n\n```bash\nAUDREY_PROMOTE_ROOTS=/path/to/trusted:d:/trusted audrey promote --yes\n```\n\n资料来源：[CHANGELOG.md:28-30]()\n\n## 集成方式\n\n### Claude Code 集成\n\n```bash\nnpx audrey install --host claude-code\n```\n\n安装后会在 Claude Code 设置中添加 PreToolUse 钩子，自动执行 `audrey guard --hook --fail-on-warn`。\n\n### MCP 服务器模式\n\nAudrey 作为 MCP 服务器运行，支持 stdio 通信：\n\n```bash\nnpx audrey serve\n```\n\n服务器暴露 `/v1/preflight`、`/v1/validate` 等 REST 端点。\n\n### Python SDK 集成\n\n```python\nfrom audrey_memory import Audrey\n\nbrain = Audrey(base_url=\"http://127.0.0.1:7437\", agent=\"my-agent\")\n\n# 预检动作\nresult = brain.preflight(\n tool=\"Bash\",\n action=\"npm run deploy\"\n)\n\nif result.decision == \"block\":\n print(\"动作被阻止:\", result.evidence)\n```\n\n## 总结\n\nAudrey Guard 通过五层闭环机制为 AI Agent 提供可靠的安全防护：\n\n1. **预检层**: 动作执行前的多维度风险评估\n2. **反射层**: 历史经验转化为可执行规则\n3. **脱敏层**: 敏感数据的自动保护\n4. **验证层**: 执行结果的反馈收集\n5. **权重层**: 记忆权重的动态调整\n\n这种设计使 Agent 能够从历史错误中学习，在重复操作前获得警告，最终实现真正的\"记忆驱动的智能代理\"。\n\n---\n\n*本页面基于 Audrey 源码生成，最后更新对应仓库 commit: master 分支。*\n\n---\n\n\n\n## 数据存储\n\n### 相关页面\n\n相关主题：[系统架构](#page-system-architecture), [记忆模型](#page-memory-model)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/Evilander/Audrey/blob/main/README.md)\n- [src/impact.ts](https://github.com/Evilander/Audrey/blob/main/src/impact.ts)\n- [src/routes.ts](https://github.com/Evilander/Audrey/blob/main/src/routes.ts)\n- [src/capsule.ts](https://github.com/Evilander/Audrey/blob/main/src/capsule.ts)\n- [CHANGELOG.md](https://github.com/Evilander/Audrey/blob/main/CHANGELOG.md)\n- [python/README.md](https://github.com/Evilander/Audrey/blob/main/python/README.md)\n \n\n# 数据存储\n\nAudrey 的数据存储层是整个本地优先记忆防火墙的核心基础设施。它采用 SQLite 作为主数据库，结合 sqlite-vec 扩展实现向量检索功能，为 AI 代理提供持久化、可查询的记忆存储能力。\n\n## 存储架构概述\n\nAudrey 采用单文件本地数据库架构，所有记忆数据存储在 SQLite 数据库中，无需外部托管数据库服务。这种设计确保了：\n\n- **数据主权**：所有数据保留在本地文件系统\n- **零依赖**：不依赖 PostgreSQL、Redis 等外部服务\n- **便携性**：通过备份整个数据目录即可迁移整个记忆状态\n- **事务完整性**：SQLite 的 ACID 特性保证数据一致性\n\n资料来源：[README.md:1-30]()\n\n```mermaid\ngraph TD\n A[Audrey Server] --> B[SQLite 数据库]\n A --> C[sqlite-vec 向量索引]\n B --> D[episodic_memory 表]\n B --> E[semantic_memory 表]\n B --> F[procedural_memory 表]\n B --> G[memory_events 表]\n C --> H[向量嵌入存储]\n```\n\n## 数据库文件位置\n\n默认情况下，Audrey 将数据存储在 `$PWD/.audrey/audrey.db` 目录中，即当前工作目录下的隐藏文件夹内。通过环境变量可以自定义数据目录位置：\n\n| 环境变量 | 默认值 | 说明 |\n|---------|--------|------|\n| `AUDREY_DATA_DIR` | `$PWD/.audrey` | 数据库文件所在目录路径 |\n\n```bash\n# 示例：指定自定义数据目录\nAUDREY_DATA_DIR=/home/user/.audrey-staging npx audrey serve\n```\n\n资料来源：[README.md:环境变量部分]()\n\n## 数据库表结构\n\nAudrey 的记忆模型通过三个核心表实现，分别对应不同的记忆类型：\n\n### 情景记忆表 (episodic_memory)\n\n存储具体的观察结果、工具执行结果、用户偏好和会话事实。\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| id | TEXT | 主键，ULID 格式 |\n| content | TEXT | 记忆内容文本 |\n| embedding | BLOB | 向量嵌入数据 |\n| confidence | REAL | 置信度分数 (0-1) |\n| source | TEXT | 来源类型 (direct-observation, tool-result, user-feedback) |\n| tags | TEXT | 逗号分隔的标签列表 |\n| agent | TEXT | 关联的代理标识 |\n| state | TEXT | 状态 (active, decayed, challenged, disputed) |\n| created_at | TEXT | ISO 时间戳 |\n| last_used_at | TEXT | 上次使用时间 |\n| usage_count | INTEGER | 使用次数统计 |\n\n资料来源：[src/impact.ts:1-50]()\n\n### 语义记忆表 (semantic_memory)\n\n存储从重复证据中提取的巩固原则和规则。\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| id | TEXT | 主键 |\n| content | TEXT | 原则内容 |\n| embedding | BLOB | 向量嵌入 |\n| confidence | REAL | 置信度 |\n| evidence_count | INTEGER | 支持证据数量 |\n| challenged | INTEGER | 是否被质疑标记 |\n| created_at | TEXT | 创建时间 |\n\n### 程序记忆表 (procedural_memory)\n\n存储执行操作的已知方式、避免事项、重试策略和验证方法。\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| id | TEXT | 主键 |\n| content | TEXT | 程序步骤内容 |\n| embedding | BLOB | 向量嵌入 |\n| confidence | REAL | 置信度 |\n| trigger_conditions | TEXT | 触发条件表达式 |\n| created_at | TEXT | 创建时间 |\n\n### 记忆事件表 (memory_events)\n\n审计日志表，记录所有记忆相关的操作事件。\n\n```typescript\n// 事件类型包括:\n// - encode: 新记忆编码\n// - recall: 记忆检索\n// - feedback: 反馈更新\n// - consolidate: 记忆巩固\n// - decay: 记忆衰减\n// - promote: 记忆提升为规则\n// - forget: 记忆遗忘\n```\n\n资料来源：[src/capsule.ts:1-30]()\n\n## 向量检索配置\n\nAudrey 使用 sqlite-vec 扩展提供向量相似度搜索能力。向量检索支持两种模式：\n\n| 检索模式 | 说明 | 适用场景 |\n|----------|------|----------|\n| `hybrid` (默认) | 结合向量相似度和全文搜索的混合检索 | 平衡精度和召回率 |\n| `vector` | 仅使用向量相似度搜索 | 快速精确匹配，跳过 FTS |\n\n```typescript\n// 检索选项配置\ninterface RecallOptions {\n query: string; // 检索查询文本\n limit?: number; // 返回结果数量限制\n tags?: string[]; // 标签过滤\n sources?: string[]; // 来源类型过滤\n after?: string; // 时间范围起点 (ISO 格式)\n before?: string; // 时间范围终点\n scope?: 'shared' | 'agent'; // 共享记忆或代理专属记忆\n retrieval?: 'hybrid' | 'vector'; // 检索模式选择\n context?: Record; // 上下文参数\n mood?: RecallOptions['mood']; // 情感/优先级配置\n}\n```\n\n资料来源：[src/routes.ts:1-30]()\n\n## 数据库性能优化\n\n### PRAGMA 配置\n\nAudrey 对 SQLite 进行了性能调优配置：\n\n| PRAGMA 设置 | 说明 |\n|-------------|------|\n| `journal_mode = WAL` | 启用 WAL 模式，提高并发读写性能 |\n| `synchronous = NORMAL` | 平衡安全性和写入性能 |\n| `cache_size` | 增大缓存减少磁盘 IO |\n| `mmap_size` | 启用内存映射加速读取 |\n\n如需恢复默认配置：\n\n```bash\nAUDREY_PRAGMA_DEFAULTS=0 npx audrey serve\n```\n\n资料来源：[README.md:环境变量部分]()\n\n### 嵌入预热\n\n首次启动时，Audrey 会进行嵌入模型预热以加速后续操作：\n\n```\n冷启动首次编码: 525ms → 预热后: 28ms (约18.7倍提升)\n```\n\n| 环境变量 | 默认值 | 说明 |\n|---------|--------|------|\n| `AUDREY_DISABLE_WARMUP` | `0` | 设为 `1` 可跳过嵌入预热 |\n\n资料来源：[CHANGELOG.md:0.22.0 性能部分]()\n\n## 数据备份与恢复\n\n### 手动备份\n\n由于所有数据存储在单一数据库文件，备份非常简单：\n\n```bash\n# 停止服务后复制数据库目录\ncp -r .audrey .audrey.backup-$(date +%Y%m%d)\n```\n\n### 快照导出与恢复\n\nAudrey 支持生成和恢复记忆快照：\n\n```python\nfrom audrey_memory import Audrey\n\nbrain = Audrey(base_url=\"http://127.0.0.1:7437\", api_key=\"secret\")\n\n# 创建快照\nsnapshot = brain.snapshot()\n\n# 恢复到新的空存储\nrestore_target = Audrey(base_url=\"http://127.0.0.1:7437\", api_key=\"secret\")\nrestore_target.restore(snapshot)\nrestore_target.close()\n```\n\n**注意**：快照只能恢复到空的存储中。建议使用新的 `AUDREY_DATA_DIR` 目录作为恢复目标。\n\n资料来源：[python/README.md:1-50]()\n\n## 数据隔离与多租户\n\nAudrey 通过数据目录实现租户隔离：\n\n| 策略 | 配置方式 |\n|------|----------|\n| 按租户隔离 | 每个租户设置独立的 `AUDREY_DATA_DIR` |\n| 按环境隔离 | 开发/测试/生产使用不同数据目录 |\n| 按项目隔离 | 每个项目使用独立的数据目录 |\n\n```bash\n# 多实例运行示例\nAUDREY_DATA_DIR=/data/tenant-a audrey serve --port 7437 &\nAUDREY_DATA_DIR=/data/tenant-b audrey serve --port 7438 &\n```\n\n## 数据导入导出\n\n### 导出工具\n\n当启用管理工具时（`AUDREY_ENABLE_ADMIN_TOOLS=1`），可以通过 REST API 导出数据：\n\n| 端点 | 方法 | 说明 |\n|------|------|------|\n| `/v1/export` | POST | 导出所有记忆数据 |\n| `/v1/import` | POST | 导入记忆快照 |\n| `/v1/forget` | POST | 删除指定记忆 |\n\n```bash\n# 启用管理工具\nAUDREY_ENABLE_ADMIN_TOOLS=1 npx audrey serve\n\n# 导出数据\ncurl -X POST http://127.0.0.1:7437/v1/export \\\n -H \"Authorization: Bearer $AUDREY_API_KEY\"\n```\n\n资料来源：[README.md:环境变量部分]()\n\n## 生产环境建议\n\n| 建议项 | 说明 |\n|--------|------|\n| 定期备份 | 每次重大版本升级前备份 `AUDREY_DATA_DIR` |\n| 磁盘空间监控 | 监控数据库目录大小，避免磁盘满 |\n| 权限控制 | 确保数据库目录仅服务进程可读写 |\n| 升级前备份 | Provider 或维度变化前必须备份 |\n| 冷备份时机 | 备份时停止服务或使用只读快照 |\n\n```bash\n# 生产环境备份脚本示例\n#!/bin/bash\nAUDREY_DATA_DIR=\"${AUDREY_DATA_DIR:-.audrey}\"\nBACKUP_DIR=\"/backups/audrey\"\nTIMESTAMP=$(date +%Y%m%d_%H%M%S)\n\nmkdir -p \"$BACKUP_DIR\"\ncp -r \"$AUDREY_DATA_DIR\" \"$BACKUP_DIR/audrey-$TIMESTAMP\"\necho \"Backup completed: $BACKUP_DIR/audrey-$TIMESTAMP\"\n```\n\n资料来源：[README.md:Production Readiness 部分]()\n\n## 数据生命周期\n\n### 记忆巩固 (Consolidation)\n\nAudrey 通过定期运行 `dream` 命令执行记忆巩固：\n\n```bash\nnpx audrey dream\n```\n\n巩固过程包括：\n- 低置信度记忆衰减\n- 高频使用记忆强化\n- 矛盾记忆标记处理\n- 跨记忆类型关联更新\n\n### 记忆衰减 (Decay)\n\n置信度低于阈值的记忆会逐渐衰减，失去在检索中的优先级：\n\n| 衰减因素 | 说明 |\n|----------|------|\n| 时间衰减 | 长时间未使用的记忆置信度下降 |\n| 矛盾干扰 | 被新证据反驳的记忆进入 disputed 状态 |\n| 低使用率 | usage_count 过低的记忆逐渐淡化 |\n\n```typescript\n// 衰减配置 (half-life 机制)\ninterface ConfidenceConfig {\n halfLifeDays: number; // 置信度减半的天数\n decayThreshold: number; // 触发衰减的最小置信度\n boostOnUse: boolean; // 使用后是否提升置信度\n}\n```\n\n资料来源：[src/impact.ts:全文]()\n\n## 存储健康检查\n\n使用 CLI 检查存储状态：\n\n```bash\n# 基本状态检查\nnpx audrey status\n\n# JSON 格式输出\nnpx audrey status --json\n\n# 严格模式（不健康时退出码非零）\nnpx audrey status --json --fail-on-unhealthy\n```\n\n```json\n{\n \"status\": \"healthy\",\n \"database\": {\n \"path\": \".audrey/audrey.db\",\n \"size_bytes\": 1048576,\n \"episodic_count\": 150,\n \"semantic_count\": 23,\n \"procedural_count\": 8\n },\n \"vectorIndex\": {\n \"status\": \"ready\",\n \"dimension\": 768\n }\n}\n\n---\n\n\n\n## MCP集成\n\n### 相关页面\n\n相关主题：[Audrey Guard 安全循环](#page-audrey-guard), [REST API](#page-rest-api)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [mcp-server/index.ts](https://github.com/Evilander/Audrey/blob/main/mcp-server/index.ts)\n- [mcp-server/config.ts](https://github.com/Evilander/Audrey/blob/main/mcp-server/config.ts)\n- [src/routes.ts](https://github.com/Evilander/Audrey/blob/main/src/routes.ts)\n- [src/capsule.ts](https://github.com/Evilander/Audrey/blob/main/src/capsule.ts)\n- [src/redact.ts](https://github.com/Evilander/Audrey/blob/main/src/redact.ts)\n- [README.md](https://github.com/Evilander/Audrey/blob/main/README.md)\n \n\n# MCP集成\n\n## 概述\n\nAudrey通过Model Context Protocol (MCP)实现与各类AI代理（Codex、Claude Code、Claude Desktop、Cursor、Windsurf、VS Code、JetBrains、Ollama等）的本地优先记忆防火墙集成。MCP作为中间协议层，使Audrey能够以工具的形式嵌入到AI代理的工作流程中，在代理执行操作前进行记忆检查和决策过滤。\n\n核心工作流程为：代理请求操作 → Audrey Guard检查记忆层 → 返回`allow`（允许）、`warn`（警告）或`block`（阻止）决策及证据。\n\n资料来源：[README.md:1-20]()\n\n## 架构设计\n\n### 系统组件关系\n\n```mermaid\ngraph TD\n A[\"AI代理
(Claude Code/Cursor/Codex等)\"] -->|MCP协议| B[\"Audrey MCP Server
mcp-server/index.ts\"]\n B -->|stdio/STDIO通信| C[\"Audrey Core
内存管理层\"]\n C -->|SQLite存储| D[\"记忆存储
episodic/semantic/procedural\"]\n \n E[\"REST API
/v1/*\"] -->|HTTP调用| C\n \n F[\"CLI工具
audrey guard\"] -->|命令行接口| C\n \n B -->|工具调用| G[\"guard
记忆检查工具\"]\n B -->|工具调用| H[\"memory_encode
编码记忆\"]\n B -->|工具调用| I[\"memory_recall
检索记忆\"]\n B -->|工具调用| J[\"memory_feedback
反馈结果\"]\n```\n\n### MCP通信模式\n\nAudrey MCP Server支持两种通信模式，根据不同宿主环境选择：\n\n| 宿主类型 | 通信模式 | 配置格式 | 说明 |\n|---------|---------|---------|------|\n| Codex | stdio | TOML | 通过`command`和`args`直接启动进程 |\n| Claude Code | stdio | JSON | MCP原生JSON-RPC |\n| Claude Desktop | stdio | JSON | MCP原生JSON-RPC |\n| Cursor | stdio | JSON | MCP原生JSON-RPC |\n| Windsurf | stdio | JSON | MCP原生JSON-RPC |\n| VS Code | stdio | JSON | MCP原生JSON-RPC |\n| JetBrains | stdio | JSON | MCP原生JSON-RPC |\n| Ollama | stdio | JSON | 本地模型支持 |\n| Generic | stdio | JSON | 通用MCP宿主 |\n\n资料来源：[mcp-server/config.ts:1-50]()\n\n## MCP服务器启动\n\n### CLI参数解析\n\nMCP服务器通过命令行参数配置启动行为，支持以下选项：\n\n```mermaid\ngraph LR\n A[\"CLI Arguments\"] --> B{\"参数解析
parseArgs()\"}\n B --> C[\"--host=\"]\n B --> D[\"--dry-run\"]\n B --> D2[\"--include-secrets\"]\n \n C --> E[\"host变量
宿主标识\"]\n D --> F[\"dryRun标志\"]\n D2 --> G[\"includeSecrets标志\"]\n \n E --> H[\"返回对象
{host, dryRun, includeSecrets}\"]\n```\n\n参数处理逻辑（伪代码表示）：\n\n| 参数模式 | 示例 | 行为 |\n|---------|------|------|\n| `--host=` | `--host=claude-code` | 设置宿主标识 |\n| `--dry-run` | `audrey mcp --dry-run` | 预览配置不实际启动 |\n| `--include-secrets` | `audrey mcp --include-secrets` | 在环境变量中包含密钥 |\n| 无前缀值 | `audrey mcp claude-code` | 设置宿主标识 |\n\n资料来源：[mcp-server/index.ts:1-80]()\n\n### 子命令分发\n\n```mermaid\nstateDiagram-v2\n [*] --> HelpCheck\n HelpCheck --> VersionCheck: --help/-h/help\n HelpCheck --> [*]: 退出\n VersionCheck --> [*]: --version/-v/version\n VersionCheck --> [*]: 退出\n \n [*] --> SubcommandDispatch\n SubcommandDispatch --> install: subcommand='install'\n SubcommandDispatch --> uninstall: subcommand='uninstall'\n SubcommandDispatch --> mcp_config: subcommand='mcp-config'\n SubcommandDispatch --> hook_config: subcommand='hook-config'\n SubcommandDispatch --> demo: subcommand='demo'\n SubcommandDispatch --> reembed: subcommand='reembed'\n SubcommandDispatch --> dream: subcommand='dream'\n SubcommandDispatch --> MCP_Server: stdio_loop\n \n install --> [*]\n uninstall --> [*]\n mcp_config --> [*]\n hook_config --> [*]\n demo --> [*]\n reembed --> [*]\n dream --> [*]\n MCP_Server --> [*]\n```\n\n支持的子命令列表：\n\n| 子命令 | 功能描述 |\n|-------|---------|\n| `audrey install --host ` | 在指定宿主中注册Audrey |\n| `audrey uninstall` | 取消注册Audrey |\n| `audrey mcp-config` | 打印MCP配置文件 |\n| `audrey hook-config` | 打印/应用Hook配置 |\n| `audrey demo` | 运行演示命令 |\n| `audrey reembed` | 重新生成嵌入向量 |\n| `audrey dream` | 触发记忆整合 |\n| `audrey greeting` | 打印问候语 |\n\n资料来源：[mcp-server/index.ts:100-150]()\n\n## MCP工具接口\n\n### 工具注册与调用\n\nAudrey通过MCP暴露以下核心工具，AI代理可在执行操作前调用：\n\n| 工具名称 | 功能 | 返回类型 |\n|---------|------|---------|\n| `guard` | 记忆前置检查 | `GuardResult` |\n| `memory_encode` | 编码新记忆 | `EncodeResult` |\n| `memory_recall` | 检索相关记忆 | `RecallResult` |\n| `memory_feedback` | 记录反馈结果 | `FeedbackResult` |\n\n### Guard工具详解\n\nGuard是Audrey的核心工具，用于在代理执行操作前进行记忆检查：\n\n```mermaid\nsequenceDiagram\n participant Agent as AI代理\n participant MCP as Audrey MCP Server\n participant Core as Audrey Core\n participant DB as SQLite存储\n\n Agent->>MCP: guard(tool, action, context)\n MCP->>Core: beforeAction(options)\n Core->>DB: 查询相关记忆\n DB-->>Core: 记忆记录列表\n Core->>Core: 分析决策
allow/warn/block\n Core->>DB: 记录使用统计\n Core-->>MCP: GuardResult\n MCP-->>Agent: 决策+证据\n```\n\nGuard参数结构（`src/routes.ts`中定义）：\n\n```typescript\ninterface GuardParams {\n tool: string; // 工具名称\n action: string; // 操作描述\n cwd?: string; // 工作目录\n sessionId?: string; // 会话标识\n files?: string[]; // 相关文件列表\n json?: boolean; // JSON格式输出\n override?: boolean; // 覆盖配置\n failOnWarn?: boolean; // 警告时失败\n explain?: boolean; // 返回解释\n hook?: boolean; // Hook模式\n strict?: boolean; // 严格模式\n includeCapsule?: boolean; // 包含记忆胶囊\n}\n```\n\n资料来源：[mcp-server/index.ts:200-280]()\n资料来源：[src/routes.ts:1-60]()\n\n### Guard返回值结构\n\n| 字段 | 类型 | 说明 |\n|-----|------|------|\n| `decision` | `allow` \\| `warn` \\| `block` | 决策结果 |\n| `receipt_id` | `string` | 收据ID，用于后续反馈 |\n| `capsule` | `MemoryCapsule` | 检索到的相关记忆 |\n| `preflight` | `PreflightResult` | 前置检查结果 |\n| `confidence` | `number` | 置信度 (0-1) |\n| `evidence` | `Evidence[]` | 支持决策的证据 |\n\n### Memory Capsule结构\n\n记忆胶囊（Memory Capsule）将检索到的记忆分类组织，便于代理理解和使用：\n\n```mermaid\ngraph TD\n A[\"MemoryCapsule\"] --> B[\"sections: 各分区记忆\"]\n B --> C[\"must_follow
必须遵守的规则\"]\n B --> D[\"procedures
操作流程\"]\n B --> E[\"user_preferences
用户偏好\"]\n B --> F[\"risks
风险警告\"]\n B --> G[\"uncertain_or_disputed
不确定/争议\"]\n B --> H[\"recent_changes
近期变更\"]\n B --> I[\"project_facts
项目事实\"]\n```\n\n分区分配规则（`src/capsule.ts`）：\n\n| 记忆类型/标签 | 分配分区 | 条件 |\n|-------------|---------|------|\n| 高置信度直接观察/用户告知 | `must_follow` | 包含MUST_FOLLOW_TAGS |\n| 低置信度间接来源 | `uncertain_or_disputed` | 包含MUST_FOLLOW_TAGS但来源不可信 |\n| 包含RISK_TAGS | `risks` | 标签匹配 |\n| procedural类型或PROCEDURE_TAGS | `procedures` | 类型/标签匹配 |\n| PREFERENCE_TAGS或told-by-user | `user_preferences` | 标签/来源匹配 |\n| 状态为disputed/context_dependent | `uncertain_or_disputed` | 状态检查 |\n| 置信度 < 0.55 | `uncertain_or_disputed` | 阈值检查 |\n| 7天内创建 | `recent_changes` | 时间窗口 |\n\n资料来源：[src/capsule.ts:1-100]()\n\n## 配置生成\n\n### 宿主配置格式化\n\nMCP Server根据不同宿主类型生成对应格式的配置文件：\n\n```mermaid\ngraph LR\n A[\"宿主类型\"] --> B{\"formatMcpHostConfig()\"}\n B -->|codex| C[\"TOML格式
tomlString()\"]\n B -->|其他| D[\"JSON格式
JSON.stringify()\"]\n \n C --> E[\"[mcp_servers.audrey]
command = ...
args = [...]\"]\n D --> F[\"{\\\"mcpServers\\\": {...}}\"]\n```\n\n#### Codex配置格式（TOML）\n\n```\n[mcp_servers.audrey]\ncommand = \"/path/to/node\"\nargs = [\"/path/to/audrey\", \"mcp\"]\n\n[mcp_servers.audrey.env]\nAUDREY_DATA_DIR = \"/path/to/data\"\nAUDREY_EMBEDDING_PROVIDER = \"openai\"\n```\n\n#### 标准JSON配置格式\n\n```json\n{\n \"mcpServers\": {\n \"audrey\": {\n \"command\": \"node\",\n \"args\": [\"/path/to/mcp-server/index.ts\"],\n \"env\": {\n \"AUDREY_DATA_DIR\": \"/path/to/data\"\n }\n }\n }\n}\n```\n\n资料来源：[mcp-server/config.ts:10-60]()\n\n### 环境变量构建\n\n```typescript\nfunction buildAudreyMcpEnv(\n env: Record,\n agent: string,\n options: { includeSecrets?: boolean }\n): Record\n```\n\n| 环境变量 | 默认值 | 说明 |\n|---------|-------|------|\n| `AUDREY_DATA_DIR` | 自动 | 数据存储目录 |\n| `AUDREY_LLM_PROVIDER` | 推断 | LLM提供者 |\n| `AUDREY_EMBEDDING_PROVIDER` | 推断 | 嵌入提供者 |\n| `AUDREY_LLM_MODEL` | 推断 | LLM模型 |\n| `AUDREY_API_KEY` | 无 | API密钥（需设置includeSecrets） |\n\n资料来源：[mcp-server/config.ts:50-100]()\n\n## 安装与配置\n\n### 安装流程\n\n```mermaid\ngraph TD\n A[\"audrey install --host \"] --> B[\"buildInstallArgs()\"]\n B --> C[\"生成MCP安装参数\"]\n C --> D[\"mcp add -s user audrey -e KEY=VALUE -- node audrey mcp\"]\n D --> E[\"调用宿主MCP安装命令\"]\n E --> F{\"成功?\"}\n F -->|是| G[\"安装完成\"]\n F -->|否| H[\"错误处理\"]\n \n A2[\"--dry-run\"] --> I[\"仅预览配置
不实际安装\"]\n```\n\n### Claude Code安装步骤\n\n```bash\n# 1. 预览安装配置\nnpx audrey install --host claude-code --dry-run\n\n# 2. 实际注册Audrey MCP Server\nnpx audrey install --host claude-code\n\n# 3. 应用项目级Hook配置\nnpx audrey hook-config claude-code --apply --scope project\n\n# 4. 应用用户级Hook配置\nnpx audrey hook-config claude-code --apply --scope user\n\n# 5. 在Claude Code中验证Hook\n/hooks\n\n# 6. 验证MCP Server\nclaude mcp list\n```\n\n### Hook配置\n\nHook配置用于将Audrey集成到代理的请求-响应循环中：\n\n```typescript\ninterface HookConfigOptions {\n host: string;\n apply: boolean; // 是否应用配置\n dryRun: boolean; // 预览模式\n scope: 'project' | 'user'; // 配置作用域\n projectDir: string; // 项目目录\n settingsPath?: string; // 配置文件路径\n}\n```\n\n| 作用域 | 配置文件路径 |\n|-------|-------------|\n| `user` | `~/.claude/settings.json` |\n| `project` | `/.claude/settings.local.json` |\n\n资料来源：[mcp-server/index.ts:150-200]()\n\n## 安全与隐私\n\n### 数据脱敏\n\nAudrey MCP Server内置敏感信息检测和脱敏机制（`src/redact.ts`）：\n\n| 敏感类型 | 模式 | 替换值 |\n|---------|------|-------|\n| API密钥 | `/(api[_-]?key|apikey)[=:]\\s*['\"]?([^'\"\\s,]+)/gi` | `[REDACTED:api_key]` |\n| AWS密钥 | `/(aws[_-]?secret[_-]?access[_-]?key)[=:]\\s*['\"]?([^'\"\\s,]+)/gi` | `[REDACTED:aws_key]` |\n| Bearer令牌 | `/(bearer[_-]?token)[=:]\\s*['\"]?([^'\"\\s,]+)/gi` | `[REDACTED:bearer_token]` |\n| 密码赋值 | `/(password|passwd|pwd)[=:]\\s*['\"]?([^'\"\\s,]+)/gi` | `[REDACTED:password]` |\n| JWT | `/(jwt)[=:]\\s*['\"]?([^'\"\\s,]+)/gi` | `[REDACTED:jwt]` |\n| 会话Cookie | `/(session|sid)=[A-Za-z0-9%._-]{8,}/gi` | `[REDACTED:session]` |\n| S3签名 | `/([?&](?:X-Amz-Signature|sig)=)[^&\\s\"']+/gi` | `[REDACTED:signed_url_signature]` |\n| US SSN | `/\\b(?!000|666|9\\d{2})\\d{3}-(?!00)\\d{2}-(?!0000)\\d{4}\\b/g` | `[REDACTED:ssn]` |\n\n### HTTP API安全\n\n| 安全措施 | 说明 |\n|---------|------|\n| 绑定地址限制 | 默认为`127.0.0.1`，拒绝非localhost无API Key |\n| API Key比较 | 使用`crypto.timingSafeEqual`防止时序攻击 |\n| 选项白名单 | `sanitizeRecallOptions()`过滤不允许的HTTP Body参数 |\n| 管理员工具 | `AUDREY_ENABLE_ADMIN_TOOLS`默认禁用导出/导入/删除功能 |\n\n资料来源：[src/redact.ts:1-80]()\n资料来源：[README.md:环境变量部分]()\n\n## 诊断与调试\n\n### Doctor诊断命令\n\n```bash\nnpx audrey doctor [--json] [--override]\n```\n\n| 检查项 | 说明 |\n|-------|------|\n| `node-runtime` | Node.js版本 ≥ 20 |\n| `mcp-entrypoint` | MCP入口文件存在 |\n| `data-dir-writable` | 数据目录可写 |\n| `memory-store` | SQLite存储健康 |\n| `embedding-provider` | 嵌入提供者配置 |\n| `llm-provider` | LLM提供者配置 |\n| `host-config` | 宿主配置文件存在 |\n\n### 环境变量诊断\n\n| 环境变量 | 默认值 | 用途 |\n|---------|-------|------|\n| `AUDREY_DEBUG` | `0` | 打印MCP启动和预热日志 |\n| `AUDREY_PROFILE` | `0` | 启用诊断计时输出 |\n| `AUDREY_DISABLE_WARMUP` | `0` | 跳过嵌入向量预热 |\n| `AUDREY_ONNX_VERBOSE` | `0` | 显示ONNX运行时端点分配警告 |\n\n资料来源：[mcp-server/index.ts:doctor相关函数]()\n\n## 性能特性\n\n### 冷启动优化\n\n| 指标 | 优化前 | 优化后 | 提升倍数 |\n|-----|-------|-------|---------|\n| 编码响应时间 (p50) | 24.7ms | 15.2ms | ~1.6x |\n| 冷启动首次编码 | 525ms | 28ms | ~18.7x |\n| 混合检索 (p50) | 30.2ms | 14.3ms | ~2.1x |\n\n### 嵌入向量优化\n\n- 验证、干扰检测、情感共鸣共享主内容向量\n- 消除4次冗余嵌入调用中的3次\n- 可选`wait_for_consolidation`参数实现写后读语义\n\n资料来源：[CHANGELOG.md:0.22.0版本]()\n\n## 版本历史\n\n| 版本 | 发布日期 | 关键变更 |\n|-----|---------|---------|\n| 0.22.0 | 2026-04-28 | 性能优化，编码速度提升40%+，冷启动18.7x提升 |\n| 0.21.0 | 2026-04 | 添加`audrey doctor`诊断命令，host安装预览 |\n| 0.20.0 | 2026-03 | 记忆Preflight和Reflexes，MCP文档完善 |\n\n资料来源：[CHANGELOG.md:版本记录]()\n\n---\n\n\n\n## REST API\n\n### 相关页面\n\n相关主题：[MCP集成](#page-mcp-integration)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/routes.ts](https://github.com/Evilander/Audrey/blob/main/src/routes.ts)\n- [src/server.ts](https://github.com/Evilander/Audrey/blob/main/src/server.ts)\n- [README.md](https://github.com/Evilander/Audrey/blob/main/README.md)\n- [python/README.md](https://github.com/Evilander/Audrey/blob/main/python/README.md)\n- [src/audrey.ts](https://github.com/Evilander/Audrey/blob/main/src/audrey.ts)\n \n\n# REST API\n\nAudrey 提供了一个基于 Hono 框架构建的 REST API 服务端点，允许外部客户端（包括 Python SDK、命令行工具和其他 AI 代理）通过 HTTP 协议访问记忆功能。该 API 是 Audrey 作为本地优先记忆防火墙的核心通信接口。\n\n## 概述\n\nREST API 作为 Audrey 的远程通信层，默认监听 `http://127.0.0.1:7437`，提供健康检查、记忆编码、记忆召回、记忆胶囊获取以及管理工具等端点。资料来源：[README.md](https://github.com/Evilander/Audrey/blob/main/README.md)\n\n```mermaid\ngraph LR\n A[Python SDK] -->|HTTP 请求| B[REST API]\n C[CLI 工具] -->|HTTP 请求| B\n D[外部 Agent] -->|HTTP 请求| B\n B --> E[SQLite + sqlite-vec]\n B --> F[Embedding 服务]\n```\n\n## 核心端点\n\nAudrey REST API 遵循 `/health` 和 `/v1/*` 的路由模式，所有 API 端点都需要通过认证才能访问非本地环回地址。资料来源：[CHANGELOG.md](https://github.com/Evilander/Audrey/blob/main/CHANGELOG.md)\n\n### 健康检查\n\n| 端点 | 方法 | 说明 |\n|------|------|------|\n| `/health` | GET | 检查服务健康状态 |\n\n### 记忆操作\n\n| 端点 | 方法 | 说明 |\n|------|------|------|\n| `/v1/preflight` | POST | 执行行动前检查，返回 allow、warn 或 block 决策 |\n| `/v1/recall` | POST | 召回相关记忆上下文 |\n| `/v1/capsule` | POST | 获取回合大小的记忆数据包 |\n| `/v1/status` | GET | 获取当前记忆状态 |\n\n### 管理工具（需启用）\n\n当 `AUDREY_ENABLE_ADMIN_TOOLS=1` 时，以下端点可用：\n\n| 端点 | 方法 | 说明 |\n|------|------|------|\n| `/v1/export` | POST | 导出记忆快照 |\n| `/v1/import` | POST | 导入记忆快照 |\n| `/v1/forget` | POST | 遗忘特定记忆 |\n\n## 请求体结构\n\n所有 POST 端点使用统一的 `RouteBody` 类型定义，支持丰富的参数选项。资料来源：[src/routes.ts:1-50](https://github.com/Evilander/Audrey/blob/main/src/routes.ts)\n\n### 基础参数\n\n| 参数名 | 类型 | 说明 |\n|--------|------|------|\n| `action` | string | 执行的操作或命令 |\n| `query` | string | 查询字符串（action 的别名） |\n| `tool` | string | 工具名称（如 Bash、Write） |\n| `session_id` / `sessionId` | string | 会话标识符 |\n| `cwd` | string | 当前工作目录 |\n\n### 记忆召回参数\n\n| 参数名 | 类型 | 默认值 | 说明 |\n|--------|------|--------|------|\n| `limit` | number | - | 召回记忆数量限制 |\n| `budget_chars` / `budgetChars` | number | 4000 | 记忆胶囊字符预算 |\n| `include_capsule` / `includeCapsule` | boolean | false | 是否包含记忆胶囊 |\n| `include_status` / `includeStatus` | boolean | false | 是否包含状态信息 |\n| `include_preflight` / `includePreflight` | boolean | false | 是否包含预检结果 |\n\n### Preflight 参数\n\n| 参数名 | 类型 | 说明 |\n|--------|------|------|\n| `mode` | string | 预检模式 |\n| `failure_window_hours` | number | 失败窗口小时数 |\n| `recent_failure_window_hours` | number | 最近失败窗口小时数 |\n| `recent_change_window_hours` | number | 最近变更窗口小时数 |\n| `strict` | boolean | 是否启用严格模式 |\n| `record_event` / `recordEvent` | boolean | 是否记录事件 |\n\n### 事件反馈参数\n\n| 参数名 | 类型 | 说明 |\n|--------|------|------|\n| `receipt_id` / `receiptId` | string | 收据标识符 |\n| `input` | unknown | 输入数据 |\n| `output` | unknown | 输出数据 |\n| `outcome` | string | 结果（used/helpful/wrong） |\n| `error_summary` / `errorSummary` | string | 错误摘要 |\n| `evidence_feedback` | object | 证据反馈映射 |\n\n## 认证机制\n\n### API 密钥认证\n\n非环回地址的请求必须提供 Bearer 令牌认证：\n\n```\nAuthorization: Bearer \n```\n\nAPI 密钥通过环境变量 `AUDREY_API_KEY` 配置。资料来源：[CHANGELOG.md](https://github.com/Evilander/Audrey/blob/main/CHANGELOG.md)\n\n### 安全措施\n\n1. **时序安全比较**：HTTP API 密钥比较使用 `crypto.timingSafeEqual` 而非字符串 `!==`，防止前缀匹配时序泄露攻击。资料来源：[CHANGELOG.md](https://github.com/Evilander/Audrey/blob/main/CHANGELOG.md)\n\n2. **选项清理**：`/v1/recall` 和 `/v1/capsule` 不再将调用者选项直接传播到 `audrey.recall()`，新增的 `sanitizeRecallOptions()` 白名单函数会过滤不安全的参数，防止 `includePrivate: true` 等 ACL 绕过。资料来源：[CHANGELOG.md](https://github.com/Evilander/Audrey/blob/main/CHANGELOG.md)\n\n3. **绑定安全**：`audrey serve` 默认绑定 `127.0.0.1`（原为 `0.0.0.0`），非环回主机拒绝启动除非设置了 `AUDREY_API_KEY` 或明确设置 `AUDREY_ALLOW_NO_AUTH=1`。资料来源：[CHANGELOG.md](https://github.com/Evilander/Audrey/blob/main/CHANGELOG.md)\n\n## 环境变量配置\n\n| 变量名 | 默认值 | 说明 |\n|--------|--------|------|\n| `AUDREY_PORT` | `7437` | REST API 监听端口 |\n| `AUDREY_HOST` | `127.0.0.1` | REST API 绑定地址 |\n| `AUDREY_API_KEY` | unset | 非环回请求必需的 Bearer 令牌 |\n| `AUDREY_ALLOW_NO_AUTH` | `0` | 允许无认证的非环回绑定 |\n| `AUDREY_ENABLE_ADMIN_TOOLS` | `0` | 启用导出、导入和遗忘路由 |\n| `AUDREY_DEBUG` | `0` | 打印 MCP 信息日志 |\n| `AUDREY_PROFILE` | `0` | 通过 MCP `_meta.diagnostics` 发出每阶段计时 |\n\n## Python SDK 集成\n\nPython 客户端通过 HTTP 调用 REST API 实现所有功能。资料来源：[python/README.md](https://github.com/Evilander/Audrey/blob/main/python/README.md)\n\n### 同步客户端\n\n```python\nfrom audrey_memory import Audrey\n\nbrain = Audrey(\n base_url=\"http://127.0.0.1:7437\",\n api_key=\"secret\",\n agent=\"support-agent\",\n)\n\nmemory_id = brain.encode(\n \"Stripe returns HTTP 429 above 100 req/s\",\n source=\"direct-observation\",\n tags=[\"stripe\", \"rate-limit\"],\n)\n\nresults = brain.recall(\"stripe rate limits\", limit=5)\nsnapshot = brain.snapshot()\nbrain.close()\n```\n\n### 异步客户端\n\n```python\nimport asyncio\nfrom audrey_memory import AsyncAudrey\n\nasync def main() -> None:\n async with AsyncAudrey(base_url=\"http://127.0.0.1:7437\") as brain:\n await brain.health()\n await brain.encode(\"Deploy failed due to OOM\", source=\"direct-observation\")\n await brain.recall(\"deploy failure\", limit=3)\n\nasyncio.run(main())\n```\n\n### 关键修复\n\n- `DEFAULT_BASE_URL` 已从 `http://127.0.0.1:3487` 更正为 `http://127.0.0.1:7437`\n- `recall()` 和 `recall_response()` 现在能正确解码 `/v1/recall` 返回的裸露列表\n- `restore()` 现在将快照包装在 `{\"snapshot\": ...}` 中以匹配 `/v1/import` 处理器\n\n## 部署模式\n\n### 启动服务\n\n```bash\nnpx audrey serve\n```\n\n### Docker 部署\n\n支持通过 Docker 和 Compose 进行容器化部署，REST API 端点暴露在配置的端口上。\n\n## 数据流\n\n```mermaid\nsequenceDiagram\n participant Client as Python/CLI\n participant API as REST API\n participant Audrey as Core Engine\n participant Storage as SQLite+vec\n\n Client->>API: POST /v1/recall\n API->>API: sanitizeRecallOptions()\n API->>Audrey: recall()\n Audrey->>Storage: 混合检索查询\n Storage-->>Audrey: 相关记忆\n Audrey-->>API: 记忆结果\n API-->>Client: JSON 响应\n```\n\n## 状态报告\n\n`/v1/status` 端点返回详细的系统状态，包括：\n\n- 记忆统计（情景记忆、语义记忆、程序性记忆数量）\n- 数据库连接状态\n- 嵌入服务状态\n- LLM 提供商信息\n\n医生检查（Doctor Checks）会验证：\n\n- Node.js 运行时版本（需 >= 20）\n- 入口点文件存在性\n- 数据目录配置\n- 嵌入模型可用性\n- 服务绑定安全性\n\n当服务绑定到非环回地址但未配置 API 密钥时，系统会拒绝启动并提示安全风险。资料来源：[mcp-server/index.ts](https://github.com/Evilander/Audrey/blob/main/mcp-server/index.ts)\n\n## 错误处理\n\n### HTTP 状态码\n\n| 状态码 | 说明 |\n|--------|------|\n| 200 | 请求成功 |\n| 400 | 请求参数错误 |\n| 401 | 认证失败 |\n| 404 | 端点不存在 |\n| 500 | 服务器内部错误 |\n\n### 验证错误\n\n请求体中的参数经过验证，非法参数会被拒绝并返回详细的错误信息。资料来源：[src/routes.ts](https://github.com/Evilander/Audrey/blob/main/src/routes.ts)\n\n## 与 MCP 协议的关系\n\nREST API 与 MCP（Model Context Protocol）stdio 服务器共享相同的核心引擎，但通过不同的传输层暴露功能：\n\n| 特性 | MCP | REST API |\n|------|-----|----------|\n| 传输协议 | stdio | HTTP |\n| 主要用途 | 代理集成 | 外部客户端 |\n| 实时性 | 更高 | 标准 HTTP 延迟 |\n| 工具数量 | 20+ | 4+ |\n\n---\n\n\n\n## CLI工具\n\n### 相关页面\n\n相关主题：[Audrey Guard 安全循环](#page-audrey-guard), [快速开始](#page-quick-start)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/Evilander/Audrey/blob/main/README.md)\n- [mcp-server/index.ts](https://github.com/Evilander/Audrey/blob/main/mcp-server/index.ts)\n- [src/impact.ts](https://github.com/Evilander/Audrey/blob/main/src/impact.ts)\n- [src/routes.ts](https://github.com/Evilander/Audrey/blob/main/src/routes.ts)\n- [src/rules-compiler.ts](https://github.com/Evilander/Audrey/blob/main/src/rules-compiler.ts)\n- [src/capsule.ts](https://github.com/Evilander/Audrey/blob/main/src/capsule.ts)\n- [src/redact.ts](https://github.com/Evilander/Audrey/blob/main/src/redact.ts)\n- [CHANGELOG.md](https://github.com/Evilander/Audrey/blob/main/CHANGELOG.md)\n \n\n# CLI工具\n\nAudrey 提供了一套完整的命令行界面（CLI）工具，用于管理 AI 代理的记忆系统。通过 CLI，用户可以执行记忆检查、原则提升、影响分析、工具观察等核心操作。\n\n## 概述\n\nAudrey CLI 是与 Audrey 记忆系统交互的主要方式之一，支持多种子命令以满足不同的使用场景：\n\n- **guard** — 记忆驱动的动作预检，在执行危险操作前进行检查\n- **promote** — 将高置信度记忆提升为持久化规则文件\n- **impact** — 生成记忆系统的影响分析报告\n- **install** — 安装和配置 Audrey 与目标主机的集成\n- **doctor** — 诊断 Audrey 环境配置状态\n- **status** — 查看记忆系统当前状态\n- **dream** — 触发记忆巩固与整合过程\n- **reembed** — 重新生成向量嵌入\n- **hook-config** — 生成 Claude Code 钩子配置\n- **mcp-config** — 生成 MCP 服务器配置\n\n资料来源：[README.md](https://github.com/Evilander/Audrey/blob/main/README.md)\n\n## 命令详解\n\n### guard 命令\n\n`guard` 是 Audrey 的核心安全循环命令，用于在执行工具操作前进行记忆预检。\n\n```bash\naudrey guard --tool \"\" [options]\n```\n\n#### 参数说明\n\n| 参数 | 说明 | 类型 |\n|------|------|------|\n| `--tool` | 工具名称（如 `Bash`, `Write`） | 字符串 |\n| `--explain` | 显示决策依据 | 标志位 |\n| `--strict` | 严格模式，拒绝所有警告决策 | 标志位 |\n| `--hook` | 以钩子模式运行 | 标志位 |\n| `--json` | 输出 JSON 格式结果 | 标志位 |\n| `--fail-on-warn` | 遇到警告时返回失败 | 标志位 |\n| `--session-id` | 会话标识符 | 字符串 |\n| `--cwd` | 工作目录 | 字符串 |\n| `--include-capsule` | 在响应中包含记忆胶囊 | 标志位 |\n\n#### 返回值\n\n`guard` 命令返回三种决策结果：\n\n- **`allow`** — 允许执行，提供相关记忆上下文\n- **`warn`** — 警告执行，显示需要注意的记忆内容\n- **`block`** — 阻止执行，基于记忆中的风险标记\n\n资料来源：[mcp-server/index.ts:45-89](https://github.com/Evilander/Audrey/blob/main/mcp-server/index.ts)\n\n#### 执行流程图\n\n```mermaid\ngraph TD\n A[用户执行 guard 命令] --> B[解析工具名称和动作]\n B --> C[调用 beforeAction 预检]\n C --> D{决策结果}\n D -->|allow| E[显示上下文记忆]\n D -->|caution| F[显示警告和证据]\n D -->|block| G[阻止执行并显示原因]\n E --> H[返回允许状态]\n F --> I[根据配置决定是否阻止]\n G --> J[返回阻止状态]\n```\n\n### promote 命令\n\n`promote` 命令将高置信度的记忆提升为 Claude Code 可读取的规则文件（`.claude/rules/*.md`）。\n\n```bash\naudrey promote [--yes] [--dry-run] [--limit ]\n```\n\n#### 参数说明\n\n| 参数 | 说明 | 默认值 |\n|------|------|--------|\n| `--yes` | 跳过确认直接写入 | false |\n| `--dry-run` | 预览将要创建的文件 | false |\n| `--limit` | 最大提升数量 | 10 |\n\n#### 生成的文件格式\n\n提升后的规则文件包含 YAML 前置元数据：\n\n```yaml\n---\ntitle: Audrey semantic memory \nsource_memory_ids: []\nconfidence: 0.85\nevidence_count: 3\npromoted_at: 2025-01-15T10:30:00Z\n---\n```\n\n资料来源：[src/rules-compiler.ts:1-45](https://github.com/Evilander/Audrey/blob/main/src/rules-compiler.ts)\n\n### impact 命令\n\n`impact` 命令生成记忆系统的使用影响分析报告，帮助评估记忆系统的实际效果。\n\n```bash\naudrey impact [--window-days ] [--format ]\n```\n\n#### 报告内容\n\n| 指标 | 说明 |\n|------|------|\n| `episodic` | 情景记忆总数（来自直接观察） |\n| `semantic` | 语义记忆总数（经巩固的原则） |\n| `procedural` | 程序性记忆总数（操作步骤） |\n| `validatedTotal` | 经过验证的记忆总数 |\n| `topUsed` | 使用频率最高的记忆 |\n| `weakest` | 置信度最低的记忆 |\n| `recentActivity` | 最近的记忆活动 |\n\n#### 情绪指标\n\n报告包含基于近近期记忆的情绪分析：\n\n- **valence** — 情绪效价（积极/消极程度）\n- **arousal** — 唤醒度\n- **samples** — 用于分析的样本数量\n\n资料来源：[src/impact.ts:1-80](https://github.com/Evilander/Audrey/blob/main/src/impact.ts)\n\n### install 命令\n\n`install` 命令用于将 Audrey 与目标主机进行集成配置。\n\n```bash\naudrey install --host [--dry-run]\n```\n\n#### 支持的主机\n\n| 主机 | 说明 |\n|------|------|\n| `claude-code` | Claude Code 编辑器 |\n| 其他 | 通用 MCP 配置生成 |\n\n#### 安装流程\n\n```mermaid\ngraph TD\n A[运行 install 命令] --> B[检测主机类型]\n B --> C{主机类型}\n C -->|claude-code| D[生成 MCP 配置]\n C -->|其他| E[生成通用配置]\n D --> F[注册 Claude Code 钩子]\n E --> G[输出配置供手动添加]\n F --> H[验证安装]\n```\n\n资料来源：[mcp-server/index.ts:90-130](https://github.com/Evilander/Audrey/blob/main/mcp-server/index.ts)\n\n### hook-config 命令\n\n生成 Claude Code 的钩子配置文件。\n\n```bash\naudrey hook-config [--apply] [--scope ] [--project-dir ]\n```\n\n| 参数 | 说明 | 可选值 |\n|------|------|--------|\n| `--scope` | 钩子作用域 | `project`, `user` |\n| `--apply` | 直接应用配置 | - |\n| `--project-dir` | 项目目录路径 | 路径 |\n\n资料来源：[mcp-server/index.ts:150-200](https://github.com/Evilander/Audrey/blob/main/mcp-server/index.ts)\n\n### status 命令\n\n查看 Audrey 记忆系统的当前状态。\n\n```bash\naudrey status [--json]\n```\n\n#### 显示内容\n\n- **Mood** — 情绪指标（valence, arousal）\n- **Memory** — 各类记忆数量统计\n- **Principles** — 学习到的原则列表\n- **Identity** — 身份相关记忆\n- **Recent memories** — 最近创建的记忆\n- **Unresolved** — 未解决的矛盾线索\n\n### 其他命令\n\n| 命令 | 功能 |\n|------|------|\n| `doctor` | 诊断环境配置问题 |\n| `demo` | 运行演示模式 |\n| `mcp-config` | 打印 MCP 服务器配置 |\n| `dream` | 触发记忆巩固过程 |\n| `reembed` | 重新生成向量嵌入 |\n| `observe-tool` | 观察工具执行结果 |\n| `greeting` | 问候语生成 |\n\n## 环境变量配置\n\nCLI 行为可通过以下环境变量进行配置：\n\n| 变量 | 默认值 | 说明 |\n|------|--------|------|\n| `AUDREY_DATA_DIR` | `./audrey-data` | 数据存储目录 |\n| `AUDREY_PORT` | `7437` | REST API 端口 |\n| `AUDREY_HOST` | `127.0.0.1` | REST API 绑定地址 |\n| `AUDREY_API_KEY` | 未设置 | API 认证密钥 |\n| `AUDREY_ENABLE_ADMIN_TOOLS` | `0` | 启用导出/导入/遗忘工具 |\n| `AUDREY_DEBUG` | `0` | 调试日志输出 |\n| `AUDREY_PROFILE` | `0` | 性能分析 |\n| `AUDREY_DISABLE_WARMUP` | `0` | 跳过嵌入预热 |\n\n资料来源：[README.md](https://github.com/Evilander/Audrey/blob/main/README.md)\n\n## REST API 端点\n\nCLI 底层通过 Hono 服务器提供 REST API：\n\n| 端点 | 方法 | 功能 |\n|------|------|------|\n| `/health` | GET | 健康检查 |\n| `/v1/preflight` | POST | 动作预检（guard 功能） |\n| `/v1/recall` | POST | 记忆召回 |\n| `/v1/capsule` | POST | 获取记忆胶囊 |\n| `/v1/status` | GET | 系统状态 |\n\n资料来源：[src/routes.ts:1-50](https://github.com/Evilander/Audrey/blob/main/src/routes.ts)\n\n## 安全机制\n\n### API 密钥保护\n\n`audrey serve` 默认绑定到 `127.0.0.1`，非回环地址启动需要 `AUDREY_API_KEY`。HTTP API 使用 `crypto.timingSafeEqual` 进行密钥比较，防止时序攻击。\n\n### 写入路径限制\n\n`audrey promote --yes` 拒绝向 `process.cwd()` 之外写入 `.claude/rules/*.md`，除非目标路径在 `AUDREY_PROMOTE_ROOTS` 环境变量中明确指定。\n\n### 敏感信息脱敏\n\nCLI 内置数据脱敏功能，自动处理以下敏感字段：\n\n- 密码相关：`password`, `passwd`, `pwd`\n- 密钥相关：`api_key`, `secret`, `token`\n- 认证相关：`auth_token`, `bearer_token`, `jwt`\n- 云服务：`aws_secret`, `private_key`\n\n资料来源：[src/redact.ts:30-50](https://github.com/Evilander/Audrey/blob/main/src/redact.ts)\n\n## 使用示例\n\n### 动作预检\n\n```bash\n# 检查 Bash 命令\naudrey guard --tool Bash \"rm -rf node_modules\" --explain\n\n# JSON 格式输出\naudrey guard --tool Bash \"npm run deploy\" --json\n\n# 严格模式\naudrey guard --tool Write \"config.yaml\" --strict\n```\n\n### 提升记忆为规则\n\n```bash\n# 预览将要创建的规则\naudrey promote --dry-run\n\n# 确认并写入\naudrey promote --yes\n\n# 限制数量\naudrey promote --yes --limit 5\n```\n\n### 查看影响分析\n\n```bash\n# 默认 30 天窗口\naudrey impact\n\n# 指定窗口天数\naudrey impact --window-days 7\n\n# JSON 格式\naudrey impact --format json\n```\n\n## 版本变更\n\n| 版本 | 变更内容 |\n|------|----------|\n| 0.23.0 | 新增 `--include-capsule` 参数 |\n| 0.22.0 | 性能优化：编码时间提升 40% |\n| 0.21.0 | 新增 `usage_count` 和 `last_used_at` 追踪 |\n| 0.20.0 | CLI 表面新增 `--help`/`--version` 短路处理 |\n\n资料来源：[CHANGELOG.md](https://github.com/Evilander/Audrey/blob/main/CHANGELOG.md)\n\n---\n\n\n\n## JavaScript SDK\n\n### 相关页面\n\n相关主题：[系统架构](#page-system-architecture), [记忆模型](#page-memory-model)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/audrey.ts](https://github.com/Evilander/Audrey/blob/main/src/audrey.ts)\n- [src/index.ts](https://github.com/Evilander/Audrey/blob/main/src/index.ts)\n- [src/types.ts](https://github.com/Evilander/Audrey/blob/main/src/types.ts)\n- [mcp-server/index.ts](https://github.com/Evilander/Audrey/blob/main/mcp-server/index.ts)\n- [src/capsule.ts](https://github.com/Evilander/Audrey/blob/main/src/capsule.ts)\n- [src/reflexes.ts](https://github.com/Evilander/Audrey/blob/main/src/reflexes.ts)\n- [src/routes.ts](https://github.com/Evilander/Audrey/blob/main/src/routes.ts)\n \n\n# JavaScript SDK\n\nAudrey JavaScript SDK 是该项目的核心客户端库，提供与 Audrey 记忆运行时交互的完整 TypeScript 接口。SDK 支持同步和异步操作，可用于 Node.js 环境和 CLI 工具中。\n\n## 核心架构\n\n### 模块结构\n\n```\naudrey (SDK)\n├── Audrey # 主类，包含所有记忆操作\n├── AsyncAudrey # 异步版本\n├── AudreyError # 错误类型\n└── 类型导出 # 完整的 TypeScript 类型定义\n```\n\n### 主类概述\n\n`Audrey` 类是 SDK 的核心，封装了所有与本地记忆存储交互的功能。主要特性包括：\n\n- **记忆编码与检索**：支持三种记忆类型的写入和查询\n- **Preflight 检查**：动作执行前的记忆验证\n- **记忆胶囊构建**：上下文压缩与摘要生成\n- **因果链路管理**：记忆之间的因果关系追踪\n- **健康诊断**：运行时状态检查\n\n## 记忆类型系统\n\nAudrey 采用三层记忆架构，对应神经科学的不同记忆系统：\n\n| 记忆类型 | 用途 | 特征 | 典型场景 |\n|---------|------|------|---------|\n| **情景记忆 (episodic)** | 事件记录 | 时间戳驱动、一次性的经验 | \"上次执行 deploy 失败，报 OOM\" |\n| **语义记忆 (semantic)** | 知识存储 | 跨会话持久、基于重要性 | \"项目使用 yarn 而非 npm\" |\n| **程序记忆 (procedural)** | 流程规范 | 步骤化、可执行 | \"审查 PR 的流程是...\" |\n\n资料来源：[src/audrey.ts](https://github.com/Evilander/Audrey/blob/main/src/audrey.ts)\n\n## 核心 API\n\n### 记忆编码 (encode)\n\n将信息编码为记忆存入存储系统。\n\n```typescript\nconst memoryId = brain.encode(\n \"Stripe API 在超过 100 req/s 时返回 HTTP 429\",\n source=\"direct-observation\",\n tags=[\"stripe\", \"rate-limit\"]\n);\n```\n\n**参数说明**：\n\n| 参数 | 类型 | 必需 | 说明 |\n|-----|------|-----|------|\n| content | string | 是 | 记忆内容 |\n| source | string | 否 | 来源标识（默认值：`direct-observation`）|\n| tags | string[] | 否 | 标签数组 |\n| memoryType | 'episodic' \\\\| 'semantic' \\\\| 'procedural' | 否 | 记忆类型 |\n| wait_for_consolidation | boolean | 否 | 是否等待一致性确认 |\n\n### 记忆检索 (recall)\n\n根据查询字符串检索相关记忆。\n\n```typescript\nconst results = brain.recall(\"stripe rate limits\", limit=5);\n```\n\n**参数说明**：\n\n| 参数 | 类型 | 默认值 | 说明 |\n|-----|------|-------|------|\n| query | string | - | 检索查询 |\n| limit | number | 16 | 返回结果数量 |\n| scope | 'shared' \\\\| 'agent' | 'shared' | 检索范围 |\n| retrieval | 'hybrid' \\\\| 'vector' | 'hybrid' | 检索模式 |\n| mood | MoodOptions | - | 情感参数 |\n| context | Record | - | 额外上下文 |\n\n### 记忆快取 (snapshot/restore)\n\n支持记忆状态的导出与恢复。\n\n```typescript\n// 导出\nconst snapshot = brain.snapshot();\n\n// 恢复到空存储\nrestoreTarget.restore(snapshot);\n```\n\n资料来源：[python/README.md](https://github.com/Evilander/Audrey/blob/main/python/README.md)\n\n## Preflight 检查系统\n\nPreflight 是 Audrey 的核心安全机制，在动作执行前验证记忆状态。\n\n### 工作流程\n\n```mermaid\ngraph TD\n A[动作请求] --> B[构建 Preflight]\n B --> C{匹配记忆反射?}\n C -->|是| D[返回反射建议]\n C -->|否| E{匹配风险标签?}\n E -->|是| F[生成警告]\n E -->|否| G[检查近期失败]\n G --> H{发现失败记录?}\n H -->|是| I[标记为 caution]\n H -->|否| J[允许执行]\n D --> K[返回决策: allow/warn/block]\n F --> K\n I --> K\n J --> K\n```\n\n### 返回决策\n\n| 决策 | 含义 | 触发条件 |\n|-----|------|---------|\n| `allow` | 允许执行 | 无风险匹配 |\n| `warn` | 警告执行 | 存在低置信度风险 |\n| `block` | 阻止执行 | 高置信度风险或阻止级反射 |\n\n资料来源：[src/reflexes.ts](https://github.com/Evilander/Audrey/blob/main/src/reflexes.ts)\n资料来源：[src/preflight.ts](https://github.com/Evilander/Audrey/blob/main/src/preflight.ts)\n\n## 记忆胶囊 (Memory Capsule)\n\n记忆胶囊是上下文压缩机制，将检索到的记忆压缩为可嵌入 LLM 上下文的格式。\n\n### 胶囊结构\n\n```typescript\ninterface MemoryCapsule {\n sections: {\n must_follow: []; // 必须遵循的规则\n project_facts: []; // 项目事实\n user_preferences: []; // 用户偏好\n procedures: []; // 程序流程\n risks: []; // 风险警告\n contradictions: []; // 矛盾信息\n recent_changes: []; // 近期变更\n };\n mood: MoodState; // 情感状态\n health: HealthStatus; // 健康状态\n}\n```\n\n### 构建选项\n\n| 选项 | 类型 | 默认值 | 说明 |\n|-----|------|-------|------|\n| mode | 'conservative' \\\\| 'balanced' \\\\| 'aggressive' | 'balanced' | 压缩激进程度 |\n| budgetChars | number | 4000 | 上下文预算上限 |\n| recentChangeWindowHours | number | 24 | 近期变更时间窗口 |\n| includeRisks | boolean | true | 是否包含风险 |\n| includeContradictions | boolean | true | 是否包含矛盾信息 |\n\n资料来源：[src/capsule.ts](https://github.com/Evilander/Audrey/blob/main/src/capsule.ts)\n\n## 记忆反射 (Memory Reflexes)\n\n记忆反射是预定义的动作-响应模式，用于在 Preflight 阶段自动匹配。\n\n### 反射类型\n\n| 类型 | 响应方式 | 使用场景 |\n|-----|---------|---------|\n| `block` | 阻止执行 | 已知危险操作 |\n| `warn` | 发出警告 | 潜在风险操作 |\n| `guide` | 提供引导 | 建议性操作 |\n\n### 反射报告构建\n\n```typescript\nconst report = await buildReflexReport(audrey, \"npm run deploy\", {\n includeCapsule: true,\n includePreflight: true\n});\n```\n\n资料来源：[src/reflexes.ts](https://github.com/Evilander/Audrey/blob/main/src/reflexes.ts)\n\n## HTTP API 层\n\nSDK 底层通过 HTTP REST API 与本地服务通信。\n\n### 路由结构\n\n| 端点 | 方法 | 说明 |\n|-----|------|------|\n| `/health` | GET | 健康检查 |\n| `/v1/encode` | POST | 编码记忆 |\n| `/v1/recall` | POST | 检索记忆 |\n| `/v1/snapshot` | GET | 导出快照 |\n| `/v1/restore` | POST | 恢复快照 |\n| `/v1/guard` | POST | Preflight 检查 |\n\n### 参数清理\n\n`src/routes.ts` 中实现了严格的参数白名单机制：\n\n```typescript\nfunction sanitizeRecallOptions(opts: Record): RecallOptions {\n // 仅允许特定字段通过\n const allowedKeys = ['limit', 'tags', 'sources', 'after', 'before', \n 'context', 'mood', 'retrieval', 'scope'];\n // ...\n}\n```\n\n资料来源：[src/routes.ts](https://github.com/Evilander/Audrey/blob/main/src/routes.ts)\n\n## CLI 命令行接口\n\n### guard 命令\n\n在执行工具前运行记忆检查。\n\n```bash\naudrey guard --tool Bash \"npm run deploy\"\n```\n\n**参数说明**：\n\n| 参数 | 说明 |\n|-----|------|\n| `--tool ` | 工具名称 |\n| `--session-id ` | 会话标识 |\n| `--cwd ` | 工作目录 |\n| `--json` | JSON 输出格式 |\n| `--explain` | 显示详细解释 |\n| `--hook` | Hook 模式运行 |\n| `--strict` | 严格模式（block 决策时退出） |\n\n### hook-config 命令\n\n配置 Claude Code 等 IDE 的集成钩子。\n\n```bash\naudrey hook-config claude-code --apply --scope project\n```\n\n### doctor 命令\n\n诊断运行时健康状态。\n\n```bash\naudrey doctor [--verbose]\n```\n\n**检查项**：\n\n- Node.js 运行时版本（需 >= 20）\n- 数据目录存在性\n- MCP 入口点配置\n- LLM 提供商配置\n- Embedding 提供商配置\n\n资料来源：[mcp-server/index.ts](https://github.com/Evilander/Audrey/blob/main/mcp-server/index.ts)\n\n## 类型系统\n\n### 核心类型定义\n\n```typescript\n// 记忆条目\ninterface MemoryEntry {\n id: string;\n content: string;\n memory_type: 'episodic' | 'semantic' | 'procedural';\n created_at: string;\n updated_at?: string;\n salience?: number;\n tags?: string[];\n}\n\n// Preflight 结果\ninterface PreflightResult {\n decision: 'allow' | 'warn' | 'block';\n warnings: PreflightWarning[];\n reflexReport?: MemoryReflexReport;\n capsule?: MemoryCapsule;\n}\n\n// 检索选项\ninterface RecallOptions {\n limit?: number;\n tags?: string[];\n sources?: string[];\n after?: string;\n before?: string;\n context?: Record;\n mood?: MoodOptions;\n retrieval?: 'hybrid' | 'vector';\n scope?: 'shared' | 'agent';\n}\n```\n\n资料来源：[src/types.ts](https://github.com/Evilander/Audrey/blob/main/src/types.ts)\n\n## 错误处理\n\n### 错误类型\n\n| 错误类型 | 说明 |\n|---------|------|\n| `AudreyError` | 基础错误类型 |\n| 验证错误 | 参数校验失败 |\n| 存储错误 | 数据库操作失败 |\n| LLM 错误 | AI 提供商调用失败 |\n\n### 错误处理示例\n\n```typescript\ntry {\n await brain.recall(\"query\", { limit: -1 });\n} catch (error) {\n if (error instanceof AudreyError) {\n console.error(`SDK Error: ${error.message}`);\n }\n}\n```\n\n## 情感状态 (Mood)\n\nAudrey 支持情感状态追踪，用于调整检索和响应行为。\n\n```typescript\ninterface MoodState {\n valence: number; // -1.0 到 1.0，情感正负\n arousal: number; // 0.0 到 1.0，激活程度\n samples: number; // 采样数量\n}\n```\n\n## 信任评估 (Confidence)\n\n记忆具有置信度评分，影响检索权重和决策。\n\n### 衰减机制\n\n```typescript\nfunction recencyDecay(\n createdAt: Date,\n halfLifeDays: number = 30\n): number {\n // 基于时间的衰减计算\n}\n```\n\n**规则**：\n- `halfLifeDays <= 0` 时抛出 `RangeError`\n- 默认半衰期为 30 天\n- 置信度基于记忆年龄、验证次数、使用频率综合计算\n\n资料来源：[src/causal.ts](https://github.com/Evilander/Audrey/blob/main/src/causal.ts)\n\n## 因果链路 (Causal Links)\n\n记忆之间可以建立因果关系。\n\n```typescript\ninterface CausalLink {\n linkId: string;\n causeId: string;\n effectId: string;\n linkType: 'correlational' | 'causal' | 'counterfactual';\n mechanism: string;\n confidence: number;\n spurious: boolean;\n}\n```\n\n### LLM 驱动的因果推断\n\n系统使用 LLM 分析记忆对之间的关系，判断是否为因果链接：\n\n1. 构建因果分析 prompt\n2. LLM 返回 JSON 格式分析结果\n3. 验证响应格式完整性\n4. 创建或拒绝因果链路\n\n**格式要求**：\n- `spurious`: boolean\n- `mechanism`: string\n- `linkType`: string（可选）\n- `confidence`: number（必须为有限数值）\n\n## 数据安全\n\n### 敏感信息脱敏\n\n`src/redact.ts` 实现了多层脱敏机制：\n\n```typescript\nconst SENSITIVE_KEY_PATTERN = /(password|secret|api_key|token|...)/i;\n```\n\n**脱敏规则**：\n\n| 类别 | 检测方式 |\n|-----|---------|\n| API 密钥 | 键名模式匹配 |\n| 密码凭证 | 键名 + 值模式 |\n| Bearer Token | 值内容检测 |\n| JWT | 结构化检测 |\n| AWS 密钥 | 特定前缀匹配 |\n\n### JSON 递归遍历\n\n脱敏系统递归遍历 JSON 结构，对象、数组、字符串分别处理，保留原始数据结构。\n\n资料来源：[src/redact.ts](https://github.com/Evilander/Audrey/blob/main/src/redact.ts)\n\n## 配置与环境变量\n\n### 关键环境变量\n\n| 变量 | 说明 | 默认值 |\n|-----|------|-------|\n| `AUDREY_DATA_DIR` | 数据存储目录 | `~/.audrey` |\n| `AUDREY_LLM_PROVIDER` | LLM 提供商 | 自动检测 |\n| `AUDREY_EMBEDDING_PROVIDER` | Embedding 提供商 | `local` |\n| `AUDREY_API_KEY` | API 认证密钥 | - |\n| `AUDREY_ALLOW_NO_AUTH` | 允许无认证 | `false` |\n\n### 提供商支持\n\n**LLM 提供商**：\n- OpenAI\n- Anthropic\n- 本地 Ollama\n- 自定义端点\n\n**Embedding 提供商**：\n- `local`：本地 GPU 加速（默认）\n- 云端服务\n\n## 性能优化\n\n### 近期版本性能改进 (0.22.0)\n\n| 指标 | 改进幅度 |\n|-----|---------|\n| 编码响应时间 | 40% 提升 (24.7ms → 15.2ms) |\n| 冷启动首次编码 | 18.7x 加速 (525ms → 28ms) |\n| 混合检索 | 2.1x 加速 (30.2ms → 14.3ms) |\n\n### 优化策略\n\n1. **复用 Embedding**：验证、干扰检测、情感共鸣共享主内容向量\n2. **预热机制**：冷启动时执行预热，避免首次延迟\n3. **流式检索**：`recallStream` 支持流式响应\n\n资料来源：[CHANGELOG.md](https://github.com/Evilander/Audrey/blob/main/CHANGELOG.md)\n\n## 使用示例\n\n### 基础同步使用\n\n```typescript\nimport { Audrey } from 'audrey';\n\nconst brain = new Audrey({\n baseUrl: 'http://127.0.0.1:7437',\n apiKey: 'secret',\n agent: 'support-agent'\n});\n\n// 编码新记忆\nconst memoryId = brain.encode(\n \"Deploy 失败是因为 OOM\",\n source: \"direct-observation\",\n tags: [\"deploy\", \"error\"]\n);\n\n// 检索相关记忆\nconst results = brain.recall(\"deploy failure\", limit: 3);\n\n// 获取快照\nconst snapshot = brain.snapshot();\n\n// 关闭连接\nbrain.close();\n```\n\n### 异步使用\n\n```typescript\nimport { AsyncAudrey } from 'audrey';\n\nasync function main() {\n const brain = new AsyncAudrey({\n baseUrl: 'http://127.0.0.1:7437',\n apiKey: 'secret'\n });\n\n await brain.health();\n await brain.encode(\"Stripe 返回 HTTP 429\");\n \n brain.close();\n}\n```\n\n### Preflight 检查\n\n```typescript\nconst result = await brain.beforeAction({\n tool: 'Bash',\n action: 'npm run deploy',\n cwd: '/project',\n sessionId: 'session-123'\n});\n\nif (result.decision === 'block') {\n console.error('操作被阻止:', result.warnings);\n process.exit(1);\n}\n```\n\n## MCP 服务器集成\n\nAudrey 通过 MCP (Model Context Protocol) 与各种 AI 代理集成：\n\n```mermaid\ngraph LR\n A[Claude Code] -->|MCP| B[Audrey MCP Server]\n A[Cursor] -->|MCP| B\n A[Windsurf] -->|MCP| B\n B --> C[Local Audrey Service]\n C --> D[(SQLite DB)]\n```\n\n### 支持的 IDE/工具\n\n- Claude Code\n- Claude Desktop\n- Cursor\n- Windsurf\n- VS Code (通过扩展)\n- JetBrains IDEs\n- Ollama 后端代理\n- 自定义代理服务\n\n资料来源：[README.md](https://github.com/Evilander/Audrey/blob/main/README.md)\n\n## 版本历史关键变更\n\n### 0.23.0\n\n- 移除 `hybrid_strict` 检索模式（曾是 `hybrid` 的别名）\n- 新增 `closeAsync(timeoutMs?)` 方法\n- 新增 `sanitizeRecallOptions()` 参数白名单工具\n\n### 0.22.0\n\n- 新增 `wait_for_consolidation` 参数\n- 新增 `retrieval` 参数（`hybrid` / `vector`）\n- 性能大幅优化\n\n资料来源：[CHANGELOG.md](https://github.com/Evilander/Audrey/blob/main/CHANGELOG.md)\n\n---\n\n---\n\n## Doramagic 踩坑日志\n\n项目：Evilander/Audrey\n\n摘要：发现 14 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：安装坑 - 来源证据：Audrey 1.0.1 — honest GuardBench gate, Guard time decay, structured validate errors。\n\n## 1. 安装坑 · 来源证据：Audrey 1.0.1 — honest GuardBench gate, Guard time decay, structured validate errors\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Audrey 1.0.1 — honest GuardBench gate, Guard time decay, structured validate errors\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_135b992964ae468aa28f88ee639816d1 | https://github.com/Evilander/Audrey/releases/tag/v1.0.1 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。\n\n## 2. 安装坑 · 来源证据：Audrey Guard 0.23.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Audrey Guard 0.23.0\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_9c913c644e2c4c099ea01523623f080e | https://github.com/Evilander/Audrey/releases/tag/v0.23.0 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 3. 安装坑 · 来源证据：v0.16.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v0.16.0\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_a7c5c62d4f034e50ba2e9c36e0798882 | https://github.com/Evilander/Audrey/releases/tag/v0.16.0 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。\n\n## 4. 安装坑 · 来源证据：v0.16.1 — Windows MCP fix\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v0.16.1 — Windows MCP fix\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_c0141ccf0a3245ec8c8ba112af7948e0 | https://github.com/Evilander/Audrey/releases/tag/v0.16.1 | 来源讨论提到 windows 相关条件，需在安装/试用前复核。\n\n## 5. 安装坑 · 来源证据：v0.17.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v0.17.0\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_9617863b3f954035926b8670b5bbea29 | https://github.com/Evilander/Audrey/releases/tag/v0.17.0 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 6. 配置坑 · 可能修改宿主 AI 配置\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。\n- 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。\n- 建议检查：列出会写入的配置文件、目录和卸载/回滚步骤。\n- 防护动作：涉及宿主配置目录时必须给回滚路径，不能只给安装命令。\n- 证据：capability.host_targets | github_repo:1161444210 | https://github.com/Evilander/Audrey | host_targets=mcp_host, claude, claude_code\n\n## 7. 能力坑 · 能力判断依赖假设\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:1161444210 | https://github.com/Evilander/Audrey | README/documentation is current enough for a first validation pass.\n\n## 8. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | github_repo:1161444210 | https://github.com/Evilander/Audrey | last_activity_observed missing\n\n## 9. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作：下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | github_repo:1161444210 | https://github.com/Evilander/Audrey | no_demo; severity=medium\n\n## 10. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | github_repo:1161444210 | https://github.com/Evilander/Audrey | no_demo; severity=medium\n\n## 11. 安全/权限坑 · 来源证据：Audrey 1.0.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Audrey 1.0.0\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_d30d964956da40a2b5e26dc7404861f8 | https://github.com/Evilander/Audrey/releases/tag/v1.0.0 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 12. 安全/权限坑 · 来源证据：v0.22.2 — correctness pass + legitimate benchmarking\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v0.22.2 — correctness pass + legitimate benchmarking\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_f9c004c97d31437ebdc3699d6f1ba2f4 | https://github.com/Evilander/Audrey/releases/tag/v0.22.2 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 13. 维护坑 · 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:1161444210 | https://github.com/Evilander/Audrey | issue_or_pr_quality=unknown\n\n## 14. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | github_repo:1161444210 | https://github.com/Evilander/Audrey | 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项目：Evilander/Audrey\n\n摘要：发现 14 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：安装坑 - 来源证据：Audrey 1.0.1 — honest GuardBench gate, Guard time decay, structured validate errors。\n\n## 1. 安装坑 · 来源证据：Audrey 1.0.1 — honest GuardBench gate, Guard time decay, structured validate errors\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Audrey 1.0.1 — honest GuardBench gate, Guard time decay, structured validate errors\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_135b992964ae468aa28f88ee639816d1 | https://github.com/Evilander/Audrey/releases/tag/v1.0.1 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。\n\n## 2. 安装坑 · 来源证据：Audrey Guard 0.23.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Audrey Guard 0.23.0\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_9c913c644e2c4c099ea01523623f080e | https://github.com/Evilander/Audrey/releases/tag/v0.23.0 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 3. 安装坑 · 来源证据：v0.16.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v0.16.0\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_a7c5c62d4f034e50ba2e9c36e0798882 | https://github.com/Evilander/Audrey/releases/tag/v0.16.0 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。\n\n## 4. 安装坑 · 来源证据：v0.16.1 — Windows MCP fix\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v0.16.1 — Windows MCP fix\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_c0141ccf0a3245ec8c8ba112af7948e0 | https://github.com/Evilander/Audrey/releases/tag/v0.16.1 | 来源讨论提到 windows 相关条件，需在安装/试用前复核。\n\n## 5. 安装坑 · 来源证据：v0.17.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v0.17.0\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_9617863b3f954035926b8670b5bbea29 | https://github.com/Evilander/Audrey/releases/tag/v0.17.0 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 6. 配置坑 · 可能修改宿主 AI 配置\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。\n- 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。\n- 建议检查：列出会写入的配置文件、目录和卸载/回滚步骤。\n- 防护动作：涉及宿主配置目录时必须给回滚路径，不能只给安装命令。\n- 证据：capability.host_targets | github_repo:1161444210 | https://github.com/Evilander/Audrey | host_targets=mcp_host, claude, claude_code\n\n## 7. 能力坑 · 能力判断依赖假设\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:1161444210 | https://github.com/Evilander/Audrey | README/documentation is current enough for a first validation pass.\n\n## 8. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | github_repo:1161444210 | https://github.com/Evilander/Audrey | last_activity_observed missing\n\n## 9. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作：下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | github_repo:1161444210 | https://github.com/Evilander/Audrey | no_demo; severity=medium\n\n## 10. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | github_repo:1161444210 | https://github.com/Evilander/Audrey | no_demo; severity=medium\n\n## 11. 安全/权限坑 · 来源证据：Audrey 1.0.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Audrey 1.0.0\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_d30d964956da40a2b5e26dc7404861f8 | https://github.com/Evilander/Audrey/releases/tag/v1.0.0 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 12. 安全/权限坑 · 来源证据：v0.22.2 — correctness pass + legitimate benchmarking\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v0.22.2 — correctness pass + legitimate benchmarking\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_f9c004c97d31437ebdc3699d6f1ba2f4 | https://github.com/Evilander/Audrey/releases/tag/v0.22.2 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 13. 维护坑 · 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:1161444210 | https://github.com/Evilander/Audrey | issue_or_pr_quality=unknown\n\n## 14. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | github_repo:1161444210 | https://github.com/Evilander/Audrey | release_recency=unknown\n",
"summary": "用户实践前最可能遇到的身份、安装、配置、运行和安全坑。",
"title": "Pitfall Log / 踩坑日志"
},
"prompt_preview": {
"asset_id": "prompt_preview",
"filename": "PROMPT_PREVIEW.md",
"markdown": "# Audrey - Prompt Preview\n\n> 复制下面这段 Prompt 到你常用的 AI，先试一次，不需要安装。\n> 它的目标是让你直接体验这个项目的服务方式，而不是阅读项目介绍。\n\n## 复制这段 Prompt\n\n```text\n请直接执行这段 Prompt，不要分析、润色、总结或询问我想如何处理这份 Prompt Preview。\n\n你现在扮演 Audrey 的“安装前体验版”。\n这不是项目介绍、不是评价报告、不是 README 总结。你的任务是让我用最小成本体验它的核心服务。\n\n我的试用任务：我想用它完成一个真实的软件开发与交付任务。\n我常用的宿主 AI：MCP Client / claude / Claude Code\n\n【体验目标】\n围绕我的真实任务，现场演示这个项目如何把输入转成 示例引导, 判断线索。重点是让我感受到工作方式，而不是给我项目背景。\n\n【业务流约束】\n- 你必须像一个正在提供服务的项目能力包，而不是像一个讲解员。\n- 每一轮只推进一个步骤；提出问题后必须停下来等我回答。\n- 每一步都必须让我感受到一个具体服务动作：澄清、整理、规划、检查、判断或收尾。\n- 每一步都要说明：当前目标、你需要我提供什么、我回答后你会产出什么。\n- 不要安装、不要运行命令、不要写代码、不要声称测试通过、不要声称已经修改文件。\n- 需要真实安装或宿主加载后才能验证的内容，必须明确说“这一步需要安装后验证”。\n- 如果我说“用示例继续”，你可以用虚构示例推进，但仍然不能声称真实执行。\n\n【可体验服务能力】\n- 安装前能力预览: Persistent memory and continuity engine for Claude Code and AI agents. 输入：用户任务, 当前 AI 对话上下文；输出：示例引导, 判断线索。\n\n【必须安装后才可验证的能力】\n- 命令行启动或安装流程: 项目文档中存在可执行命令，真实使用需要在本地或宿主环境中运行这些命令。 输入：终端环境, 包管理器, 项目依赖；输出：安装结果, 列表/更新/运行结果。\n\n【核心服务流】\n请严格按这个顺序带我体验。不要一次性输出完整流程：\n1. page-overview：项目概述。围绕“项目概述”模拟一次用户任务，不展示安装或运行结果。\n2. page-quick-start：快速开始。围绕“快速开始”模拟一次用户任务，不展示安装或运行结果。\n3. page-system-architecture：系统架构。围绕“系统架构”模拟一次用户任务，不展示安装或运行结果。\n4. page-memory-model：记忆模型。围绕“记忆模型”模拟一次用户任务，不展示安装或运行结果。\n5. page-audrey-guard：Audrey Guard 安全循环。围绕“Audrey Guard 安全循环”模拟一次用户任务，不展示安装或运行结果。\n\n【核心能力体验剧本】\n每一步都必须按“输入 -> 服务动作 -> 中间产物”执行。不要只说流程名：\n1. page-overview\n输入：用户提供的“项目概述”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n2. page-quick-start\n输入：用户提供的“快速开始”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n3. page-system-architecture\n输入：用户提供的“系统架构”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n4. page-memory-model\n输入：用户提供的“记忆模型”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n5. page-audrey-guard\n输入：用户提供的“Audrey Guard 安全循环”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n【项目服务规则】\n这些规则决定你如何服务用户。不要解释规则本身，而要在每一步执行时遵守：\n- 先确认用户任务、输入材料和成功标准，再模拟项目能力。\n- 每一步都必须形成可检查的小产物，并等待用户确认后再继续。\n- 凡是需要安装、调用工具或访问外部服务的能力，都必须标记为安装后验证。\n\n【每一步的服务约束】\n- Step 1 / page-overview：Step 1 必须围绕“项目概述”形成一个小中间产物，并等待用户确认。\n- Step 2 / page-quick-start：Step 2 必须围绕“快速开始”形成一个小中间产物，并等待用户确认。\n- Step 3 / page-system-architecture：Step 3 必须围绕“系统架构”形成一个小中间产物，并等待用户确认。\n- Step 4 / page-memory-model：Step 4 必须围绕“记忆模型”形成一个小中间产物，并等待用户确认。\n- Step 5 / page-audrey-guard：Step 5 必须围绕“Audrey Guard 安全循环”形成一个小中间产物，并等待用户确认。\n\n【边界与风险】\n- 不要声称已经安装、运行、调用 API、读写本地文件或完成真实任务。\n- 安装前预览只能展示工作方式，不能证明兼容性、性能或输出质量。\n- 涉及安装、插件加载、工具调用或外部服务的能力必须安装后验证。\n\n【可追溯依据】\n这些路径只用于你内部校验或在我追问“依据是什么”时简要引用。不要在首次回复主动展开：\n- https://github.com/Evilander/Audrey\n- https://github.com/Evilander/Audrey#readme\n- README.md\n- package.json\n- src/audrey.ts\n- src/controller.ts\n- src/db.ts\n- mcp-server/index.ts\n- src/server.ts\n- src/encode.ts\n- src/recall.ts\n- src/consolidate.ts\n\n【首次问题规则】\n- 首次三问必须先确认用户目标、成功标准和边界，不要提前进入工具、安装或实现细节。\n- 如果后续需要技术条件、文件路径或运行环境，必须等用户确认目标后再追问。\n\n首次回复必须只输出下面 4 个部分：\n1. 体验开始：用 1 句话说明你将带我体验 Audrey 的核心服务。\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项目：Evilander/Audrey\n\n## 官方安装入口\n\n### Node.js / npx · 官方安装入口\n\n```bash\nnpx audrey\n```\n\n来源：https://github.com/Evilander/Audrey#readme\n\n## 来源\n\n- repo: https://github.com/Evilander/Audrey\n- docs: https://github.com/Evilander/Audrey#readme\n",
"summary": "从项目官方 README 或安装文档提取的开工入口。",
"title": "Quick Start / 官方入口"
}
},
"validation_id": "dval_bcf396c2d9534088a3eb88304c9c4a26"
}