核心定位

问题背景

AI 代理在长时间运行和跨会话工作时面临以下挑战：

• 记忆缺失：代理会忘记昨天犯下的具体错误
• 重复错误：代理会重复执行之前失败过的命令
• 规则丢失：项目特定的规则在不同会话间丢失
• 矛盾忽略：代理忽视上下文中的矛盾信息
• 冷启动：每次新会话都像从零开始

解决方案

Audrey Guard 是项目的核心循环机制，其工作流程如下：

1. 记录（Record）：记录代理的操作和结果
2. 记忆（Remember）：记住重要的内容
3. 检查（Check）：在行动前进行检查
4. 决策（Decide）：返回 allow（允许）、warn（警告）或 block（阻止）决策，并附带证据
5. 验证（Validate）：验证记忆是否真正帮助了代理

资料来源：README.md:1-25

graph TD
    A[代理执行工具] --> B{Audrey Guard 检查}
    B -->|允许| C[执行工具]
    B -->|警告| D[返回警告+证据]
    B -->|阻止| E[阻止执行]
    C --> F[记录结果到记忆]
    D --> F
    F --> G{验证成功?}
    G -->|是| H[强化记忆+置信度↑]
    G -->|否| I[弱化记忆+衰减]

功能架构

多层客户端支持

资料来源：README.md:88-95

存储架构

Audrey 采用本地存储方案，无需托管数据库：

• SQLite：主数据库，使用 WAL 模式
• sqlite-vec：向量检索扩展

graph LR
    A[代理应用] -->|REST API| B[Hono Server]
    A -->|MCP| B
    B --> C[SQLite + WAL]
    B --> D[sqlite-vec]

重要约束：SQLite 使用 WAL 模式但无咨询锁，两个进程共享同一目录会导致写竞争。多代理场景下，每个租户、代理身份或并发主机必须设置独立的 AUDREY_DATA_DIR。

资料来源：README.md:107-109

记忆模型

Audrey 内置了针对代理场景优化的多维度记忆系统：

记忆类型

资料来源：README.md:111-120

记忆生命周期

graph TD
    A[新记忆写入] --> B{首次编码}
    B --> C[验证循环]
    C -->|收到反馈| D[置信度更新]
    C -->|重复触发| E[证据积累]
    D --> F[巩固 Consolidation]
    E --> F
    F --> G[衰减 Decay 检查]
    G -->|过期/低置信度| H[降级处理]
    G -->|活跃| I[高优先级召回]

高级特性

• 干扰与衰减（Interference & Decay）：过时、冲突或低置信度的记忆会随时间失去权威性
• 矛盾处理（Contradiction Handling）：对竞争的声明进行追踪而非静默覆盖
• 工具追踪学习（Tool-trace Learning）：从工具执行轨迹中提取学习模式

资料来源：README.md:121-124

REST API

端点概览

资料来源：README.md:85-87

请求示例

import Audrey from 'audrey';

const brain = new Audrey({
  base_url: "http://127.0.0.1:7437",
  agent: "support-agent"
});

brain.encode(
  "Stripe returns HTTP 429 above 100 req/s",
  source: "direct-observation",
  tags: ["stripe", "rate-limit"]
);

const results = brain.recall("stripe rate limits", limit: 5);
brain.close();

资料来源：python/README.md:30-45

部署模式

部署方式

MCP 配置

Audrey 提供针对多种主机的 MCP 配置生成：

npx audrey mcp-config codex
npx audrey mcp-config generic
npx audrey mcp-config vscode

Claude Code 还可以直接注册：

npx audrey install
claude mcp list

资料来源：README.md:96-102

Claude Code 钩子配置

graph LR
    A[Claude Code] -->|PreToolUse| B[audrey guard --hook]
    A -->|PostToolUse| C[记录脱敏工具轨迹]
    A -->|PostToolUseFailure| C
    B --> D{决策}
    D -->|allow| E[继续执行]
    D -->|warn| F[警告+证据]
    D -->|block| G[阻止执行]

预览钩子配置：

npx audrey hook-config claude-code

应用钩子配置：

npx audrey hook-config claude-code --apply --scope project
npx audrey hook-config claude-code --apply --scope user

资料来源：mcp-server/index.ts:1-50

安全机制

认证与授权

⚠️ 除非设置 AUDREY_API_KEY，否则只能绑定到 0.0.0.0。

资料来源：README.md:127-133

安全改进（v0.22+）

• HTTP /v1/recall 和 /v1/capsule 不再将调用者选项体展开到 audrey.recall()，防止 includePrivate: true 和 confidenceConfig 覆盖绕过私有记忆 ACL
• audrey serve 默认为 127.0.0.1 绑定，非回环主机无 API key 拒绝启动
• HTTP API key 比较使用 crypto.timingSafeEqual 防止前缀匹配时序泄露
• audrey promote --yes 拒绝写入 process.cwd() 之外的 .claude/rules/*.md，防止恶意 MCP 调用者注入持久化提示

资料来源：CHANGELOG.md:1-100

环境变量配置

核心配置

记忆配置

资料来源：README.md:134-145

性能指标

v0.22.0 性能改进

优化策略：编码过程中消除了 4 个冗余嵌入调用中的 3 个，验证、干扰和情感共鸣现在复用主内容向量。

资料来源：CHANGELOG.md:25-50

规则编译与推广

当记忆达到足够置信度时，可通过 audrey promote 将记忆提升为持久化规则文件：

graph TD
    A[高置信度记忆] --> B[PromotionCandidate]
    B --> C{rules-compiler.ts}
    C --> D[.claude/rules/<slug>.md]
    D --> E[YAML frontmatter]
    E --> F[source memory_ids]
    E --> G[confidence + evidence_count]
    E --> H[promotion_timestamp]

每个规则文件包含：

• 标题：从记忆中推断
• Slug：自动生成
• 相对路径：.claude/rules/<slug>.md
• 正文：规则内容
• Frontmatter：源记忆追踪信息

资料来源：src/rules-compiler.ts:1-30

记忆胶囊（Capsule）

Capsule 是回合级记忆数据包，按不同分类组织记忆：

资料来源：src/capsule.ts:1-80

生产就绪检查

发布门控

npm run release:gate
python -m unittest discover -s python/tests -v
npm run python:release:check
npm run bench:guard:card
npm run bench:guard:validate
npx audrey doctor
npx audrey demo

生产环境建议

1. 每个租户、环境或隔离边界设置独立的 AUDREY_DATA_DIR
2. 明确指定 AUDREY_EMBEDDING_PROVIDER 和 AUDREY_LLM_PROVIDER
3. 提供者或维度变更前备份 SQLite 数据目录
4. 编码记忆内容中排除 API key 和原始凭证
5. REST sidecar 可被本地进程外访问时使用 AUDREY_API_KEY
6. 定期运行 npx audrey dream 以保持巩固和衰减活跃
7. 监管环境需添加应用级加密、保留策略、访问控制和审计日志

资料来源：README.md:70-85

技术栈

资料来源：python/README.md:1-30

许可

Audrey 采用 MIT 许可证开源。

资料来源：README.md:1

本页面将引导您完成 Audrey 的完整安装、配置和基础使用流程。

环境要求

资料来源：README.md:1-15

安装方式

npm 全局安装

Audrey 作为 npm 包发布，可通过 npx 直接运行：

npx audrey serve

或全局安装以获得更好的离线体验：

npm install -g audrey

资料来源：README.md:88-92

Python SDK 安装

如需在 Python 项目中使用 Audrey：

pip install audrey-memory

本地开发模式安装：

cd python
python -m pip install -e .

资料来源：python/README.md:1-18

启动服务

启动 REST API 服务

Audrey 的 REST API 是核心通信接口，CLI、Python SDK 和 MCP 服务器都依赖此接口：

npx audrey serve

服务默认绑定到 127.0.0.1:7437，可通过环境变量修改：

资料来源：README.md:98-115

启动 MCP 服务器

MCP 服务器提供 20 个工具和多个资源端点：

npx audrey mcp-config <host>

支持的 host 类型：

• codex — Codex 代理
• generic — 通用 MCP 客户端
• vscode — VS Code 代理

资料来源：mcp-server/index.ts:1-30

基础使用流程

架构概览

graph TD
    subgraph 客户端层
        CLI[CLI<br/>audrey 命令]
        MCP[MCP 服务器<br/>stdio 连接]
        REST[REST API<br/>HTTP 请求]
        Python[Python SDK<br/>Python 客户端]
    end
    
    subgraph 核心服务
        Server[Hono 服务器<br/>:7437]
        Audrey[Audrey 核心引擎<br/>记忆处理]
    end
    
    subgraph 存储层
        SQLite[(SQLite<br/>主数据库)]
        Vec[(sqlite-vec<br/>向量索引)]
    end
    
    CLI --> Server
    MCP --> Server
    REST --> Server
    Python --> Server
    Server --> Audrey
    Audrey --> SQLite
    Audrey --> Vec

内存编码与检索

#### Python SDK 使用

from audrey_memory import Audrey

brain = Audrey(
    base_url="http://127.0.0.1:7437",
    api_key="secret",
    agent="support-agent",
)

# 编码记忆
memory_id = brain.encode(
    "Stripe 返回 HTTP 429 超过 100 req/s",
    source="direct-observation",
    tags=["stripe", "rate-limit"],
)

# 检索相关记忆
results = brain.recall("stripe rate limit", limit=5)

# 获取快照
snapshot = brain.snapshot()
brain.close()

资料来源：python/README.md:20-60

#### REST API 调用

资料来源：README.md:68-74

异步使用

import asyncio
from audrey_memory import AsyncAudrey

async def main() -> None:
    async with AsyncAudrey(base_url="http://127.0.0.1:7437") as brain:
        await brain.health()
        await brain.encode("部署失败因 OOM", source="direct-observation")
        await brain.recall("部署失败", limit=3)

asyncio.run(main())

资料来源：python/README.md:62-75

Guard 模式：记忆前置检查

Audrey Guard 是核心反馈循环：在执行工具操作前检查记忆，返回 allow、warn 或 block 并附带证据。

CLI Guard 命令

npx audrey guard --tool Bash "npm run deploy"

集成 Claude Code

预览钩子配置：

npx audrey hook-config claude-code

应用钩子配置：

# 项目级钩子
npx audrey hook-config claude-code --apply --scope project

# 用户级钩子
npx audrey hook-config claude-code --apply --scope user

生成的 PreToolUse 钩子运行 audrey guard --hook --fail-on-warn，PostToolUse 和 PostToolUseFailure 钩子记录脱敏的工具追踪。

资料来源：README.md:75-82

Guard 工作流程

graph TD
    A[代理执行工具] --> B{PreToolUse 钩子}
    B --> C[调用 audrey guard]
    C --> D[查询记忆库]
    D --> E{决策判断}
    E -->|allow| F[允许执行]
    E -->|warn| G[警告执行]
    E -->|block| H[阻止执行]
    G --> I{用户确认?}
    I -->|是| F
    I -->|否| H
    F --> J[PostToolUse 钩子]
    H --> K[记录阻止事件]
    J --> L[编码执行结果]
    K --> L

开发环境配置

从源码构建

npm ci
npm run build
npm test

构建后，CLI 子命令解析本地 dist/ 输出。

资料来源：README.md:135-145

完整发布门控

npm run release:gate
python -m unittest discover -s python/tests -v
npm run python:release:check

诊断与验证

健康检查

npx audrey doctor
npx audrey doctor --json

状态检查

npx audrey status --json --fail-on-unhealthy

影响评估

Audrey 提供影响评估功能，跟踪记忆的验证状态和使用情况：

npx audrey impact --window 30

返回内容包括：

• 按类型统计（情景记忆、语义记忆、程序记忆）
• 窗口期内的验证数量
• 结果分布（helpful、wrong、used）
• 高频使用的记忆条目
• 活跃度最弱的记忆条目

资料来源：src/impact.ts:1-50

规则编译与提升

规则编译

Audrey 支持将记忆提升为可审查的 Markdown 规则文件：

npx audrey promote

生成的规则文件位于 .claude/rules/ 目录，包含 YAML 前置元数据，记录源记忆 ID、置信度、证据数量和提升时间戳。

资料来源：src/rules-compiler.ts:1-30

规则文件结构

概述

Audrey 是一个本地优先的 AI 代理内存防火墙（local-first memory firewall），为 Codex、Claude Code、Cursor、Windsurf 等 AI 代理提供持久化的记忆层。其核心设计目标是在代理执行操作前检查记忆，在操作后记录经验，形成闭环的学习-验证机制。

系统架构采用分层设计，核心层基于 TypeScript 实现，通过 MCP（Model Context Protocol）协议与各类 AI 代理集成，同时提供 REST API 和 Python SDK 供外部调用。

架构总览

graph TB
    subgraph 代理层
        A[Claude Code] 
        B[Codex] 
        C[Cursor] 
        D[VS Code]
    end
    
    subgraph 协议层
        E[MCP stdio 服务器]
        F[REST API 服务器]
        G[CLI 接口]
    end
    
    subgraph 核心引擎
        H[Audrey 核心]
        I[记忆模型]
        J[检索引擎]
    end
    
    subgraph 存储层
        K[SQLite]
        L[sqlite-vec 向量索引]
    end
    
    A --> E
    B --> E
    C --> E
    D --> E
    
    F --> H
    E --> H
    G --> H
    
    H --> I
    H --> J
    
    I --> K
    J --> L
    J --> K

核心组件

Audrey 核心引擎

核心引擎位于 src/audrey.ts，是整个系统的心脏，负责记忆的编码、检索、衰减和一致性管理。

数据库层

数据持久化采用双索引架构，同时支持 SQLite 原生查询和向量相似度检索。

重要：SQLite 使用 WAL 模式但无咨询锁，多进程共享同一目录会产生写竞争。每个租户或代理必须设置独立的 AUDREY_DATA_DIR。

资料来源：src/db.ts:1-100

MCP 服务器

MCP 服务器（mcp-server/index.ts）提供标准化的工具接口，使 Audrey 能以 stdio 模式与各类 AI 代理通信。

支持的 MCP 工具集（共 20 个工具）：

MCP 服务器通过以下步骤与代理集成：

1. 解析命令行参数（host 类型、dry-run 模式等）
2. 生成特定代理的配置文件
3. 启动 stdio 连接循环
4. 处理工具调用请求

资料来源：mcp-server/index.ts:1-150

REST API 服务器

REST API 基于 Hono 框架构建，提供轻量级的 HTTP 接口。

可用路由：

安全特性：

• 默认绑定 127.0.0.1，禁止非本地访问
• 非环回地址必须提供 AUDREY_API_KEY
• HTTP API Key 比较使用 crypto.timingSafeEqual 防止时序攻击

资料来源：src/routes.ts:1-100, src/server.ts:1-80

记忆模型

Audrey 实现了一套多维记忆模型，模拟人类记忆的复杂性。

graph LR
    A[观察/交互] --> B[编码]
    B --> C[情景记忆]
    B --> D[语义记忆]
    B --> E[程序记忆]
    C --> F[信任度计算]
    D --> F
    E --> F
    F --> G{衰减/强化}
    G -->|高信任| H[长期记忆]
    G -->|低信任| I[遗忘]

记忆类型

信任度与衰减

每条记忆关联一个信任度分数（0-1），通过以下公式计算：

new_confidence = old_confidence + (evidence_weight * reinforcement_factor)

衰减采用半衰期模型：

decayed = original * 0.5^(days_elapsed / half_life_days)

半衰期必须大于 0，否则抛出 RangeError。

资料来源：src/audrey.ts:200-350, src/impact.ts:50-120

工作流程

Guard 循环（核心安全环）

sequenceDiagram
    participant Agent as AI 代理
    participant Guard as Audrey Guard
    participant Memory as 记忆存储
    participant User as 用户
    
    Agent->>Guard: 执行操作前请求
    Guard->>Memory: 检索相关记忆
    Memory-->>Guard: 历史经验和规则
    Guard->>Guard: 分析风险和矛盾
    Guard-->>Agent: allow / warn / block + 证据
    
    alt allow
        Agent->>User: 执行操作
        Agent->>Guard: 操作结果
        Guard->>Memory: 记录经验
    else warn
        Agent->>Agent: 显示警告给用户
        User-->>Agent: 确认/取消
    end

Guard 命令行用法：

audrey guard --tool Bash "npm run deploy"
audrey guard --hook --fail-on-warn  # MCP 钩子模式

资料来源：mcp-server/index.ts:150-300

记忆编码流程

graph TD
    A[输入文本] --> B[生成 ULID]
    B --> C[计算向量嵌入]
    C --> D[情感分析]
    D --> E[检查矛盾]
    E --> F{发现矛盾?}
    F -->|是| G[标记为 disputed]
    F -->|否| H[正常状态]
    G --> I[存储记忆]
    H --> I
    I --> J[更新向量索引]
    J --> K[返回 memory_id]

记忆编码支持以下元数据：

资料来源：src/audrey.ts:350-500

检索流程

Audrey 支持三种检索模式：

检索选项白名单（HTTP API 强制校验）：

• query、limit、scope
• tags、sources（数组）
• after、before（时间范围）
• retrieval（hybrid/vector）

资料来源：src/routes.ts:50-150

数据流与隐私

工具调用脱敏

在记录工具调用结果前，系统自动脱敏敏感信息：

const SENSITIVE_KEY_PATTERN = /(password|secret|api[_-]?key|token)$/i;

脱敏规则覆盖：

• API 密钥和令牌
• 密码和私钥
• Bearer Token
• AWS 密钥
• JWT

资料来源：src/redact.ts:50-100

私有记忆隔离

私有记忆通过 private: true 标记，仅创建者 agent 可检索。HTTP API 的 /v1/recall 端点实施 ACL 检查，防止跨代理泄露。

注意：includePrivate: true 不能通过 HTTP 请求体传入（安全修复 v0.22.0）。

部署架构

多租户隔离

graph TB
    subgraph 主机 A
        A1[Agent 1]
        A2[AUDREY_DATA_DIR=/data/agent1]
    end
    
    subgraph 主机 B
        B1[Agent 2]
        B2[AUDREY_DATA_DIR=/data/agent2]
    end
    
    subgraph 主机 C
        C1[Agent 3]
        C2[AUDREY_DATA_DIR=/data/agent3]
    end
    
    A1 --> A2
    B1 --> B2
    C1 --> C2

环境变量配置

启动方式

规则编译与推广

当需要将记忆固化为持久规则时，Audrey 提供规则编译功能：

graph LR
    A[PromotionCandidate] --> B[规则编译]
    B --> C[Markdown 文件]
    C --> D[.claude/rules/]
    D --> E[Claude Code 提示]

规则文件格式：

概述

Audrey 的记忆模型是一个专为 AI 代理设计的本地优先记忆防火墙，旨在解决代理"遗忘昨日错误"的核心问题。该模型通过多层次、可验证的记忆系统，使代理能够在执行操作前检查相关记忆，从而避免重复犯错、保持项目特定规则的连续性。资料来源：README.md

核心架构

Audrey 记忆模型采用三层记忆架构，结合情感权重和干扰衰减机制，形成一个动态、可自适应的记忆系统。

graph TD
    A[用户交互/工具执行] --> B[事件编码]
    B --> C{记忆类型分类}
    C --> D[情节记忆<br/>Episodic]
    C --> E[语义记忆<br/>Semantic]
    C --> F[程序记忆<br/>Procedural]
    D --> G[记忆存储]
    E --> G
    F --> G
    G --> H[检索系统]
    H --> I{mood 影响}
    H --> J{干扰检测}
    H --> K{衰减处理}
    I --> L[最终检索结果]
    J --> L
    K --> L
    L --> M[Preflight 检查]
    M --> N{allow/warn/block}

记忆类型体系

Audrey 将记忆划分为三种核心类型，每种类型具有不同的生命周期和用途。

情节记忆 (Episodic Memory)

情节记忆记录特定的观察结果、工具执行结果、用户偏好和会话事实。它是系统获取新知识的主要入口，通常来源于直接观察或用户告知。资料来源：README.md

语义记忆 (Semantic Memory)

语义记忆是从重复证据中提炼出的巩固原则。它代表了系统经过验证的核心信念，要求更高的置信度门槛才能晋升为语义记忆。资料来源：README.md

语义记忆的晋升条件：

// 资料来源：src/promote.ts
if (evidence < Math.max(minEvidence, 3)) continue;
if ((row.contradicting_count ?? 0) > 0) continue;

晋升要求：

• 至少 3 条证据支持
• 无矛盾证据记录
• 状态为活跃 (active)

程序记忆 (Procedural Memory)

程序记忆记录"如何行动、如何避免、如何重试、如何验证"的具体步骤。它直接关联工具使用和操作流程。资料来源：README.md

程序记忆的晋升条件相对宽松，关注实用性：

// 资料来源：src/promote.ts
if ((row.failure_prevented ?? 0) > 0) {
  reasonParts.push(`${row.failure_prevented} failure prevented`);
}
if ((row.usage_count ?? 0) > 0) {
  reasonParts.push(`used ${row.usage_count} time(s)`);
}

置信度与强化机制

置信度计算

Audrey 使用基于证据和支持度的置信度计算模型，通过 confidence.ts 模块实现强化公式。

graph LR
    A[新证据] --> B{证据类型}
    B -->|支持性| C[supporting_count++]
    B -->|矛盾性| D[contradicting_count++]
    C --> E[置信度计算]
    D --> E
    E --> F{salience 更新}

强化反馈循环

Audrey 实现了闭环反馈机制，通过 memory_validate 工具收集用户反馈并调整记忆权重。

资料来源：CHANGELOG.md

情感与显著性系统

情感影响 (Affect)

情感影响基于记忆的情感权重和唤醒度 (arousal)，影响检索结果的排序和优先级。

// 资料来源：src/capsule.ts
if (trustedControlSource && hashMatchesAny(lowerTags, MUST_FOLLOW_TAGS)) {
  sections.add('must_follow');
}

if (result.source === 'told-by-user') {
  sections.add('user_preferences');
}

显著性 (Salience)

显著性决定记忆在检索时的权威程度，受以下因素影响：

• 使用频率 (usage_count)
• 上次使用时间 (last_used_at)
• 证据强度 (evidence_count)
• 情感权重

资料来源：src/impact.ts

干扰与衰减机制

干扰检测 (Interference)

当存在相互矛盾的证据时，系统不会静默覆盖，而是跟踪这些矛盾状态。资料来源：README.md

graph TD
    A[新记忆] --> B{与现有记忆冲突?}
    B -->|是| C[标记为 disputed]
    B -->|否| D[正常存储]
    C --> E[跟踪矛盾证据]
    E --> F[保留双方记录]
    D --> G[更新支持度]

衰减处理 (Decay)

陈旧、冲突或低置信度的记忆会随时间降低权威性，确保最新、最准确的信息占据主导地位。资料来源：README.md

衰减考虑因素：

• 时间间隔（半衰期）
• 检索频率
• 矛盾证据数量
• 最后强化时间

记忆胶囊 (Memory Capsule)

记忆胶囊是一种 turn-sized 的记忆数据包，用于在特定上下文中快速获取相关记忆。

胶囊分段

// 资料来源：src/capsule.ts
const sections = new Set<keyof MemoryCapsule['sections']>();

if (trustedControlSource && hashMatchesAny(lowerTags, MUST_FOLLOW_TAGS)) {
  sections.add('must_follow');
}

if (hashMatchesAny(lowerTags, RISK_TAGS)) {
  sections.add('risks');
}

if (entry.memory_type === 'procedural') {
  sections.add('procedures');
}

if (result.confidence < 0.55) {
  sections.add('uncertain_or_disputed');
}

胶囊分区表

记忆验证流程

Preflight 检查

在执行工具操作前，系统执行预检查以确保行动的安全性。

graph TD
    A[工具调用请求] --> B[检索相关记忆]
    B --> C{检查失败历史}
    B --> D{检查风险标记}
    B --> E{检查相关规则}
    B --> F{检查验证程序}
    C --> G{决策生成}
    D --> G
    E --> G
    F --> G
    G --> H{allow/warn/block}

验证反馈

验证结果通过 REST API 端点收集：

资料来源：CHANGELOG.md

规则晋升系统

高质量的程序记忆和语义记忆可以被晋升为可执行的规则文件。

晋升条件对比

资料来源：src/promote.ts

规则编译

规则文件包含 YAML front matter，记录来源记忆 ID、置信度、证据数量等信息。

// 资料来源：src/rules-compiler.ts
export interface RuleDoc {
  title: string;
  slug: string;
  relativePath: string;
  body: string;
  frontmatter: Record<string, unknown>;
}

记忆数据模型

数据库存储

Audrey 使用 SQLite 作为本地存储，结合 sqlite-vec 支持向量检索。

-- 情节记忆表结构（示意）
CREATE TABLE episodes (
  id TEXT PRIMARY KEY,
  content TEXT NOT NULL,
  source TEXT,
  state TEXT DEFAULT 'active',
  salience REAL,
  usage_count INTEGER DEFAULT 0,
  created_at TEXT,
  last_used_at TEXT
);

-- 语义记忆表结构（示意）
CREATE TABLE semantics (
  id TEXT PRIMARY KEY,
  content TEXT NOT NULL,
  state TEXT DEFAULT 'active',
  evidence_count INTEGER DEFAULT 0,
  supporting_count INTEGER DEFAULT 0,
  contradicting_count INTEGER DEFAULT 0,
  confidence REAL,
  salience REAL,
  created_at TEXT
);

检索模式

资料来源：CHANGELOG.md

私有记忆与访问控制

隐私隔离

HTTP /v1/recall 和 /v1/capsule 不再将调用者选项体传播到 audrey.recall()，防止通过 HTTP 请求绕过私有记忆 ACL。资料来源：CHANGELOG.md

选项白名单

// 资料来源：src/routes.ts
const ALLOWED_KEYS: Set<string> = new Set([
  'limit', 'offset', 'agent', 'tags', 'sources',
  'after', 'before', 'context', 'mood', 'retrieval', 'scope'
]);

安全机制

敏感信息脱敏

// 资料来源：src/redact.ts
const SENSITIVE_KEY_PATTERN = /(^|_|-)(password|passwd|pwd|secret|api[_-]?key|auth[_-]?token|bearer[_-]?token|...)$/i;

脱敏状态：

• clean - 无敏感信息
• redacted - 已脱敏

影响统计与监控

记忆统计接口

// 资料来源：src/impact.ts
interface ImpactReport {
  generatedAt: string;
  windowDays: number;
  totals: {
    episodic: number;
    semantic: number;
    procedural: number;
  };
  validatedTotal: number;
  validatedInWindow: number;
  byType: {
    episodic: { validated: number; recent: number };
    semantic: { validated: number; recent: number; challenged: number };
    procedural: { validated: number; recent: number };
  };
  outcomeBreakdownInWindow: {
    helpful: number;
    wrong: number;
    used: number;
  };
  topUsed: MemoryRow[];
  weakest: MemoryRow[];
  recentActivity: MemoryRow[];
}

梦 Consolidation

audrey dream 命令执行记忆巩固和衰减处理，将情节记忆合并为原则并应用衰减机制。资料来源：README.md

建议按计划运行以保持巩固和衰减的最新状态。

环境变量配置

资料来源：README.md

核心概念

安全循环的工作原理

Audrey Guard 采用记录-记忆-检查-响应-验证的闭环设计：

1. 记忆编码 (memory_encode): 将 Agent 的操作经验、错误教训、项目规则编码存储
2. 预检执行 (memory_preflight): 动作执行前查询相关记忆，评估风险等级
3. 决策返回: 输出 allow（允许）、warn（警告）或 block（阻止）决策
4. 反射生成 (memory_reflexes): 将记忆证据转换为可执行的触发-响应指导
5. 反馈验证 (memory_validate): 动作完成后收集结果，更新记忆权重

graph TD
    A[Agent 工具调用请求] --> B[memory_preflight 预检]
    B --> C{查询记忆数据库}
    C --> D[评估风险与规则匹配]
    D --> E{风险等级判断}
    E -->|低风险| F[allow 允许]
    E -->|中风险| G[warn 警告 + 证据]
    E -->|高风险| H[block 阻止]
    F --> I[执行工具]
    G --> I
    H --> J[终止执行]
    I --> K[memory_validate 验证结果]
    K --> L[更新 salience 与 confidence]
    K --> M[反馈循环: helpful/used/wrong]

资料来源：mcp-server/index.ts:58-75

决策类型

资料来源：mcp-server/index.ts:58-65

预检系统 (Preflight)

预检是 Guard 的核心检查模块，在动作执行前全面评估各种风险因素。

检查维度

memory_preflight 从多个维度进行综合评估：

interface PreflightOptions {
  tool: string;                    // 工具名称
  action?: string;                 // 具体动作描述
  sessionId?: string;             // 会话标识
  mode?: 'normal' | 'strict';      // 检查严格程度
  failure_window_hours?: number;   // 失败历史时间窗口
  recent_failure_window_hours?: number;  // 最近失败窗口
  recent_change_window_hours?: number;   // 最近变更窗口
}

资料来源：src/routes.ts:23-36

Memory Capsule 预检内容

预检返回的 Memory Capsule 包含结构化的记忆分段：

graph LR
    A[查询结果] --> B[recent_changes 近期变更]
    A --> C[must_follow 强制规则]
    A --> D[procedures 流程规范]
    A --> E[risks 风险提示]
    A --> F[user_preferences 用户偏好]
    A --> G[uncertain_or_disputed 不确定信息]
    A --> H[project_facts 项目事实]

资料来源：src/capsule.ts:35-60

风险标签系统

预检模块使用标签系统标记不同类型的风险记忆：

资料来源：src/capsule.ts:62-85

近期失败检测

预检自动查询最近 7 天内的工具失败记录，识别反复出现的错误模式：

const failures = recentFailures(db, {
  since: new Date(Date.now() - 7 * 24 * 60 * 60 * 1000).toISOString(),
  limit: 5
});

这些失败记录会自动添加到 Capsule 的 risks 分段，作为动作前的警告依据。

资料来源：src/capsule.ts:52-56

反射机制 (Reflexes)

memory_reflexes 是 Audrey Guard 的触发-响应转换层，将历史记忆转化为 Agent 可直接执行的指导规则。

反射生成流程

graph TD
    A[记忆事件] --> B[提取证据内容]
    B --> C[识别触发条件]
    C --> D[生成响应规则]
    D --> E[格式化为 Markdown]
    E --> F[添加 YAML 前置元数据]
    F --> G[持久化到规则文件]

规则文件结构

Audrey 将反射规则存储为 Markdown 文件，包含 YAML 前置元数据：

存储架构概述

Audrey 采用单文件本地数据库架构，所有记忆数据存储在 SQLite 数据库中，无需外部托管数据库服务。这种设计确保了：

• 数据主权：所有数据保留在本地文件系统
• 零依赖：不依赖 PostgreSQL、Redis 等外部服务
• 便携性：通过备份整个数据目录即可迁移整个记忆状态
• 事务完整性：SQLite 的 ACID 特性保证数据一致性

资料来源：README.md:1-30

graph TD
    A[Audrey Server] --> B[SQLite 数据库]
    A --> C[sqlite-vec 向量索引]
    B --> D[episodic_memory 表]
    B --> E[semantic_memory 表]
    B --> F[procedural_memory 表]
    B --> G[memory_events 表]
    C --> H[向量嵌入存储]

数据库文件位置

默认情况下，Audrey 将数据存储在 $PWD/.audrey/audrey.db 目录中，即当前工作目录下的隐藏文件夹内。通过环境变量可以自定义数据目录位置：

# 示例：指定自定义数据目录
AUDREY_DATA_DIR=/home/user/.audrey-staging npx audrey serve

资料来源：README.md:环境变量部分

数据库表结构

Audrey 的记忆模型通过三个核心表实现，分别对应不同的记忆类型：

情景记忆表 (episodic_memory)

存储具体的观察结果、工具执行结果、用户偏好和会话事实。

资料来源：src/impact.ts:1-50

语义记忆表 (semantic_memory)

存储从重复证据中提取的巩固原则和规则。

程序记忆表 (procedural_memory)

存储执行操作的已知方式、避免事项、重试策略和验证方法。

记忆事件表 (memory_events)

审计日志表，记录所有记忆相关的操作事件。

// 事件类型包括:
// - encode: 新记忆编码
// - recall: 记忆检索
// - feedback: 反馈更新
// - consolidate: 记忆巩固
// - decay: 记忆衰减
// - promote: 记忆提升为规则
// - forget: 记忆遗忘

资料来源：src/capsule.ts:1-30

向量检索配置

Audrey 使用 sqlite-vec 扩展提供向量相似度搜索能力。向量检索支持两种模式：

// 检索选项配置
interface RecallOptions {
  query: string;           // 检索查询文本
  limit?: number;          // 返回结果数量限制
  tags?: string[];         // 标签过滤
  sources?: string[];      // 来源类型过滤
  after?: string;          // 时间范围起点 (ISO 格式)
  before?: string;         // 时间范围终点
  scope?: 'shared' | 'agent';  // 共享记忆或代理专属记忆
  retrieval?: 'hybrid' | 'vector';  // 检索模式选择
  context?: Record<string, string>;  // 上下文参数
  mood?: RecallOptions['mood'];      // 情感/优先级配置
}

资料来源：src/routes.ts:1-30

数据库性能优化

PRAGMA 配置

Audrey 对 SQLite 进行了性能调优配置：

如需恢复默认配置：

AUDREY_PRAGMA_DEFAULTS=0 npx audrey serve

资料来源：README.md:环境变量部分

嵌入预热

首次启动时，Audrey 会进行嵌入模型预热以加速后续操作：

冷启动首次编码: 525ms → 预热后: 28ms (约18.7倍提升)

资料来源：CHANGELOG.md:0.22.0 性能部分

数据备份与恢复

手动备份

由于所有数据存储在单一数据库文件，备份非常简单：

# 停止服务后复制数据库目录
cp -r .audrey .audrey.backup-$(date +%Y%m%d)

快照导出与恢复

Audrey 支持生成和恢复记忆快照：

from audrey_memory import Audrey

brain = Audrey(base_url="http://127.0.0.1:7437", api_key="secret")

# 创建快照
snapshot = brain.snapshot()

# 恢复到新的空存储
restore_target = Audrey(base_url="http://127.0.0.1:7437", api_key="secret")
restore_target.restore(snapshot)
restore_target.close()

注意：快照只能恢复到空的存储中。建议使用新的 AUDREY_DATA_DIR 目录作为恢复目标。

资料来源：python/README.md:1-50

数据隔离与多租户

Audrey 通过数据目录实现租户隔离：

# 多实例运行示例
AUDREY_DATA_DIR=/data/tenant-a audrey serve --port 7437 &
AUDREY_DATA_DIR=/data/tenant-b audrey serve --port 7438 &

数据导入导出

导出工具

当启用管理工具时（AUDREY_ENABLE_ADMIN_TOOLS=1），可以通过 REST API 导出数据：

# 启用管理工具
AUDREY_ENABLE_ADMIN_TOOLS=1 npx audrey serve

# 导出数据
curl -X POST http://127.0.0.1:7437/v1/export \
  -H "Authorization: Bearer $AUDREY_API_KEY"

资料来源：README.md:环境变量部分

生产环境建议

# 生产环境备份脚本示例
#!/bin/bash
AUDREY_DATA_DIR="${AUDREY_DATA_DIR:-.audrey}"
BACKUP_DIR="/backups/audrey"
TIMESTAMP=$(date +%Y%m%d_%H%M%S)

mkdir -p "$BACKUP_DIR"
cp -r "$AUDREY_DATA_DIR" "$BACKUP_DIR/audrey-$TIMESTAMP"
echo "Backup completed: $BACKUP_DIR/audrey-$TIMESTAMP"

资料来源：README.md:Production Readiness 部分

数据生命周期

记忆巩固 (Consolidation)

Audrey 通过定期运行 dream 命令执行记忆巩固：

npx audrey dream

巩固过程包括：

• 低置信度记忆衰减
• 高频使用记忆强化
• 矛盾记忆标记处理
• 跨记忆类型关联更新

记忆衰减 (Decay)

置信度低于阈值的记忆会逐渐衰减，失去在检索中的优先级：

// 衰减配置 (half-life 机制)
interface ConfidenceConfig {
  halfLifeDays: number;      // 置信度减半的天数
  decayThreshold: number;    // 触发衰减的最小置信度
  boostOnUse: boolean;       // 使用后是否提升置信度
}

资料来源：src/impact.ts:全文

存储健康检查

使用 CLI 检查存储状态：

# 基本状态检查
npx audrey status

# JSON 格式输出
npx audrey status --json

# 严格模式（不健康时退出码非零）
npx audrey status --json --fail-on-unhealthy

{
  "status": "healthy",
  "database": {
    "path": ".audrey/audrey.db",
    "size_bytes": 1048576,
    "episodic_count": 150,
    "semantic_count": 23,
    "procedural_count": 8
  },
  "vectorIndex": {
    "status": "ready",
    "dimension": 768
  }
}

概述

Audrey通过Model Context Protocol (MCP)实现与各类AI代理（Codex、Claude Code、Claude Desktop、Cursor、Windsurf、VS Code、JetBrains、Ollama等）的本地优先记忆防火墙集成。MCP作为中间协议层，使Audrey能够以工具的形式嵌入到AI代理的工作流程中，在代理执行操作前进行记忆检查和决策过滤。

核心工作流程为：代理请求操作 → Audrey Guard检查记忆层 → 返回allow（允许）、warn（警告）或block（阻止）决策及证据。

资料来源：README.md:1-20

架构设计

系统组件关系

graph TD
    A["AI代理<br/>(Claude Code/Cursor/Codex等)"] -->|MCP协议| B["Audrey MCP Server<br/>mcp-server/index.ts"]
    B -->|stdio/STDIO通信| C["Audrey Core<br/>内存管理层"]
    C -->|SQLite存储| D["记忆存储<br/>episodic/semantic/procedural"]
    
    E["REST API<br/>/v1/*"] -->|HTTP调用| C
    
    F["CLI工具<br/>audrey guard"] -->|命令行接口| C
    
    B -->|工具调用| G["guard<br/>记忆检查工具"]
    B -->|工具调用| H["memory_encode<br/>编码记忆"]
    B -->|工具调用| I["memory_recall<br/>检索记忆"]
    B -->|工具调用| J["memory_feedback<br/>反馈结果"]

MCP通信模式

Audrey MCP Server支持两种通信模式，根据不同宿主环境选择：

资料来源：mcp-server/config.ts:1-50

MCP服务器启动

CLI参数解析

MCP服务器通过命令行参数配置启动行为，支持以下选项：

graph LR
    A["CLI Arguments"] --> B{"参数解析<br/>parseArgs()"}
    B --> C["--host=<value>"]
    B --> D["--dry-run"]
    B --> D2["--include-secrets"]
    
    C --> E["host变量<br/>宿主标识"]
    D --> F["dryRun标志"]
    D2 --> G["includeSecrets标志"]
    
    E --> H["返回对象<br/>{host, dryRun, includeSecrets}"]

参数处理逻辑（伪代码表示）：

资料来源：mcp-server/index.ts:1-80

子命令分发

stateDiagram-v2
    [*] --> HelpCheck
    HelpCheck --> VersionCheck: --help/-h/help
    HelpCheck --> [*]: 退出
    VersionCheck --> [*]: --version/-v/version
    VersionCheck --> [*]: 退出
    
    [*] --> SubcommandDispatch
    SubcommandDispatch --> install: subcommand='install'
    SubcommandDispatch --> uninstall: subcommand='uninstall'
    SubcommandDispatch --> mcp_config: subcommand='mcp-config'
    SubcommandDispatch --> hook_config: subcommand='hook-config'
    SubcommandDispatch --> demo: subcommand='demo'
    SubcommandDispatch --> reembed: subcommand='reembed'
    SubcommandDispatch --> dream: subcommand='dream'
    SubcommandDispatch --> MCP_Server: stdio_loop
    
    install --> [*]
    uninstall --> [*]
    mcp_config --> [*]
    hook_config --> [*]
    demo --> [*]
    reembed --> [*]
    dream --> [*]
    MCP_Server --> [*]

支持的子命令列表：

资料来源：mcp-server/index.ts:100-150

MCP工具接口

工具注册与调用

Audrey通过MCP暴露以下核心工具，AI代理可在执行操作前调用：

Guard工具详解

Guard是Audrey的核心工具，用于在代理执行操作前进行记忆检查：

sequenceDiagram
    participant Agent as AI代理
    participant MCP as Audrey MCP Server
    participant Core as Audrey Core
    participant DB as SQLite存储

    Agent->>MCP: guard(tool, action, context)
    MCP->>Core: beforeAction(options)
    Core->>DB: 查询相关记忆
    DB-->>Core: 记忆记录列表
    Core->>Core: 分析决策<br/>allow/warn/block
    Core->>DB: 记录使用统计
    Core-->>MCP: GuardResult
    MCP-->>Agent: 决策+证据

Guard参数结构（src/routes.ts中定义）：

interface GuardParams {
  tool: string;           // 工具名称
  action: string;         // 操作描述
  cwd?: string;           // 工作目录
  sessionId?: string;     // 会话标识
  files?: string[];       // 相关文件列表
  json?: boolean;         // JSON格式输出
  override?: boolean;     // 覆盖配置
  failOnWarn?: boolean;   // 警告时失败
  explain?: boolean;      // 返回解释
  hook?: boolean;         // Hook模式
  strict?: boolean;       // 严格模式
  includeCapsule?: boolean; // 包含记忆胶囊
}

资料来源：mcp-server/index.ts:200-280 资料来源：src/routes.ts:1-60

Guard返回值结构

Memory Capsule结构

记忆胶囊（Memory Capsule）将检索到的记忆分类组织，便于代理理解和使用：

graph TD
    A["MemoryCapsule"] --> B["sections: 各分区记忆"]
    B --> C["must_follow<br/>必须遵守的规则"]
    B --> D["procedures<br/>操作流程"]
    B --> E["user_preferences<br/>用户偏好"]
    B --> F["risks<br/>风险警告"]
    B --> G["uncertain_or_disputed<br/>不确定/争议"]
    B --> H["recent_changes<br/>近期变更"]
    B --> I["project_facts<br/>项目事实"]

分区分配规则（src/capsule.ts）：

资料来源：src/capsule.ts:1-100

配置生成

宿主配置格式化

MCP Server根据不同宿主类型生成对应格式的配置文件：

graph LR
    A["宿主类型"] --> B{"formatMcpHostConfig()"}
    B -->|codex| C["TOML格式<br/>tomlString()"]
    B -->|其他| D["JSON格式<br/>JSON.stringify()"]
    
    C --> E["[mcp_servers.audrey]<br/>command = ...<br/>args = [...]"]
    D --> F["{\"mcpServers\": {...}}"]

#### Codex配置格式（TOML）

[mcp_servers.audrey]
command = "/path/to/node"
args = ["/path/to/audrey", "mcp"]

[mcp_servers.audrey.env]
AUDREY_DATA_DIR = "/path/to/data"
AUDREY_EMBEDDING_PROVIDER = "openai"

#### 标准JSON配置格式

{
  "mcpServers": {
    "audrey": {
      "command": "node",
      "args": ["/path/to/mcp-server/index.ts"],
      "env": {
        "AUDREY_DATA_DIR": "/path/to/data"
      }
    }
  }
}

资料来源：mcp-server/config.ts:10-60

环境变量构建

function buildAudreyMcpEnv(
  env: Record<string, string | undefined>,
  agent: string,
  options: { includeSecrets?: boolean }
): Record<string, string>

资料来源：mcp-server/config.ts:50-100

安装与配置

安装流程

graph TD
    A["audrey install --host <host>"] --> B["buildInstallArgs()"]
    B --> C["生成MCP安装参数"]
    C --> D["mcp add -s user audrey -e KEY=VALUE -- node audrey mcp"]
    D --> E["调用宿主MCP安装命令"]
    E --> F{"成功?"}
    F -->|是| G["安装完成"]
    F -->|否| H["错误处理"]
    
    A2["--dry-run"] --> I["仅预览配置<br/>不实际安装"]

Claude Code安装步骤

# 1. 预览安装配置
npx audrey install --host claude-code --dry-run

# 2. 实际注册Audrey MCP Server
npx audrey install --host claude-code

# 3. 应用项目级Hook配置
npx audrey hook-config claude-code --apply --scope project

# 4. 应用用户级Hook配置
npx audrey hook-config claude-code --apply --scope user

# 5. 在Claude Code中验证Hook
/hooks

# 6. 验证MCP Server
claude mcp list

Hook配置

Hook配置用于将Audrey集成到代理的请求-响应循环中：

interface HookConfigOptions {
  host: string;
  apply: boolean;        // 是否应用配置
  dryRun: boolean;       // 预览模式
  scope: 'project' | 'user';  // 配置作用域
  projectDir: string;    // 项目目录
  settingsPath?: string; // 配置文件路径
}

资料来源：mcp-server/index.ts:150-200

安全与隐私

数据脱敏

Audrey MCP Server内置敏感信息检测和脱敏机制（src/redact.ts）：

HTTP API安全

资料来源：src/redact.ts:1-80 资料来源：README.md:环境变量部分

诊断与调试

Doctor诊断命令

npx audrey doctor [--json] [--override]

环境变量诊断

资料来源：mcp-server/index.ts:doctor相关函数

性能特性

冷启动优化

嵌入向量优化

• 验证、干扰检测、情感共鸣共享主内容向量
• 消除4次冗余嵌入调用中的3次
• 可选wait_for_consolidation参数实现写后读语义

资料来源：CHANGELOG.md:0.22.0版本

版本历史

资料来源：CHANGELOG.md:版本记录

概述

REST API 作为 Audrey 的远程通信层，默认监听 http://127.0.0.1:7437，提供健康检查、记忆编码、记忆召回、记忆胶囊获取以及管理工具等端点。资料来源：README.md

graph LR
    A[Python SDK] -->|HTTP 请求| B[REST API]
    C[CLI 工具] -->|HTTP 请求| B
    D[外部 Agent] -->|HTTP 请求| B
    B --> E[SQLite + sqlite-vec]
    B --> F[Embedding 服务]

核心端点

Audrey REST API 遵循 /health 和 /v1/* 的路由模式，所有 API 端点都需要通过认证才能访问非本地环回地址。资料来源：CHANGELOG.md

健康检查

记忆操作

管理工具（需启用）

当 AUDREY_ENABLE_ADMIN_TOOLS=1 时，以下端点可用：

请求体结构

所有 POST 端点使用统一的 RouteBody 类型定义，支持丰富的参数选项。资料来源：src/routes.ts:1-50

基础参数

记忆召回参数

Preflight 参数

事件反馈参数

认证机制

API 密钥认证

非环回地址的请求必须提供 Bearer 令牌认证：

Authorization: Bearer <token>

API 密钥通过环境变量 AUDREY_API_KEY 配置。资料来源：CHANGELOG.md

安全措施

1. 时序安全比较：HTTP API 密钥比较使用 crypto.timingSafeEqual 而非字符串 !==，防止前缀匹配时序泄露攻击。资料来源：CHANGELOG.md

1. 选项清理：/v1/recall 和 /v1/capsule 不再将调用者选项直接传播到 audrey.recall()，新增的 sanitizeRecallOptions() 白名单函数会过滤不安全的参数，防止 includePrivate: true 等 ACL 绕过。资料来源：CHANGELOG.md

1. 绑定安全：audrey serve 默认绑定 127.0.0.1（原为 0.0.0.0），非环回主机拒绝启动除非设置了 AUDREY_API_KEY 或明确设置 AUDREY_ALLOW_NO_AUTH=1。资料来源：CHANGELOG.md

环境变量配置

Python SDK 集成

Python 客户端通过 HTTP 调用 REST API 实现所有功能。资料来源：python/README.md

同步客户端

from audrey_memory import Audrey

brain = Audrey(
    base_url="http://127.0.0.1:7437",
    api_key="secret",
    agent="support-agent",
)

memory_id = brain.encode(
    "Stripe returns HTTP 429 above 100 req/s",
    source="direct-observation",
    tags=["stripe", "rate-limit"],
)

results = brain.recall("stripe rate limits", limit=5)
snapshot = brain.snapshot()
brain.close()

异步客户端

import asyncio
from audrey_memory import AsyncAudrey

async def main() -> None:
    async with AsyncAudrey(base_url="http://127.0.0.1:7437") as brain:
        await brain.health()
        await brain.encode("Deploy failed due to OOM", source="direct-observation")
        await brain.recall("deploy failure", limit=3)

asyncio.run(main())

关键修复

• DEFAULT_BASE_URL 已从 http://127.0.0.1:3487 更正为 http://127.0.0.1:7437
• recall() 和 recall_response() 现在能正确解码 /v1/recall 返回的裸露列表
• restore() 现在将快照包装在 {"snapshot": ...} 中以匹配 /v1/import 处理器

部署模式

启动服务

npx audrey serve

Docker 部署

支持通过 Docker 和 Compose 进行容器化部署，REST API 端点暴露在配置的端口上。

数据流

sequenceDiagram
    participant Client as Python/CLI
    participant API as REST API
    participant Audrey as Core Engine
    participant Storage as SQLite+vec

    Client->>API: POST /v1/recall
    API->>API: sanitizeRecallOptions()
    API->>Audrey: recall()
    Audrey->>Storage: 混合检索查询
    Storage-->>Audrey: 相关记忆
    Audrey-->>API: 记忆结果
    API-->>Client: JSON 响应

状态报告

/v1/status 端点返回详细的系统状态，包括：

• 记忆统计（情景记忆、语义记忆、程序性记忆数量）
• 数据库连接状态
• 嵌入服务状态
• LLM 提供商信息

医生检查（Doctor Checks）会验证：

• Node.js 运行时版本（需 >= 20）
• 入口点文件存在性
• 数据目录配置
• 嵌入模型可用性
• 服务绑定安全性

当服务绑定到非环回地址但未配置 API 密钥时，系统会拒绝启动并提示安全风险。资料来源：mcp-server/index.ts

错误处理

HTTP 状态码

验证错误

请求体中的参数经过验证，非法参数会被拒绝并返回详细的错误信息。资料来源：src/routes.ts

与 MCP 协议的关系

REST API 与 MCP（Model Context Protocol）stdio 服务器共享相同的核心引擎，但通过不同的传输层暴露功能：

概述

Audrey CLI 是与 Audrey 记忆系统交互的主要方式之一，支持多种子命令以满足不同的使用场景：

• guard — 记忆驱动的动作预检，在执行危险操作前进行检查
• promote — 将高置信度记忆提升为持久化规则文件
• impact — 生成记忆系统的影响分析报告
• install — 安装和配置 Audrey 与目标主机的集成
• doctor — 诊断 Audrey 环境配置状态
• status — 查看记忆系统当前状态
• dream — 触发记忆巩固与整合过程
• reembed — 重新生成向量嵌入
• hook-config — 生成 Claude Code 钩子配置
• mcp-config — 生成 MCP 服务器配置

资料来源：README.md

命令详解

guard 命令

guard 是 Audrey 的核心安全循环命令，用于在执行工具操作前进行记忆预检。

audrey guard --tool <tool_name> "<action>" [options]

#### 参数说明

#### 返回值

guard 命令返回三种决策结果：

• allow — 允许执行，提供相关记忆上下文
• warn — 警告执行，显示需要注意的记忆内容
• block — 阻止执行，基于记忆中的风险标记

资料来源：mcp-server/index.ts:45-89

#### 执行流程图

graph TD
    A[用户执行 guard 命令] --> B[解析工具名称和动作]
    B --> C[调用 beforeAction 预检]
    C --> D{决策结果}
    D -->|allow| E[显示上下文记忆]
    D -->|caution| F[显示警告和证据]
    D -->|block| G[阻止执行并显示原因]
    E --> H[返回允许状态]
    F --> I[根据配置决定是否阻止]
    G --> J[返回阻止状态]

promote 命令

promote 命令将高置信度的记忆提升为 Claude Code 可读取的规则文件（.claude/rules/*.md）。

audrey promote [--yes] [--dry-run] [--limit <number>]

#### 参数说明

#### 生成的文件格式

提升后的规则文件包含 YAML 前置元数据：

核心架构

模块结构

audrey (SDK)
├── Audrey          # 主类，包含所有记忆操作
├── AsyncAudrey     # 异步版本
├── AudreyError     # 错误类型
└── 类型导出        # 完整的 TypeScript 类型定义

主类概述

Audrey 类是 SDK 的核心，封装了所有与本地记忆存储交互的功能。主要特性包括：

• 记忆编码与检索：支持三种记忆类型的写入和查询
• Preflight 检查：动作执行前的记忆验证
• 记忆胶囊构建：上下文压缩与摘要生成
• 因果链路管理：记忆之间的因果关系追踪
• 健康诊断：运行时状态检查

记忆类型系统

Audrey 采用三层记忆架构，对应神经科学的不同记忆系统：

资料来源：src/audrey.ts

核心 API

记忆编码 (encode)

将信息编码为记忆存入存储系统。

const memoryId = brain.encode(
  "Stripe API 在超过 100 req/s 时返回 HTTP 429",
  source="direct-observation",
  tags=["stripe", "rate-limit"]
);

参数说明：

记忆检索 (recall)

根据查询字符串检索相关记忆。

const results = brain.recall("stripe rate limits", limit=5);

参数说明：

记忆快取 (snapshot/restore)

支持记忆状态的导出与恢复。

// 导出
const snapshot = brain.snapshot();

// 恢复到空存储
restoreTarget.restore(snapshot);

资料来源：python/README.md

Preflight 检查系统

Preflight 是 Audrey 的核心安全机制，在动作执行前验证记忆状态。

工作流程

graph TD
    A[动作请求] --> B[构建 Preflight]
    B --> C{匹配记忆反射?}
    C -->|是| D[返回反射建议]
    C -->|否| E{匹配风险标签?}
    E -->|是| F[生成警告]
    E -->|否| G[检查近期失败]
    G --> H{发现失败记录?}
    H -->|是| I[标记为 caution]
    H -->|否| J[允许执行]
    D --> K[返回决策: allow/warn/block]
    F --> K
    I --> K
    J --> K

返回决策

资料来源：src/reflexes.ts 资料来源：src/preflight.ts

记忆胶囊 (Memory Capsule)

记忆胶囊是上下文压缩机制，将检索到的记忆压缩为可嵌入 LLM 上下文的格式。

胶囊结构

interface MemoryCapsule {
  sections: {
    must_follow: [];      // 必须遵循的规则
    project_facts: [];    // 项目事实
    user_preferences: []; // 用户偏好
    procedures: [];       // 程序流程
    risks: [];            // 风险警告
    contradictions: [];   // 矛盾信息
    recent_changes: [];   // 近期变更
  };
  mood: MoodState;        // 情感状态
  health: HealthStatus;   // 健康状态
}

构建选项

资料来源：src/capsule.ts

记忆反射 (Memory Reflexes)

记忆反射是预定义的动作-响应模式，用于在 Preflight 阶段自动匹配。

反射类型

反射报告构建

const report = await buildReflexReport(audrey, "npm run deploy", {
  includeCapsule: true,
  includePreflight: true
});

资料来源：src/reflexes.ts

HTTP API 层

SDK 底层通过 HTTP REST API 与本地服务通信。

路由结构

参数清理

src/routes.ts 中实现了严格的参数白名单机制：

function sanitizeRecallOptions(opts: Record<string, unknown>): RecallOptions {
  // 仅允许特定字段通过
  const allowedKeys = ['limit', 'tags', 'sources', 'after', 'before', 
                       'context', 'mood', 'retrieval', 'scope'];
  // ...
}

资料来源：src/routes.ts

CLI 命令行接口

guard 命令

在执行工具前运行记忆检查。

audrey guard --tool Bash "npm run deploy"

参数说明：

hook-config 命令

配置 Claude Code 等 IDE 的集成钩子。

audrey hook-config claude-code --apply --scope project

doctor 命令

诊断运行时健康状态。

audrey doctor [--verbose]

检查项：

• Node.js 运行时版本（需 >= 20）
• 数据目录存在性
• MCP 入口点配置
• LLM 提供商配置
• Embedding 提供商配置

资料来源：mcp-server/index.ts

类型系统

核心类型定义

// 记忆条目
interface MemoryEntry {
  id: string;
  content: string;
  memory_type: 'episodic' | 'semantic' | 'procedural';
  created_at: string;
  updated_at?: string;
  salience?: number;
  tags?: string[];
}

// Preflight 结果
interface PreflightResult {
  decision: 'allow' | 'warn' | 'block';
  warnings: PreflightWarning[];
  reflexReport?: MemoryReflexReport;
  capsule?: MemoryCapsule;
}

// 检索选项
interface RecallOptions {
  limit?: number;
  tags?: string[];
  sources?: string[];
  after?: string;
  before?: string;
  context?: Record<string, string>;
  mood?: MoodOptions;
  retrieval?: 'hybrid' | 'vector';
  scope?: 'shared' | 'agent';
}

资料来源：src/types.ts

错误处理

错误类型

错误处理示例

try {
  await brain.recall("query", { limit: -1 });
} catch (error) {
  if (error instanceof AudreyError) {
    console.error(`SDK Error: ${error.message}`);
  }
}

情感状态 (Mood)

Audrey 支持情感状态追踪，用于调整检索和响应行为。

interface MoodState {
  valence: number;      // -1.0 到 1.0，情感正负
  arousal: number;      // 0.0 到 1.0，激活程度
  samples: number;      // 采样数量
}

信任评估 (Confidence)

记忆具有置信度评分，影响检索权重和决策。

衰减机制

function recencyDecay(
  createdAt: Date,
  halfLifeDays: number = 30
): number {
  // 基于时间的衰减计算
}

规则：

• halfLifeDays <= 0 时抛出 RangeError
• 默认半衰期为 30 天
• 置信度基于记忆年龄、验证次数、使用频率综合计算

资料来源：src/causal.ts

因果链路 (Causal Links)

记忆之间可以建立因果关系。

interface CausalLink {
  linkId: string;
  causeId: string;
  effectId: string;
  linkType: 'correlational' | 'causal' | 'counterfactual';
  mechanism: string;
  confidence: number;
  spurious: boolean;
}

LLM 驱动的因果推断

系统使用 LLM 分析记忆对之间的关系，判断是否为因果链接：

1. 构建因果分析 prompt
2. LLM 返回 JSON 格式分析结果
3. 验证响应格式完整性
4. 创建或拒绝因果链路

格式要求：

• spurious: boolean
• mechanism: string
• linkType: string（可选）
• confidence: number（必须为有限数值）

数据安全

敏感信息脱敏

src/redact.ts 实现了多层脱敏机制：

const SENSITIVE_KEY_PATTERN = /(password|secret|api_key|token|...)/i;

脱敏规则：

JSON 递归遍历

脱敏系统递归遍历 JSON 结构，对象、数组、字符串分别处理，保留原始数据结构。

资料来源：src/redact.ts

配置与环境变量

关键环境变量

提供商支持

LLM 提供商：

• OpenAI
• Anthropic
• 本地 Ollama
• 自定义端点

Embedding 提供商：

• local：本地 GPU 加速（默认）
• 云端服务

性能优化

近期版本性能改进 (0.22.0)

优化策略

1. 复用 Embedding：验证、干扰检测、情感共鸣共享主内容向量
2. 预热机制：冷启动时执行预热，避免首次延迟
3. 流式检索：recallStream 支持流式响应

资料来源：CHANGELOG.md

使用示例

基础同步使用

import { Audrey } from 'audrey';

const brain = new Audrey({
  baseUrl: 'http://127.0.0.1:7437',
  apiKey: 'secret',
  agent: 'support-agent'
});

// 编码新记忆
const memoryId = brain.encode(
  "Deploy 失败是因为 OOM",
  source: "direct-observation",
  tags: ["deploy", "error"]
);

// 检索相关记忆
const results = brain.recall("deploy failure", limit: 3);

// 获取快照
const snapshot = brain.snapshot();

// 关闭连接
brain.close();

异步使用

import { AsyncAudrey } from 'audrey';

async function main() {
  const brain = new AsyncAudrey({
    baseUrl: 'http://127.0.0.1:7437',
    apiKey: 'secret'
  });

  await brain.health();
  await brain.encode("Stripe 返回 HTTP 429");
  
  brain.close();
}

Preflight 检查

const result = await brain.beforeAction({
  tool: 'Bash',
  action: 'npm run deploy',
  cwd: '/project',
  sessionId: 'session-123'
});

if (result.decision === 'block') {
  console.error('操作被阻止:', result.warnings);
  process.exit(1);
}

MCP 服务器集成

Audrey 通过 MCP (Model Context Protocol) 与各种 AI 代理集成：

graph LR
    A[Claude Code] -->|MCP| B[Audrey MCP Server]
    A[Cursor] -->|MCP| B
    A[Windsurf] -->|MCP| B
    B --> C[Local Audrey Service]
    C --> D[(SQLite DB)]

支持的 IDE/工具

• Claude Code
• Claude Desktop
• Cursor
• Windsurf
• VS Code (通过扩展)
• JetBrains IDEs
• Ollama 后端代理
• 自定义代理服务

资料来源：README.md

版本历史关键变更

0.23.0

• 移除 hybrid_strict 检索模式（曾是 hybrid 的别名）
• 新增 closeAsync(timeoutMs?) 方法
• 新增 sanitizeRecallOptions() 参数白名单工具

0.22.0

• 新增 wait_for_consolidation 参数
• 新增 retrieval 参数（hybrid / vector）
• 性能大幅优化

资料来源：CHANGELOG.md

Pitfall Log / 踩坑日志

项目：Evilander/Audrey

摘要：发现 14 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：安装坑 - 来源证据：Audrey 1.0.1 — honest GuardBench gate, Guard time decay, structured validate errors。

1. 安装坑 · 来源证据：Audrey 1.0.1 — honest GuardBench gate, Guard time decay, structured validate errors

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Audrey 1.0.1 — honest GuardBench gate, Guard time decay, structured validate errors
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_135b992964ae468aa28f88ee639816d1 | https://github.com/Evilander/Audrey/releases/tag/v1.0.1 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。

2. 安装坑 · 来源证据：Audrey Guard 0.23.0

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Audrey Guard 0.23.0
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_9c913c644e2c4c099ea01523623f080e | https://github.com/Evilander/Audrey/releases/tag/v0.23.0 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

3. 安装坑 · 来源证据：v0.16.0

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v0.16.0
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_a7c5c62d4f034e50ba2e9c36e0798882 | https://github.com/Evilander/Audrey/releases/tag/v0.16.0 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。

4. 安装坑 · 来源证据：v0.16.1 — Windows MCP fix

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v0.16.1 — Windows MCP fix
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_c0141ccf0a3245ec8c8ba112af7948e0 | https://github.com/Evilander/Audrey/releases/tag/v0.16.1 | 来源讨论提到 windows 相关条件，需在安装/试用前复核。

5. 安装坑 · 来源证据：v0.17.0

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v0.17.0
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_9617863b3f954035926b8670b5bbea29 | https://github.com/Evilander/Audrey/releases/tag/v0.17.0 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

6. 配置坑 · 可能修改宿主 AI 配置

• 严重度：medium
• 证据强度：source_linked
• 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。
• 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。
• 建议检查：列出会写入的配置文件、目录和卸载/回滚步骤。
• 防护动作：涉及宿主配置目录时必须给回滚路径，不能只给安装命令。
• 证据：capability.host_targets | github_repo:1161444210 | https://github.com/Evilander/Audrey | host_targets=mcp_host, claude, claude_code

7. 能力坑 · 能力判断依赖假设

• 严重度：medium
• 证据强度：source_linked
• 发现：README/documentation is current enough for a first validation pass.
• 对用户的影响：假设不成立时，用户拿不到承诺的能力。
• 建议检查：将假设转成下游验证清单。
• 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。
• 证据：capability.assumptions | github_repo:1161444210 | https://github.com/Evilander/Audrey | README/documentation is current enough for a first validation pass.

8. 维护坑 · 维护活跃度未知

• 严重度：medium
• 证据强度：source_linked
• 发现：未记录 last_activity_observed。
• 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
• 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。
• 防护动作：维护活跃度未知时，推荐强度不能标为高信任。
• 证据：evidence.maintainer_signals | github_repo:1161444210 | https://github.com/Evilander/Audrey | last_activity_observed missing

9. 安全/权限坑 · 下游验证发现风险项

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 对用户的影响：下游已经要求复核，不能在页面中弱化。
• 建议检查：进入安全/权限治理复核队列。
• 防护动作：下游风险存在时必须保持 review/recommendation 降级。
• 证据：downstream_validation.risk_items | github_repo:1161444210 | https://github.com/Evilander/Audrey | no_demo; severity=medium

10. 安全/权限坑 · 存在评分风险

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 对用户的影响：风险会影响是否适合普通用户安装。
• 建议检查：把风险写入边界卡，并确认是否需要人工复核。
• 防护动作：评分风险必须进入边界卡，不能只作为内部分数。
• 证据：risks.scoring_risks | github_repo:1161444210 | https://github.com/Evilander/Audrey | no_demo; severity=medium

11. 安全/权限坑 · 来源证据：Audrey 1.0.0

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Audrey 1.0.0
• 对用户的影响：可能影响授权、密钥配置或安全边界。
• 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_d30d964956da40a2b5e26dc7404861f8 | https://github.com/Evilander/Audrey/releases/tag/v1.0.0 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

12. 安全/权限坑 · 来源证据：v0.22.2 — correctness pass + legitimate benchmarking

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v0.22.2 — correctness pass + legitimate benchmarking
• 对用户的影响：可能影响授权、密钥配置或安全边界。
• 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_f9c004c97d31437ebdc3699d6f1ba2f4 | https://github.com/Evilander/Audrey/releases/tag/v0.22.2 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

13. 维护坑 · issue/PR 响应质量未知

• 严重度：low
• 证据强度：source_linked
• 发现：issue_or_pr_quality=unknown。
• 对用户的影响：用户无法判断遇到问题后是否有人维护。
• 建议检查：抽样最近 issue/PR，判断是否长期无人处理。
• 防护动作：issue/PR 响应未知时，必须提示维护风险。
• 证据：evidence.maintainer_signals | github_repo:1161444210 | https://github.com/Evilander/Audrey | issue_or_pr_quality=unknown

14. 维护坑 · 发布节奏不明确

• 严重度：low
• 证据强度：source_linked
• 发现：release_recency=unknown。
• 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
• 建议检查：确认最近 release/tag 和 README 安装命令是否一致。
• 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。
• 证据：evidence.maintainer_signals | github_repo:1161444210 | https://github.com/Evilander/Audrey | release_recency=unknown