# https://github.com/Evilander/Audrey 项目说明书
生成时间：2026-05-16 03:41:21 UTC
## 目录
- [项目概述](#page-overview)
- [快速开始](#page-quick-start)
- [系统架构](#page-system-architecture)
- [记忆模型](#page-memory-model)
- [Audrey Guard 安全循环](#page-audrey-guard)
- [数据存储](#page-data-storage)
- [MCP集成](#page-mcp-integration)
- [REST API](#page-rest-api)
- [CLI工具](#page-cli-tools)
- [JavaScript SDK](#page-javascript-sdk)
## 项目概述
### 相关页面
相关主题：[系统架构](#page-system-architecture), [快速开始](#page-quick-start)
相关源码文件
以下源码文件用于生成本页说明：
- [README.md](https://github.com/Evilander/Audrey/blob/main/README.md)
- [CHANGELOG.md](https://github.com/Evilander/Audrey/blob/main/CHANGELOG.md)
- [python/README.md](https://github.com/Evilander/Audrey/blob/main/python/README.md)
- [src/routes.ts](https://github.com/Evilander/Audrey/blob/main/src/routes.ts)
- [src/capsule.ts](https://github.com/Evilander/Audrey/blob/main/src/capsule.ts)
- [src/rules-compiler.ts](https://github.com/Evilander/Audrey/blob/main/src/rules-compiler.ts)
- [mcp-server/index.ts](https://github.com/Evilander/Audrey/blob/main/mcp-server/index.ts)
# 项目概述
Audrey 是一个为 AI 代理（AI Agents）设计的本地优先（local-first）记忆防火墙项目。它为 Codex、Claude Code、Claude Desktop、Cursor、Windsurf、VS Code、JetBrains、Ollama 后端代理以及自定义代理服务提供了一层持久的记忆层，使这些代理能够在执行工具操作前检查记忆内容。
## 核心定位
### 问题背景
AI 代理在长时间运行和跨会话工作时面临以下挑战：
- **记忆缺失**：代理会忘记昨天犯下的具体错误
- **重复错误**：代理会重复执行之前失败过的命令
- **规则丢失**：项目特定的规则在不同会话间丢失
- **矛盾忽略**：代理忽视上下文中的矛盾信息
- **冷启动**：每次新会话都像从零开始
### 解决方案
Audrey Guard 是项目的核心循环机制，其工作流程如下：
1. **记录**（Record）：记录代理的操作和结果
2. **记忆**（Remember）：记住重要的内容
3. **检查**（Check）：在行动前进行检查
4. **决策**（Decide）：返回 `allow`（允许）、`warn`（警告）或 `block`（阻止）决策，并附带证据
5. **验证**（Validate）：验证记忆是否真正帮助了代理
资料来源：[README.md:1-25]()
```mermaid
graph TD
A[代理执行工具] --> B{Audrey Guard 检查}
B -->|允许| C[执行工具]
B -->|警告| D[返回警告+证据]
B -->|阻止| E[阻止执行]
C --> F[记录结果到记忆]
D --> F
F --> G{验证成功?}
G -->|是| H[强化记忆+置信度↑]
G -->|否| I[弱化记忆+衰减]
```
## 功能架构
### 多层客户端支持
| 客户端类型 | 状态 | 说明 |
|-----------|------|------|
| MCP stdio server | ✅ 稳定 | 提供 20 个工具，以及 status/recent/principles 资源和 briefing/recall/reflection 提示 |
| CLI | ✅ 稳定 | 支持 doctor、demo、guard、install、mcp-config、hook-config、status、dream、reembed、observe-tool、promote、impact 等命令 |
| REST API | ✅ 稳定 | 基于 Hono 框架构建，提供 `/health` 和 `/v1/*` 路由 |
| JavaScript SDK | ✅ 稳定 | 支持直接从 `audrey` 包进行 TypeScript/Node 导入 |
| Python client | ✅ 稳定 | 通过 `pip install audrey-memory` 安装，调用 REST sidecar |
资料来源：[README.md:88-95]()
### 存储架构
Audrey 采用本地存储方案，无需托管数据库：
- **SQLite**：主数据库，使用 WAL 模式
- **sqlite-vec**：向量检索扩展
```mermaid
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 内置了针对代理场景优化的多维度记忆系统：
### 记忆类型
| 记忆类型 | 描述 | 示例 |
|---------|------|------|
| 情景记忆 (Episodic) | 具体的观察、工具结果、偏好和会话事实 | "上次 npm run deploy 因权限失败" |
| 语义记忆 (Semantic) | 从重复证据中提炼的概括性原则 | "在部署前检查权限配置" |
| 程序记忆 (Procedural) | 记住的执行方式、规避方法、重试策略和验证流程 | "恢复失败时使用 git revert" |
| 情感与显著性 (Affect & Salience) | 情感权重和重要性影响召回 | 反复失败的命令标记为高显著性 |
资料来源：[README.md:111-120]()
### 记忆生命周期
```mermaid
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
### 端点概览
| 方法 | 端点 | 功能 |
|------|------|------|
| POST | `/v1/encode` | 编码记忆 |
| POST | `/v1/recall` | 召回相关记忆 |
| POST | `/v1/capsule` | 获取回合级记忆包 |
| GET | `/v1/status` | 健康检查 |
| GET | `/health` | 基础健康状态 |
资料来源：[README.md:85-87]()
### 请求示例
```typescript
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]()
## 部署模式
### 部署方式
| 方式 | 说明 |
|------|------|
| npm 包 | `npm install audrey` |
| Docker | 容器化部署 |
| Compose | docker-compose 编排 |
| MCP 配置生成 | 针对不同主机的 MCP 配置自动生成 |
### MCP 配置
Audrey 提供针对多种主机的 MCP 配置生成：
```bash
npx audrey mcp-config codex
npx audrey mcp-config generic
npx audrey mcp-config vscode
```
Claude Code 还可以直接注册：
```bash
npx audrey install
claude mcp list
```
资料来源：[README.md:96-102]()
### Claude Code 钩子配置
```mermaid
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[阻止执行]
```
预览钩子配置：
```bash
npx audrey hook-config claude-code
```
应用钩子配置：
```bash
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_HOST` | `127.0.0.0.1` | REST sidecar 绑定地址 |
| `AUDREY_API_KEY` | 未设置 | 非回环 REST 流量的 Bearer token |
| `AUDREY_ALLOW_NO_AUTH` | `0` | 允许非回环绑定时无需 API key |
| `AUDREY_ENABLE_ADMIN_TOOLS` | `0` | 启用导出、导入、遗忘路由/工具 |
> ⚠️ 除非设置 `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]()
## 环境变量配置
### 核心配置
| 变量 | 默认值 | 用途 |
|------|--------|------|
| `AUDREY_DATA_DIR` | `.audrey-data/` | 数据存储目录 |
| `AUDREY_EMBEDDING_PROVIDER` | 自动检测 | 向量嵌入提供者 |
| `AUDREY_LLM_PROVIDER` | 自动检测 | LLM 提供者 |
| `AUDREY_DEBUG` | `0` | 启用 MCP 信息日志 |
| `AUDREY_PROFILE` | `0` | 通过 MCP `_meta.diagnostics` 发出各阶段计时 |
| `AUDREY_DISABLE_WARMUP` | `0` | 跳过 MCP 启动时的后台嵌入预热 |
| `AUDREY_PRAGMA_DEFAULTS` | `1` | 是否恢复 SQLite PRAGMA 到 better-sqlite3 默认值 |
### 记忆配置
| 变量 | 默认值 | 用途 |
|------|--------|------|
| `AUDREY_CONTEXT_BUDGET_CHARS` | `4000` | 记忆胶囊默认字符预算 |
| `AUDREY_PROMOTE_ROOTS` | 未设置 | `audrey promote --yes` 写入的额外根目录 |
资料来源：[README.md:134-145]()
## 性能指标
### v0.22.0 性能改进
| 指标 | 改进前 | 改进后 | 提升幅度 |
|------|--------|--------|----------|
| 编码响应时间 p50 | 24.7ms | 15.2ms | ~40% |
| 冷启动首次编码 | 525ms | 28ms（预热后） | 18.7x |
| 混合召回 | 30.2ms | 14.3ms | 2.1x |
**优化策略**：编码过程中消除了 4 个冗余嵌入调用中的 3 个，验证、干扰和情感共鸣现在复用主内容向量。
资料来源：[CHANGELOG.md:25-50]()
## 规则编译与推广
当记忆达到足够置信度时，可通过 `audrey promote` 将记忆提升为持久化规则文件：
```mermaid
graph TD
A[高置信度记忆] --> B[PromotionCandidate]
B --> C{rules-compiler.ts}
C --> D[.claude/rules/.md]
D --> E[YAML frontmatter]
E --> F[source memory_ids]
E --> G[confidence + evidence_count]
E --> H[promotion_timestamp]
```
每个规则文件包含：
- 标题：从记忆中推断
- Slug：自动生成
- 相对路径：`.claude/rules/.md`
- 正文：规则内容
- Frontmatter：源记忆追踪信息
资料来源：[src/rules-compiler.ts:1-30]()
## 记忆胶囊（Capsule）
Capsule 是回合级记忆数据包，按不同分类组织记忆：
| 分类 | 来源条件 |
|------|----------|
| `recent_changes` | 最近变化窗口内创建或强化的记忆 |
| `must_follow` | 标记为必须遵守的规则 |
| `procedures` | 程序性记忆或标记为程序的记忆 |
| `user_preferences` | 用户声明的偏好或标记为用户偏好的记忆 |
| `risks` | 标记为风险或警告的记忆 + 最近工具失败 |
| `uncertain_or_disputed` | 争议性记忆或低置信度记忆 |
资料来源：[src/capsule.ts:1-80]()
## 生产就绪检查
### 发布门控
```bash
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]()
## 技术栈
| 层级 | 技术选型 |
|------|----------|
| 运行时 | Node.js / TypeScript |
| CLI 框架 | 未知（基于 mcp-server/index.ts） |
| REST 框架 | Hono |
| 数据库 | SQLite + sqlite-vec |
| Python SDK | httpx + pydantic |
资料来源：[python/README.md:1-30]()
## 许可
Audrey 采用 MIT 许可证开源。
资料来源：[README.md:1]()
---
## 快速开始
### 相关页面
相关主题：[项目概述](#page-overview), [CLI工具](#page-cli-tools)
相关源码文件
以下源码文件用于生成本页说明：
- [README.md](https://github.com/Evilander/Audrey/blob/main/README.md)
- [python/README.md](https://github.com/Evilander/Audrey/blob/main/python/README.md)
- [src/routes.ts](https://github.com/Evilander/Audrey/blob/main/src/routes.ts)
- [src/impact.ts](https://github.com/Evilander/Audrey/blob/main/src/impact.ts)
- [mcp-server/index.ts](https://github.com/Evilander/Audrey/blob/main/mcp-server/index.ts)
- [src/rules-compiler.ts](https://github.com/Evilander/Audrey/blob/main/src/rules-compiler.ts)
# 快速开始
Audrey 是一个本地优先的 AI 代理内存防火墙，为 Codex、Claude Code、Claude Desktop、Cursor、Windsurf、VS Code、JetBrains、Ollama 后端代理以及自定义代理服务提供持久的内存层。代理可以在执行工具操作前查询此内存层，从而避免重复犯错的命令、保留项目特定规则、发现矛盾信息。
本页面将引导您完成 Audrey 的完整安装、配置和基础使用流程。
## 环境要求
| 组件 | 版本要求 | 说明 |
|------|----------|------|
| Node.js | ≥18.0.0 | 用于运行 CLI 和 MCP 服务器 |
| npm | ≥9.0.0 | 包管理器 |
| Python | ≥3.10 | 如需使用 Python SDK |
| SQLite | 3.39+ | 内置支持，，无需单独安装 |
资料来源：[README.md:1-15]()
## 安装方式
### npm 全局安装
Audrey 作为 npm 包发布，可通过 npx 直接运行：
```bash
npx audrey serve
```
或全局安装以获得更好的离线体验：
```bash
npm install -g audrey
```
资料来源：[README.md:88-92]()
### Python SDK 安装
如需在 Python 项目中使用 Audrey：
```bash
pip install audrey-memory
```
本地开发模式安装：
```bash
cd python
python -m pip install -e .
```
资料来源：[python/README.md:1-18]()
## 启动服务
### 启动 REST API 服务
Audrey 的 REST API 是核心通信接口，CLI、Python SDK 和 MCP 服务器都依赖此接口：
```bash
npx audrey serve
```
服务默认绑定到 `127.0.0.1:7437`，可通过环境变量修改：
| 环境变量 | 默认值 | 说明 |
|----------|--------|------|
| `AUDREY_PORT` | `7437` | REST API 监听端口 |
| `AUDREY_HOST` | `127.0.0.1` | REST API 绑定地址，仅在设置 `AUDREY_API_KEY` 时可设为 `0.0.0.0` |
| `AUDREY_API_KEY` | 未设置 | 非本地流量需要 Bearer token 认证 |
| `AUDREY_DATA_DIR` | `./audrey-data` | SQLite 数据库存储目录 |
资料来源：[README.md:98-115]()
### 启动 MCP 服务器
MCP 服务器提供 20 个工具和多个资源端点：
```bash
npx audrey mcp-config
```
支持的 host 类型：
- `codex` — Codex 代理
- `generic` — 通用 MCP 客户端
- `vscode` — VS Code 代理
资料来源：[mcp-server/index.ts:1-30]()
## 基础使用流程
### 架构概览
```mermaid
graph TD
subgraph 客户端层
CLI[CLI
audrey 命令]
MCP[MCP 服务器
stdio 连接]
REST[REST API
HTTP 请求]
Python[Python SDK
Python 客户端]
end
subgraph 核心服务
Server[Hono 服务器
:7437]
Audrey[Audrey 核心引擎
记忆处理]
end
subgraph 存储层
SQLite[(SQLite
主数据库)]
Vec[(sqlite-vec
向量索引)]
end
CLI --> Server
MCP --> Server
REST --> Server
Python --> Server
Server --> Audrey
Audrey --> SQLite
Audrey --> Vec
```
### 内存编码与检索
#### Python SDK 使用
```python
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 调用
| 端点 | 方法 | 功能 |
|------|------|------|
| `/v1/encode` | POST | 编码新记忆 |
| `/v1/recall` | POST | 检索相关记忆 |
| `/v1/capsule` | POST | 获取回合级记忆包 |
| `/v1/status` | GET | 健康检查 |
资料来源：[README.md:68-74]()
### 异步使用
```python
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 命令
```bash
npx audrey guard --tool Bash "npm run deploy"
```
### 集成 Claude Code
预览钩子配置：
```bash
npx audrey hook-config claude-code
```
应用钩子配置：
```bash
# 项目级钩子
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 工作流程
```mermaid
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
```
## 开发环境配置
### 从源码构建
```bash
npm ci
npm run build
npm test
```
构建后，CLI 子命令解析本地 `dist/` 输出。
资料来源：[README.md:135-145]()
### 完整发布门控
```bash
npm run release:gate
python -m unittest discover -s python/tests -v
npm run python:release:check
```
## 诊断与验证
### 健康检查
```bash
npx audrey doctor
npx audrey doctor --json
```
### 状态检查
```bash
npx audrey status --json --fail-on-unhealthy
```
### 影响评估
Audrey 提供影响评估功能，跟踪记忆的验证状态和使用情况：
```bash
npx audrey impact --window 30
```
返回内容包括：
- 按类型统计（情景记忆、语义记忆、程序记忆）
- 窗口期内的验证数量
- 结果分布（helpful、wrong、used）
- 高频使用的记忆条目
- 活跃度最弱的记忆条目
资料来源：[src/impact.ts:1-50]()
## 规则编译与提升
### 规则编译
Audrey 支持将记忆提升为可审查的 Markdown 规则文件：
```bash
npx audrey promote
```
生成的规则文件位于 `.claude/rules/` 目录，包含 YAML 前置元数据，记录源记忆 ID、置信度、证据数量和提升时间戳。
资料来源：[src/rules-compiler.ts:1-30]()
### 规则文件结构
```yaml
---
title: "Audrey semantic memory xxx"
memory_ids: ["01ARZ3NDEKTSV4RRFFQ69G5FAV"]
confidence: 0.85
evidence_count: 5
promoted_at: "2025-01-15T10:30:00Z"
---
# 规则正文
```
## 内存模型
Audrey 的内存模型包含以下维度：
| 内存类型 | 说明 | 示例 |
|----------|------|------|
| 情景记忆 | 具体观察、工具结果、偏好、会话事实 | "用户在 macOS 上运行，遇到权限错误" |
| 语义记忆 | 从重复证据中提取的巩固原则 | "macOS 需要 sudo 才能安装全局 npm 包" |
| 程序记忆 | 记住的执行方式、避免事项、重试或验证方法 | "先检查 --dry-run，再实际执行" |
| 情感与显著性 | 情感权重和重要性影响召回 | 高情绪记忆更容易被保留 |
| 干扰与衰减 | 陈旧、冲突或低置信度记忆逐渐失去权威性 | 长时间未使用的记忆降低权重 |
| 矛盾处理 | 竞争性声明被追踪而非静默覆盖 | 多条相互矛盾的规则同时标记为待验证 |
资料来源：[README.md:53-68]()
## 数据恢复
### 创建快照
```python
snapshot = brain.snapshot()
# 快照可序列化并保存到外部存储
```
### 恢复快照
```python
restore_target = Audrey(base_url="http://127.0.0.1:7437", api_key="secret")
restore_target.restore(snapshot)
restore_target.close()
```
恢复只能导入到空的 Audrey 存储，例如使用新的 `AUDREY_DATA_DIR` 启动的 sidecar。
资料来源：[python/README.md:48-57]()
## 生产环境注意事项
| 检查项 | 说明 |
|--------|------|
| 数据目录隔离 | 每个租户、环境或隔离边界设置独立的 `AUDREY_DATA_DIR` |
| 嵌入模型锁定 | 明确锁定 `AUDREY_EMBEDDING_PROVIDER` 和 `AUDREY_LLM_PROVIDER` |
| 数据备份 | 提供商或维度变更前备份 SQLite 数据目录 |
| API 密钥保护 | 保持 API 密钥和原始凭据不在编码记忆内容中 |
| 网络访问控制 | REST sidecar 可被外部访问时必须设置 `AUDREY_API_KEY` |
| 定期整合 | 按计划运行 `npx audrey dream` 以保持整合和衰减更新 |
| 监管环境 | 添加应用级加密、保留、访问控制和审计日志 |
资料来源：[README.md:116-132]()
## 常见问题
### Q: 启动时报错 `bind: address already in use`
端口 7437 被占用，可通过 `AUDREY_PORT` 环境变量指定其他端口：
```bash
AUDREY_PORT=7438 npx audrey serve
```
### Q: 远程连接被拒绝
默认情况下服务仅绑定 `127.0.0.1`，如需远程访问：
1. 设置 API 密钥：`AUDREY_API_KEY=your-secret`
2. 修改绑定地址：`AUDREY_HOST=0.0.0.0`
警告：不推荐在生产环境中禁用认证。
### Q: 记忆检索结果不准确
1. 运行 `npx audrey reembed` 重新生成向量索引
2. 调整 `memory_recall` 参数的 `retrieval` 模式（`hybrid` 或 `vector`）
3. 检查相关记忆的置信度是否过低（可能被衰减）
资料来源：[README.md:98-115]()
### Q: MCP 服务器连接失败
确保 MCP 配置正确生成：
```bash
npx audrey mcp-config --dry-run
```
验证 MCP 服务器已启动并监听 stdio。
---
## 系统架构
### 相关页面
相关主题：[项目概述](#page-overview), [记忆模型](#page-memory-model), [数据存储](#page-data-storage)
相关源码文件
以下源码文件用于生成本页说明：
- [src/audrey.ts](https://github.com/Evilander/Audrey/blob/main/src/audrey.ts)
- [src/routes.ts](https://github.com/Evilander/Audrey/blob/main/src/routes.ts)
- [src/db.ts](https://github.com/Evilander/Audrey/blob/main/src/db.ts)
- [mcp-server/index.ts](https://github.com/Evilander/Audrey/blob/main/mcp-server/index.ts)
- [src/server.ts](https://github.com/Evilander/Audrey/blob/main/src/server.ts)
- [src/capsule.ts](https://github.com/Evilander/Audrey/blob/main/src/capsule.ts)
- [src/redact.ts](https://github.com/Evilander/Audrey/blob/main/src/redact.ts)
- [src/rules-compiler.ts](https://github.com/Evilander/Audrey/blob/main/src/rules-compiler.ts)
- [src/impact.ts](https://github.com/Evilander/Audrey/blob/main/src/impact.ts)
# 系统架构
## 概述
Audrey 是一个本地优先的 AI 代理内存防火墙（local-first memory firewall），为 Codex、Claude Code、Cursor、Windsurf 等 AI 代理提供持久化的记忆层。其核心设计目标是在代理执行操作前检查记忆，在操作后记录经验，形成闭环的学习-验证机制。
系统架构采用分层设计，核心层基于 TypeScript 实现，通过 MCP（Model Context Protocol）协议与各类 AI 代理集成，同时提供 REST API 和 Python SDK 供外部调用。
## 架构总览
```mermaid
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`，是整个系统的心脏，负责记忆的编码、检索、衰减和一致性管理。
| 组件 | 职责 | 关键方法 |
|------|------|----------|
| 记忆编码 | 将观察和经验转化为可存储的记忆 | `encode()`, `consolidate()` |
| 检索引擎 | 基于向量和关键词的混合检索 | `recall()`, `recallStream()` |
| 信任度管理 | 基于时间的衰减和证据强化 | `decay()`, `reinforce()` |
| 矛盾处理 | 追踪竞争性记忆而非静默覆盖 | 资料来源：[src/audrey.ts:1-200]() |
### 数据库层
数据持久化采用双索引架构，同时支持 SQLite 原生查询和向量相似度检索。
| 数据库 | 位置 | 用途 |
|--------|------|------|
| SQLite 主库 | `AUDREY_DATA_DIR/memory.db` | 结构化记忆存储 |
| sqlite-vec | `AUDREY_DATA_DIR/vectors.db` | 向量嵌入索引 |
> **重要**：SQLite 使用 WAL 模式但无咨询锁，多进程共享同一目录会产生写竞争。每个租户或代理必须设置独立的 `AUDREY_DATA_DIR`。
资料来源：[src/db.ts:1-100]()
### MCP 服务器
MCP 服务器（`mcp-server/index.ts`）提供标准化的工具接口，使 Audrey 能以 stdio 模式与各类 AI 代理通信。
**支持的 MCP 工具集**（共 20 个工具）：
| 工具分类 | 工具名称 |
|----------|----------|
| 记忆操作 | `memory_encode`, `memory_recall`, `memory_snapshot` |
| 安全防护 | `guard_preflight`, `guard_postflight` |
| 管理功能 | `status`, `introspect`, `dream` |
MCP 服务器通过以下步骤与代理集成：
1. 解析命令行参数（host 类型、dry-run 模式等）
2. 生成特定代理的配置文件
3. 启动 stdio 连接循环
4. 处理工具调用请求
资料来源：[mcp-server/index.ts:1-150]()
### REST API 服务器
REST API 基于 Hono 框架构建，提供轻量级的 HTTP 接口。
**可用路由**：
| 方法 | 路径 | 功能 |
|------|------|------|
| `GET` | `/health` | 健康检查 |
| `POST` | `/v1/encode` | 编码记忆 |
| `POST` | `/v1/recall` | 检索相关记忆 |
| `POST` | `/v1/capsule` | 获取回合级记忆包 |
| `GET` | `/v1/status` | 获取系统状态 |
**安全特性**：
- 默认绑定 `127.0.0.1`，禁止非本地访问
- 非环回地址必须提供 `AUDREY_API_KEY`
- HTTP API Key 比较使用 `crypto.timingSafeEqual` 防止时序攻击
资料来源：[src/routes.ts:1-100](), [src/server.ts:1-80]()
## 记忆模型
Audrey 实现了一套多维记忆模型，模拟人类记忆的复杂性。
```mermaid
graph LR
A[观察/交互] --> B[编码]
B --> C[情景记忆]
B --> D[语义记忆]
B --> E[程序记忆]
C --> F[信任度计算]
D --> F
E --> F
F --> G{衰减/强化}
G -->|高信任| H[长期记忆]
G -->|低信任| I[遗忘]
```
### 记忆类型
| 类型 | 说明 | 典型来源 |
|------|------|----------|
| 情景记忆 | 特定观察、工具结果、偏好、会话事实 | `direct-observation` |
| 语义记忆 | 从重复证据中提取的固化原则 | `consolidated` |
| 程序记忆 | 记住的行动方式、规避策略、验证方法 | `procedure` |
### 信任度与衰减
每条记忆关联一个信任度分数（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 循环（核心安全环）
```mermaid
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 命令行用法**：
```bash
audrey guard --tool Bash "npm run deploy"
audrey guard --hook --fail-on-warn # MCP 钩子模式
```
资料来源：[mcp-server/index.ts:150-300]()
### 记忆编码流程
```mermaid
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]
```
记忆编码支持以下元数据：
| 字段 | 类型 | 说明 |
|------|------|------|
| `source` | string | 记忆来源（direct-observation, told-by-user 等） |
| `tags` | string[] | 标签数组 |
| `memory_type` | enum | episodic / semantic / procedural |
| `private` | boolean | 是否私有（仅创建者可读） |
资料来源：[src/audrey.ts:350-500]()
### 检索流程
Audrey 支持三种检索模式：
| 模式 | 说明 | 性能 |
|------|------|------|
| `hybrid`（默认） | 向量 + FTS 混合检索 | 约 14.3ms p50 |
| `vector` | 纯向量检索（绕过 FTS） | 更快 |
**检索选项白名单**（HTTP API 强制校验）：
- `query`、`limit`、`scope`
- `tags`、`sources`（数组）
- `after`、`before`（时间范围）
- `retrieval`（hybrid/vector）
资料来源：[src/routes.ts:50-150]()
## 数据流与隐私
### 工具调用脱敏
在记录工具调用结果前，系统自动脱敏敏感信息：
```typescript
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）。
## 部署架构
### 多租户隔离
```mermaid
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_DATA_DIR` | `./audrey-data` | 数据存储目录 |
| `AUDREY_API_KEY` | unset | 非本地访问的 Bearer 令牌 |
| `AUDREY_HOST` | `127.0.0.1` | REST 服务绑定地址 |
| `AUDREY_ENABLE_ADMIN_TOOLS` | `0` | 启用导出/导入/遗忘工具 |
| `AUDREY_CONTEXT_BUDGET_CHARS` | `4000` | 记忆胶囊默认字符预算 |
| `AUDREY_DEBUG` | `0` | 打印 MCP 调试日志 |
### 启动方式
| 方式 | 命令 | 用途 |
|------|------|------|
| MCP stdio | `npx audrey` | 直接集成 AI 代理 |
| REST 服务 | `npx audrey serve` | 供 Python SDK 或外部调用 |
| CLI 工具 | `npx audrey guard ...` | 终端手动检查 |
## 规则编译与推广
当需要将记忆固化为持久规则时，Audrey 提供规则编译功能：
```mermaid
graph LR
A[PromotionCandidate] --> B[规则编译]
B --> C[Markdown 文件]
C --> D[.claude/rules/]
D --> E[Claude Code 提示]
```
规则文件格式：
```markdown
---
title: "警告：高风险操作"
source_memory_ids: ["01AR...","01AS..."]
confidence: 0.85
evidence_count: 5
promoted_at: "2024-01-15T10:30:00Z"
---
内容正文...
```
资料来源：[src/rules-compiler.ts:1-100]()
## 影响评估
Audrey 提供 `impact` 命令分析记忆库的健康状态：
| 指标 | 说明 |
|------|------|
| `validatedTotal` | 经过验证的记忆总数 |
| `validatedInWindow` | 时间窗口内的验证记忆 |
| `outcomeBreakdownInWindow` | 近期操作结果分布（helpful/wrong/used） |
| `topUsed` | 高频使用记忆 |
| `weakest` | 信任度最低的记忆 |
资料来源：[src/impact.ts:100-200]()
## 扩展阅读
- [快速开始指南](../guides/getting-started.md)
- [Guard 循环详解](../guides/guard-loop.md)
- [Python SDK 文档](../python/README.md)
- [CLI 命令参考](../cli/commands.md)
---
## 记忆模型
### 相关页面
相关主题：[系统架构](#page-system-architecture), [Audrey Guard 安全循环](#page-audrey-guard), [数据存储](#page-data-storage)
相关源码文件
以下源码文件用于生成本页说明：
- [README.md](https://github.com/Evilander/Audrey/blob/main/README.md)
- [src/impact.ts](https://github.com/Evilander/Audrey/blob/main/src/impact.ts)
- [src/routes.ts](https://github.com/Evilander/Audrey/blob/main/src/routes.ts)
- [src/capsule.ts](https://github.com/Evilander/Audrey/blob/main/src/capsule.ts)
- [src/promote.ts](https://github.com/Evilander/Audrey/blob/main/src/promote.ts)
- [src/redact.ts](https://github.com/Evilander/Audrey/blob/main/src/redact.ts)
# 记忆模型
## 概述
Audrey 的记忆模型是一个专为 AI 代理设计的本地优先记忆防火墙，旨在解决代理"遗忘昨日错误"的核心问题。该模型通过多层次、可验证的记忆系统，使代理能够在执行操作前检查相关记忆，从而避免重复犯错、保持项目特定规则的连续性。资料来源：[README.md](https://github.com/Evilander/Audrey/blob/main/README.md)
## 核心架构
Audrey 记忆模型采用三层记忆架构，结合情感权重和干扰衰减机制，形成一个动态、可自适应的记忆系统。
```mermaid
graph TD
A[用户交互/工具执行] --> B[事件编码]
B --> C{记忆类型分类}
C --> D[情节记忆
Episodic]
C --> E[语义记忆
Semantic]
C --> F[程序记忆
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](https://github.com/Evilander/Audrey/blob/main/README.md)
| 属性 | 说明 |
|------|------|
| 内容 | 具体的观察、事件、偏好 |
| 来源 | direct-observation、told-by-user |
| 状态 | 活跃/已验证/已衰减 |
| 置信度 | 基于证据数量和支持度计算 |
### 语义记忆 (Semantic Memory)
语义记忆是从重复证据中提炼出的巩固原则。它代表了系统经过验证的核心信念，要求更高的置信度门槛才能晋升为语义记忆。资料来源：[README.md](https://github.com/Evilander/Audrey/blob/main/README.md)
语义记忆的晋升条件：
```typescript
// 资料来源：src/promote.ts
if (evidence < Math.max(minEvidence, 3)) continue;
if ((row.contradicting_count ?? 0) > 0) continue;
```
晋升要求：
- 至少 3 条证据支持
- 无矛盾证据记录
- 状态为活跃 (active)
### 程序记忆 (Procedural Memory)
程序记忆记录"如何行动、如何避免、如何重试、如何验证"的具体步骤。它直接关联工具使用和操作流程。资料来源：[README.md](https://github.com/Evilander/Audrey/blob/main/README.md)
程序记忆的晋升条件相对宽松，关注实用性：
```typescript
// 资料来源：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` 模块实现强化公式。
```mermaid
graph LR
A[新证据] --> B{证据类型}
B -->|支持性| C[supporting_count++]
B -->|矛盾性| D[contradicting_count++]
C --> E[置信度计算]
D --> E
E --> F{salience 更新}
```
### 强化反馈循环
Audrey 实现了闭环反馈机制，通过 `memory_validate` 工具收集用户反馈并调整记忆权重。
| 反馈结果 | 语义记忆影响 | 程序记忆影响 |
|----------|--------------|--------------|
| helpful | salience↑, retrieval_count↑ | salience↑ |
| wrong | salience↓, challenge_count↑ | salience↓ |
| used | 较小 salience 增量 | salience 增量 |
资料来源：[CHANGELOG.md](https://github.com/Evilander/Audrey/blob/main/CHANGELOG.md)
## 情感与显著性系统
### 情感影响 (Affect)
情感影响基于记忆的情感权重和唤醒度 (arousal)，影响检索结果的排序和优先级。
```typescript
// 资料来源：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](https://github.com/Evilander/Audrey/blob/main/src/impact.ts)
## 干扰与衰减机制
### 干扰检测 (Interference)
当存在相互矛盾的证据时，系统不会静默覆盖，而是跟踪这些矛盾状态。资料来源：[README.md](https://github.com/Evilander/Audrey/blob/main/README.md)
```mermaid
graph TD
A[新记忆] --> B{与现有记忆冲突?}
B -->|是| C[标记为 disputed]
B -->|否| D[正常存储]
C --> E[跟踪矛盾证据]
E --> F[保留双方记录]
D --> G[更新支持度]
```
### 衰减处理 (Decay)
陈旧、冲突或低置信度的记忆会随时间降低权威性，确保最新、最准确的信息占据主导地位。资料来源：[README.md](https://github.com/Evilander/Audrey/blob/main/README.md)
衰减考虑因素：
- 时间间隔（半衰期）
- 检索频率
- 矛盾证据数量
- 最后强化时间
## 记忆胶囊 (Memory Capsule)
记忆胶囊是一种 turn-sized 的记忆数据包，用于在特定上下文中快速获取相关记忆。
### 胶囊分段
```typescript
// 资料来源：src/capsule.ts
const sections = new Set();
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');
}
```
### 胶囊分区表
| 分区名称 | 触发条件 |
|----------|----------|
| must_follow | 可信来源 + 必须遵循标签 |
| risks | 包含风险标签 |
| procedures | 程序记忆类型或程序标签 |
| user_preferences | 用户偏好标签或 told-by-user 来源 |
| recent_changes | 最近时间窗口内的更新 |
| uncertain_or_disputed | 争议状态或低置信度 (<0.55) |
| project_facts | 默认语义/情节记忆 |
## 记忆验证流程
### Preflight 检查
在执行工具操作前，系统执行预检查以确保行动的安全性。
```mermaid
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 端点收集：
| 端点 | 用途 | 参数 |
|------|------|------|
| POST /v1/validate | 标准验证 | id, outcome |
| POST /v1/mark-used | 遗留别名 | memory_id, outcome |
资料来源：[CHANGELOG.md](https://github.com/Evilander/Audrey/blob/main/CHANGELOG.md)
## 规则晋升系统
高质量的程序记忆和语义记忆可以被晋升为可执行的规则文件。
### 晋升条件对比
| 条件 | 程序记忆 | 语义记忆 |
|------|----------|----------|
| 证据数量 | ≥1 | ≥3 |
| 失败预防数 | >0 或使用次数 >0 | - |
| 矛盾限制 | 无限制 | 必须为 0 |
| 晋升目标 | .claude/rules/*.md | .claude/rules/*.md |
资料来源：[src/promote.ts](https://github.com/Evilander/Audrey/blob/main/src/promote.ts)
### 规则编译
规则文件包含 YAML front matter，记录来源记忆 ID、置信度、证据数量等信息。
```typescript
// 资料来源：src/rules-compiler.ts
export interface RuleDoc {
title: string;
slug: string;
relativePath: string;
body: string;
frontmatter: Record;
}
```
## 记忆数据模型
### 数据库存储
Audrey 使用 SQLite 作为本地存储，结合 sqlite-vec 支持向量检索。
```sql
-- 情节记忆表结构（示意）
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
);
```
### 检索模式
| 模式 | 描述 | 性能特点 |
|------|------|----------|
| hybrid | 混合检索（向量 + 全文） | 默认模式，平衡精度与召回 |
| vector | 仅向量检索 | FTS 旁路快速路径 |
资料来源：[CHANGELOG.md](https://github.com/Evilander/Audrey/blob/main/CHANGELOG.md)
## 私有记忆与访问控制
### 隐私隔离
HTTP `/v1/recall` 和 `/v1/capsule` 不再将调用者选项体传播到 `audrey.recall()`，防止通过 HTTP 请求绕过私有记忆 ACL。资料来源：[CHANGELOG.md](https://github.com/Evilander/Audrey/blob/main/CHANGELOG.md)
### 选项白名单
```typescript
// 资料来源：src/routes.ts
const ALLOWED_KEYS: Set = new Set([
'limit', 'offset', 'agent', 'tags', 'sources',
'after', 'before', 'context', 'mood', 'retrieval', 'scope'
]);
```
## 安全机制
### 敏感信息脱敏
```typescript
// 资料来源：src/redact.ts
const SENSITIVE_KEY_PATTERN = /(^|_|-)(password|passwd|pwd|secret|api[_-]?key|auth[_-]?token|bearer[_-]?token|...)$/i;
```
脱敏状态：
- `clean` - 无敏感信息
- `redacted` - 已脱敏
## 影响统计与监控
### 记忆统计接口
```typescript
// 资料来源：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](https://github.com/Evilander/Audrey/blob/main/README.md)
建议按计划运行以保持巩固和衰减的最新状态。
## 环境变量配置
| 变量 | 默认值 | 用途 |
|------|--------|------|
| AUDREY_DATA_DIR | - | 租户/环境数据目录 |
| AUDREY_EMBEDDING_PROVIDER | - | 嵌入提供商 |
| AUDREY_LLM_PROVIDER | - | LLM 提供商 |
| AUDREY_API_KEY | - | API 密钥认证 |
资料来源：[README.md](https://github.com/Evilander/Audrey/blob/main/README.md)
---
## Audrey Guard 安全循环
### 相关页面
相关主题：[记忆模型](#page-memory-model), [MCP集成](#page-mcp-integration), [REST API](#page-rest-api), [CLI工具](#page-cli-tools)
相关源码文件
以下源码文件用于生成本页说明：
- [src/preflight.ts](https://github.com/Evilander/Audrey/blob/main/src/preflight.ts)
- [src/reflexes.ts](https://github.com/Evilander/Audrey/blob/main/src/reflexes.ts)
- [src/redact.ts](https://github.com/Evilander/Audrey/blob/main/src/redact.ts)
- [src/feedback.ts](https://github.com/Evilander/Audrey/blob/main/src/feedback.ts)
- [src/action-key.ts](https://github.com/Evilander/Audrey/blob/main/src/action-key.ts)
- [mcp-server/index.ts](https://github.com/Evilander/Audrey/blob/main/mcp-server/index.ts)
- [src/capsule.ts](https://github.com/Evilander/Audrey/blob/main/src/capsule.ts)
- [src/impact.ts](https://github.com/Evilander/Audrey/blob/main/src/impact.ts)
# Audrey Guard 安全循环
Audrey Guard 是 Audrey 项目中的核心安全机制，为 AI Agent 提供内存优先的动作检查能力。在 Agent 执行任何工具调用之前，Guard 会查询持久化记忆，评估潜在风险，并根据历史经验返回允许、警告或阻止的决策。
## 核心概念
### 安全循环的工作原理
Audrey Guard 采用**记录-记忆-检查-响应-验证**的闭环设计：
1. **记忆编码** (`memory_encode`): 将 Agent 的操作经验、错误教训、项目规则编码存储
2. **预检执行** (`memory_preflight`): 动作执行前查询相关记忆，评估风险等级
3. **决策返回**: 输出 `allow`（允许）、`warn`（警告）或 `block`（阻止）决策
4. **反射生成** (`memory_reflexes`): 将记忆证据转换为可执行的触发-响应指导
5. **反馈验证** (`memory_validate`): 动作完成后收集结果，更新记忆权重
```mermaid
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]()
### 决策类型
| 决策类型 | 含义 | 触发条件 |
|---------|------|---------|
| `allow` | 允许执行 | 无历史风险记忆、规则验证通过 |
| `warn` | 带警告执行 | 存在低置信风险记忆、需要人工确认 |
| `block` | 阻止执行 | 存在高风险记忆、规则明确禁止、重复失败 |
资料来源：[mcp-server/index.ts:58-65]()
## 预检系统 (Preflight)
预检是 Guard 的核心检查模块，在动作执行前全面评估各种风险因素。
### 检查维度
`memory_preflight` 从多个维度进行综合评估：
```typescript
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 包含结构化的记忆分段：
```mermaid
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]()
### 风险标签系统
预检模块使用标签系统标记不同类型的风险记忆：
| 标签类型 | 标签值 | 记忆分段归属 |
|---------|--------|------------|
| 强制规则 | `MUST_FOLLOW_TAGS` | `must_follow` |
| 风险警告 | `RISK_TAGS` | `risks` |
| 流程规范 | `PROCEDURE_TAGS` | `procedures` |
| 用户偏好 | `PREFERENCE_TAGS` | `user_preferences` |
| 低置信 | `confidence < 0.55` | `uncertain_or_disputed` |
资料来源：[src/capsule.ts:62-85]()
### 近期失败检测
预检自动查询最近 7 天内的工具失败记录，识别反复出现的错误模式：
```typescript
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 可直接执行的指导规则。
### 反射生成流程
```mermaid
graph TD
A[记忆事件] --> B[提取证据内容]
B --> C[识别触发条件]
C --> D[生成响应规则]
D --> E[格式化为 Markdown]
E --> F[添加 YAML 前置元数据]
F --> G[持久化到规则文件]
```
### 规则文件结构
Audrey 将反射规则存储为 Markdown 文件，包含 YAML 前置元数据：
```yaml
---
memory_ids: [mem_xxx123, mem_xxx456]
confidence: 0.85
evidence_count: 3
promoted_at: "2024-01-15T10:30:00Z"
---
```
资料来源：[src/rules-compiler.ts:1-30]()
### 标题与 Slug 生成
规则编译器使用停用词过滤生成可读的 slug：
```typescript
const STOP_WORDS = new Set(['the', 'a', 'an', 'is', 'of', 'and', 'or', 'to', 'for', 'with', 'on', 'at', 'by', 'in', 'as']);
function slugifyTitle(title: string): string {
const words = lowered.split(/[^a-z0-9]+/).filter(w => w && !STOP_WORDS.has(w));
return words.slice(0, 6).join('-');
}
```
资料来源：[src/rules-compiler.ts:23-27]()
## 数据脱敏 (Redaction)
Guard 在记录工具输入输出时自动执行敏感数据脱敏，防止凭证和密钥被永久存储。
### 敏感字段检测
```typescript
const 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;
```
资料来源：[src/redact.ts:35-36]()
### 脱敏操作
| 操作类型 | 脱敏内容 | 输出格式 |
|---------|---------|---------|
| JSON 键值对 | 匹配模式的键名 | `[REDACTED:api_key]` |
| 明文密钥 | 常见密钥格式 | `[REDACTED:token]` |
| Bearer Token | Authorization 头 | `[REDACTED:bearer]` |
资料来源：[src/redact.ts:38-60]()
### 脱敏状态
脱敏结果包含状态标识：
```typescript
interface RedactionResult {
text: string; // 脱敏后的文本
redactions: RedactionHit[]; // 脱敏操作记录
state: 'clean' | 'redacted'; // 整体状态
}
```
## 反馈验证 (Feedback)
`memory_validate` 关闭安全循环的最后一步，通过收集执行结果反馈来更新记忆权重。
### 结果类型
| 结果类型 | 含义 | 权重影响 |
|---------|------|---------|
| `helpful` | 记忆有帮助 | salience + |
| `used` | 记忆被使用 | usage_count + |
| `wrong` | 记忆有误 | salience - |
资料来源：[src/impact.ts:25-35]()
### 反馈数据结构
```typescript
interface EventOutcome {
helpful?: number;
used?: number;
wrong?: number;
// 或通过证据反馈映射
evidence_feedback?: Record;
}
```
### Impact 追踪
Audrey 维护全局的 Impact 指标，用于评估记忆系统的实际效果：
```typescript
interface ImpactReport {
windowDays: number;
totals: {
episodic: number; // 情景记忆总数
semantic: number; // 语义记忆总数
procedural: number; // 流程记忆总数
};
validatedTotal: number; // 已验证记忆数
validatedInWindow: number; // 窗口内验证数
topUsed: MemoryEntry[]; // 高使用频率记忆
weakest: MemoryEntry[]; // 低权重记忆
recentActivity: MemoryEntry[]; // 近期活动
}
```
资料来源：[src/impact.ts:40-60]()
## CLI 命令行接口
### guard 命令
```bash
npx audrey guard --tool Bash "npm run deploy"
```
### 命令行参数
| 参数 | 说明 | 示例 |
|-----|------|-----|
| `--tool` | 工具名称 | `--tool Bash` |
| `--hook` | Hook 模式 | `--hook` |
| `--fail-on-warn` | 警告时失败 | `--fail-on-warn` |
| `--explain` | 显示决策证据 | `--explain` |
| `--strict` | 严格模式 | `--strict` |
| `--include-capsule` | 包含完整 Capsule | `--include-capsule` |
| `--json` | JSON 输出格式 | `--json` |
资料来源：[mcp-server/index.ts:40-55]()
## 安全考虑
### API 密钥保护
HTTP API 的密钥比较使用时序安全比较，防止时序攻击：
```typescript
crypto.timingSafeEqual(
Buffer.from(providedKey),
Buffer.from(expectedKey)
);
```
资料来源：[mcp-server/index.ts:180-185]()
### 非本地绑定限制
Audrey 默认绑定到 `127.0.0.1`，拒绝在非本地地址启动而不设置 API Key：
```typescript
const isLoopback = serveHost === '127.0.0.1' || serveHost === '::1';
if (!isLoopback && !serveAuth && !serveAllowNoAuth) {
// 拒绝启动并给出错误提示
}
```
资料来源：[mcp-server/index.ts:195-205]()
### 规则文件写入限制
`audrey promote` 命令拒绝写入非工作目录的规则文件，防止提示注入攻击：
```bash
AUDREY_PROMOTE_ROOTS=/path/to/trusted:d:/trusted audrey promote --yes
```
资料来源：[CHANGELOG.md:28-30]()
## 集成方式
### Claude Code 集成
```bash
npx audrey install --host claude-code
```
安装后会在 Claude Code 设置中添加 PreToolUse 钩子，自动执行 `audrey guard --hook --fail-on-warn`。
### MCP 服务器模式
Audrey 作为 MCP 服务器运行，支持 stdio 通信：
```bash
npx audrey serve
```
服务器暴露 `/v1/preflight`、`/v1/validate` 等 REST 端点。
### Python SDK 集成
```python
from audrey_memory import Audrey
brain = Audrey(base_url="http://127.0.0.1:7437", agent="my-agent")
# 预检动作
result = brain.preflight(
tool="Bash",
action="npm run deploy"
)
if result.decision == "block":
print("动作被阻止:", result.evidence)
```
## 总结
Audrey Guard 通过五层闭环机制为 AI Agent 提供可靠的安全防护：
1. **预检层**: 动作执行前的多维度风险评估
2. **反射层**: 历史经验转化为可执行规则
3. **脱敏层**: 敏感数据的自动保护
4. **验证层**: 执行结果的反馈收集
5. **权重层**: 记忆权重的动态调整
这种设计使 Agent 能够从历史错误中学习，在重复操作前获得警告，最终实现真正的"记忆驱动的智能代理"。
---
*本页面基于 Audrey 源码生成，最后更新对应仓库 commit: master 分支。*
---
## 数据存储
### 相关页面
相关主题：[系统架构](#page-system-architecture), [记忆模型](#page-memory-model)
相关源码文件
以下源码文件用于生成本页说明：
- [README.md](https://github.com/Evilander/Audrey/blob/main/README.md)
- [src/impact.ts](https://github.com/Evilander/Audrey/blob/main/src/impact.ts)
- [src/routes.ts](https://github.com/Evilander/Audrey/blob/main/src/routes.ts)
- [src/capsule.ts](https://github.com/Evilander/Audrey/blob/main/src/capsule.ts)
- [CHANGELOG.md](https://github.com/Evilander/Audrey/blob/main/CHANGELOG.md)
- [python/README.md](https://github.com/Evilander/Audrey/blob/main/python/README.md)
# 数据存储
Audrey 的数据存储层是整个本地优先记忆防火墙的核心基础设施。它采用 SQLite 作为主数据库，结合 sqlite-vec 扩展实现向量检索功能，为 AI 代理提供持久化、可查询的记忆存储能力。
## 存储架构概述
Audrey 采用单文件本地数据库架构，所有记忆数据存储在 SQLite 数据库中，无需外部托管数据库服务。这种设计确保了：
- **数据主权**：所有数据保留在本地文件系统
- **零依赖**：不依赖 PostgreSQL、Redis 等外部服务
- **便携性**：通过备份整个数据目录即可迁移整个记忆状态
- **事务完整性**：SQLite 的 ACID 特性保证数据一致性
资料来源：[README.md:1-30]()
```mermaid
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` | `$PWD/.audrey` | 数据库文件所在目录路径 |
```bash
# 示例：指定自定义数据目录
AUDREY_DATA_DIR=/home/user/.audrey-staging npx audrey serve
```
资料来源：[README.md:环境变量部分]()
## 数据库表结构
Audrey 的记忆模型通过三个核心表实现，分别对应不同的记忆类型：
### 情景记忆表 (episodic_memory)
存储具体的观察结果、工具执行结果、用户偏好和会话事实。
| 字段 | 类型 | 说明 |
|------|------|------|
| id | TEXT | 主键，ULID 格式 |
| content | TEXT | 记忆内容文本 |
| embedding | BLOB | 向量嵌入数据 |
| confidence | REAL | 置信度分数 (0-1) |
| source | TEXT | 来源类型 (direct-observation, tool-result, user-feedback) |
| tags | TEXT | 逗号分隔的标签列表 |
| agent | TEXT | 关联的代理标识 |
| state | TEXT | 状态 (active, decayed, challenged, disputed) |
| created_at | TEXT | ISO 时间戳 |
| last_used_at | TEXT | 上次使用时间 |
| usage_count | INTEGER | 使用次数统计 |
资料来源：[src/impact.ts:1-50]()
### 语义记忆表 (semantic_memory)
存储从重复证据中提取的巩固原则和规则。
| 字段 | 类型 | 说明 |
|------|------|------|
| id | TEXT | 主键 |
| content | TEXT | 原则内容 |
| embedding | BLOB | 向量嵌入 |
| confidence | REAL | 置信度 |
| evidence_count | INTEGER | 支持证据数量 |
| challenged | INTEGER | 是否被质疑标记 |
| created_at | TEXT | 创建时间 |
### 程序记忆表 (procedural_memory)
存储执行操作的已知方式、避免事项、重试策略和验证方法。
| 字段 | 类型 | 说明 |
|------|------|------|
| id | TEXT | 主键 |
| content | TEXT | 程序步骤内容 |
| embedding | BLOB | 向量嵌入 |
| confidence | REAL | 置信度 |
| trigger_conditions | TEXT | 触发条件表达式 |
| created_at | TEXT | 创建时间 |
### 记忆事件表 (memory_events)
审计日志表，记录所有记忆相关的操作事件。
```typescript
// 事件类型包括:
// - encode: 新记忆编码
// - recall: 记忆检索
// - feedback: 反馈更新
// - consolidate: 记忆巩固
// - decay: 记忆衰减
// - promote: 记忆提升为规则
// - forget: 记忆遗忘
```
资料来源：[src/capsule.ts:1-30]()
## 向量检索配置
Audrey 使用 sqlite-vec 扩展提供向量相似度搜索能力。向量检索支持两种模式：
| 检索模式 | 说明 | 适用场景 |
|----------|------|----------|
| `hybrid` (默认) | 结合向量相似度和全文搜索的混合检索 | 平衡精度和召回率 |
| `vector` | 仅使用向量相似度搜索 | 快速精确匹配，跳过 FTS |
```typescript
// 检索选项配置
interface RecallOptions {
query: string; // 检索查询文本
limit?: number; // 返回结果数量限制
tags?: string[]; // 标签过滤
sources?: string[]; // 来源类型过滤
after?: string; // 时间范围起点 (ISO 格式)
before?: string; // 时间范围终点
scope?: 'shared' | 'agent'; // 共享记忆或代理专属记忆
retrieval?: 'hybrid' | 'vector'; // 检索模式选择
context?: Record; // 上下文参数
mood?: RecallOptions['mood']; // 情感/优先级配置
}
```
资料来源：[src/routes.ts:1-30]()
## 数据库性能优化
### PRAGMA 配置
Audrey 对 SQLite 进行了性能调优配置：
| PRAGMA 设置 | 说明 |
|-------------|------|
| `journal_mode = WAL` | 启用 WAL 模式，提高并发读写性能 |
| `synchronous = NORMAL` | 平衡安全性和写入性能 |
| `cache_size` | 增大缓存减少磁盘 IO |
| `mmap_size` | 启用内存映射加速读取 |
如需恢复默认配置：
```bash
AUDREY_PRAGMA_DEFAULTS=0 npx audrey serve
```
资料来源：[README.md:环境变量部分]()
### 嵌入预热
首次启动时，Audrey 会进行嵌入模型预热以加速后续操作：
```
冷启动首次编码: 525ms → 预热后: 28ms (约18.7倍提升)
```
| 环境变量 | 默认值 | 说明 |
|---------|--------|------|
| `AUDREY_DISABLE_WARMUP` | `0` | 设为 `1` 可跳过嵌入预热 |
资料来源：[CHANGELOG.md:0.22.0 性能部分]()
## 数据备份与恢复
### 手动备份
由于所有数据存储在单一数据库文件，备份非常简单：
```bash
# 停止服务后复制数据库目录
cp -r .audrey .audrey.backup-$(date +%Y%m%d)
```
### 快照导出与恢复
Audrey 支持生成和恢复记忆快照：
```python
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` |
| 按环境隔离 | 开发/测试/生产使用不同数据目录 |
| 按项目隔离 | 每个项目使用独立的数据目录 |
```bash
# 多实例运行示例
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 导出数据：
| 端点 | 方法 | 说明 |
|------|------|------|
| `/v1/export` | POST | 导出所有记忆数据 |
| `/v1/import` | POST | 导入记忆快照 |
| `/v1/forget` | POST | 删除指定记忆 |
```bash
# 启用管理工具
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:环境变量部分]()
## 生产环境建议
| 建议项 | 说明 |
|--------|------|
| 定期备份 | 每次重大版本升级前备份 `AUDREY_DATA_DIR` |
| 磁盘空间监控 | 监控数据库目录大小，避免磁盘满 |
| 权限控制 | 确保数据库目录仅服务进程可读写 |
| 升级前备份 | Provider 或维度变化前必须备份 |
| 冷备份时机 | 备份时停止服务或使用只读快照 |
```bash
# 生产环境备份脚本示例
#!/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` 命令执行记忆巩固：
```bash
npx audrey dream
```
巩固过程包括：
- 低置信度记忆衰减
- 高频使用记忆强化
- 矛盾记忆标记处理
- 跨记忆类型关联更新
### 记忆衰减 (Decay)
置信度低于阈值的记忆会逐渐衰减，失去在检索中的优先级：
| 衰减因素 | 说明 |
|----------|------|
| 时间衰减 | 长时间未使用的记忆置信度下降 |
| 矛盾干扰 | 被新证据反驳的记忆进入 disputed 状态 |
| 低使用率 | usage_count 过低的记忆逐渐淡化 |
```typescript
// 衰减配置 (half-life 机制)
interface ConfidenceConfig {
halfLifeDays: number; // 置信度减半的天数
decayThreshold: number; // 触发衰减的最小置信度
boostOnUse: boolean; // 使用后是否提升置信度
}
```
资料来源：[src/impact.ts:全文]()
## 存储健康检查
使用 CLI 检查存储状态：
```bash
# 基本状态检查
npx audrey status
# JSON 格式输出
npx audrey status --json
# 严格模式（不健康时退出码非零）
npx audrey status --json --fail-on-unhealthy
```
```json
{
"status": "healthy",
"database": {
"path": ".audrey/audrey.db",
"size_bytes": 1048576,
"episodic_count": 150,
"semantic_count": 23,
"procedural_count": 8
},
"vectorIndex": {
"status": "ready",
"dimension": 768
}
}
---
## MCP集成
### 相关页面
相关主题：[Audrey Guard 安全循环](#page-audrey-guard), [REST API](#page-rest-api)
相关源码文件
以下源码文件用于生成本页说明：
- [mcp-server/index.ts](https://github.com/Evilander/Audrey/blob/main/mcp-server/index.ts)
- [mcp-server/config.ts](https://github.com/Evilander/Audrey/blob/main/mcp-server/config.ts)
- [src/routes.ts](https://github.com/Evilander/Audrey/blob/main/src/routes.ts)
- [src/capsule.ts](https://github.com/Evilander/Audrey/blob/main/src/capsule.ts)
- [src/redact.ts](https://github.com/Evilander/Audrey/blob/main/src/redact.ts)
- [README.md](https://github.com/Evilander/Audrey/blob/main/README.md)
# MCP集成
## 概述
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]()
## 架构设计
### 系统组件关系
```mermaid
graph TD
A["AI代理
(Claude Code/Cursor/Codex等)"] -->|MCP协议| B["Audrey MCP Server
mcp-server/index.ts"]
B -->|stdio/STDIO通信| C["Audrey Core
内存管理层"]
C -->|SQLite存储| D["记忆存储
episodic/semantic/procedural"]
E["REST API
/v1/*"] -->|HTTP调用| C
F["CLI工具
audrey guard"] -->|命令行接口| C
B -->|工具调用| G["guard
记忆检查工具"]
B -->|工具调用| H["memory_encode
编码记忆"]
B -->|工具调用| I["memory_recall
检索记忆"]
B -->|工具调用| J["memory_feedback
反馈结果"]
```
### MCP通信模式
Audrey MCP Server支持两种通信模式，根据不同宿主环境选择：
| 宿主类型 | 通信模式 | 配置格式 | 说明 |
|---------|---------|---------|------|
| Codex | stdio | TOML | 通过`command`和`args`直接启动进程 |
| Claude Code | stdio | JSON | MCP原生JSON-RPC |
| Claude Desktop | stdio | JSON | MCP原生JSON-RPC |
| Cursor | stdio | JSON | MCP原生JSON-RPC |
| Windsurf | stdio | JSON | MCP原生JSON-RPC |
| VS Code | stdio | JSON | MCP原生JSON-RPC |
| JetBrains | stdio | JSON | MCP原生JSON-RPC |
| Ollama | stdio | JSON | 本地模型支持 |
| Generic | stdio | JSON | 通用MCP宿主 |
资料来源：[mcp-server/config.ts:1-50]()
## MCP服务器启动
### CLI参数解析
MCP服务器通过命令行参数配置启动行为，支持以下选项：
```mermaid
graph LR
A["CLI Arguments"] --> B{"参数解析
parseArgs()"}
B --> C["--host="]
B --> D["--dry-run"]
B --> D2["--include-secrets"]
C --> E["host变量
宿主标识"]
D --> F["dryRun标志"]
D2 --> G["includeSecrets标志"]
E --> H["返回对象
{host, dryRun, includeSecrets}"]
```
参数处理逻辑（伪代码表示）：
| 参数模式 | 示例 | 行为 |
|---------|------|------|
| `--host=` | `--host=claude-code` | 设置宿主标识 |
| `--dry-run` | `audrey mcp --dry-run` | 预览配置不实际启动 |
| `--include-secrets` | `audrey mcp --include-secrets` | 在环境变量中包含密钥 |
| 无前缀值 | `audrey mcp claude-code` | 设置宿主标识 |
资料来源：[mcp-server/index.ts:1-80]()
### 子命令分发
```mermaid
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 --> [*]
```
支持的子命令列表：
| 子命令 | 功能描述 |
|-------|---------|
| `audrey install --host ` | 在指定宿主中注册Audrey |
| `audrey uninstall` | 取消注册Audrey |
| `audrey mcp-config` | 打印MCP配置文件 |
| `audrey hook-config` | 打印/应用Hook配置 |
| `audrey demo` | 运行演示命令 |
| `audrey reembed` | 重新生成嵌入向量 |
| `audrey dream` | 触发记忆整合 |
| `audrey greeting` | 打印问候语 |
资料来源：[mcp-server/index.ts:100-150]()
## MCP工具接口
### 工具注册与调用
Audrey通过MCP暴露以下核心工具，AI代理可在执行操作前调用：
| 工具名称 | 功能 | 返回类型 |
|---------|------|---------|
| `guard` | 记忆前置检查 | `GuardResult` |
| `memory_encode` | 编码新记忆 | `EncodeResult` |
| `memory_recall` | 检索相关记忆 | `RecallResult` |
| `memory_feedback` | 记录反馈结果 | `FeedbackResult` |
### Guard工具详解
Guard是Audrey的核心工具，用于在代理执行操作前进行记忆检查：
```mermaid
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: 分析决策
allow/warn/block
Core->>DB: 记录使用统计
Core-->>MCP: GuardResult
MCP-->>Agent: 决策+证据
```
Guard参数结构（`src/routes.ts`中定义）：
```typescript
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返回值结构
| 字段 | 类型 | 说明 |
|-----|------|------|
| `decision` | `allow` \| `warn` \| `block` | 决策结果 |
| `receipt_id` | `string` | 收据ID，用于后续反馈 |
| `capsule` | `MemoryCapsule` | 检索到的相关记忆 |
| `preflight` | `PreflightResult` | 前置检查结果 |
| `confidence` | `number` | 置信度 (0-1) |
| `evidence` | `Evidence[]` | 支持决策的证据 |
### Memory Capsule结构
记忆胶囊（Memory Capsule）将检索到的记忆分类组织，便于代理理解和使用：
```mermaid
graph TD
A["MemoryCapsule"] --> B["sections: 各分区记忆"]
B --> C["must_follow
必须遵守的规则"]
B --> D["procedures
操作流程"]
B --> E["user_preferences
用户偏好"]
B --> F["risks
风险警告"]
B --> G["uncertain_or_disputed
不确定/争议"]
B --> H["recent_changes
近期变更"]
B --> I["project_facts
项目事实"]
```
分区分配规则（`src/capsule.ts`）：
| 记忆类型/标签 | 分配分区 | 条件 |
|-------------|---------|------|
| 高置信度直接观察/用户告知 | `must_follow` | 包含MUST_FOLLOW_TAGS |
| 低置信度间接来源 | `uncertain_or_disputed` | 包含MUST_FOLLOW_TAGS但来源不可信 |
| 包含RISK_TAGS | `risks` | 标签匹配 |
| procedural类型或PROCEDURE_TAGS | `procedures` | 类型/标签匹配 |
| PREFERENCE_TAGS或told-by-user | `user_preferences` | 标签/来源匹配 |
| 状态为disputed/context_dependent | `uncertain_or_disputed` | 状态检查 |
| 置信度 < 0.55 | `uncertain_or_disputed` | 阈值检查 |
| 7天内创建 | `recent_changes` | 时间窗口 |
资料来源：[src/capsule.ts:1-100]()
## 配置生成
### 宿主配置格式化
MCP Server根据不同宿主类型生成对应格式的配置文件：
```mermaid
graph LR
A["宿主类型"] --> B{"formatMcpHostConfig()"}
B -->|codex| C["TOML格式
tomlString()"]
B -->|其他| D["JSON格式
JSON.stringify()"]
C --> E["[mcp_servers.audrey]
command = ...
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配置格式
```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]()
### 环境变量构建
```typescript
function buildAudreyMcpEnv(
env: Record,
agent: string,
options: { includeSecrets?: boolean }
): Record
```
| 环境变量 | 默认值 | 说明 |
|---------|-------|------|
| `AUDREY_DATA_DIR` | 自动 | 数据存储目录 |
| `AUDREY_LLM_PROVIDER` | 推断 | LLM提供者 |
| `AUDREY_EMBEDDING_PROVIDER` | 推断 | 嵌入提供者 |
| `AUDREY_LLM_MODEL` | 推断 | LLM模型 |
| `AUDREY_API_KEY` | 无 | API密钥（需设置includeSecrets） |
资料来源：[mcp-server/config.ts:50-100]()
## 安装与配置
### 安装流程
```mermaid
graph TD
A["audrey install --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["仅预览配置
不实际安装"]
```
### Claude Code安装步骤
```bash
# 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集成到代理的请求-响应循环中：
```typescript
interface HookConfigOptions {
host: string;
apply: boolean; // 是否应用配置
dryRun: boolean; // 预览模式
scope: 'project' | 'user'; // 配置作用域
projectDir: string; // 项目目录
settingsPath?: string; // 配置文件路径
}
```
| 作用域 | 配置文件路径 |
|-------|-------------|
| `user` | `~/.claude/settings.json` |
| `project` | `/.claude/settings.local.json` |
资料来源：[mcp-server/index.ts:150-200]()
## 安全与隐私
### 数据脱敏
Audrey MCP Server内置敏感信息检测和脱敏机制（`src/redact.ts`）：
| 敏感类型 | 模式 | 替换值 |
|---------|------|-------|
| API密钥 | `/(api[_-]?key|apikey)[=:]\s*['"]?([^'"\s,]+)/gi` | `[REDACTED:api_key]` |
| AWS密钥 | `/(aws[_-]?secret[_-]?access[_-]?key)[=:]\s*['"]?([^'"\s,]+)/gi` | `[REDACTED:aws_key]` |
| Bearer令牌 | `/(bearer[_-]?token)[=:]\s*['"]?([^'"\s,]+)/gi` | `[REDACTED:bearer_token]` |
| 密码赋值 | `/(password|passwd|pwd)[=:]\s*['"]?([^'"\s,]+)/gi` | `[REDACTED:password]` |
| JWT | `/(jwt)[=:]\s*['"]?([^'"\s,]+)/gi` | `[REDACTED:jwt]` |
| 会话Cookie | `/(session|sid)=[A-Za-z0-9%._-]{8,}/gi` | `[REDACTED:session]` |
| S3签名 | `/([?&](?:X-Amz-Signature|sig)=)[^&\s"']+/gi` | `[REDACTED:signed_url_signature]` |
| US SSN | `/\b(?!000|666|9\d{2})\d{3}-(?!00)\d{2}-(?!0000)\d{4}\b/g` | `[REDACTED:ssn]` |
### HTTP API安全
| 安全措施 | 说明 |
|---------|------|
| 绑定地址限制 | 默认为`127.0.0.1`，拒绝非localhost无API Key |
| API Key比较 | 使用`crypto.timingSafeEqual`防止时序攻击 |
| 选项白名单 | `sanitizeRecallOptions()`过滤不允许的HTTP Body参数 |
| 管理员工具 | `AUDREY_ENABLE_ADMIN_TOOLS`默认禁用导出/导入/删除功能 |
资料来源：[src/redact.ts:1-80]()
资料来源：[README.md:环境变量部分]()
## 诊断与调试
### Doctor诊断命令
```bash
npx audrey doctor [--json] [--override]
```
| 检查项 | 说明 |
|-------|------|
| `node-runtime` | Node.js版本 ≥ 20 |
| `mcp-entrypoint` | MCP入口文件存在 |
| `data-dir-writable` | 数据目录可写 |
| `memory-store` | SQLite存储健康 |
| `embedding-provider` | 嵌入提供者配置 |
| `llm-provider` | LLM提供者配置 |
| `host-config` | 宿主配置文件存在 |
### 环境变量诊断
| 环境变量 | 默认值 | 用途 |
|---------|-------|------|
| `AUDREY_DEBUG` | `0` | 打印MCP启动和预热日志 |
| `AUDREY_PROFILE` | `0` | 启用诊断计时输出 |
| `AUDREY_DISABLE_WARMUP` | `0` | 跳过嵌入向量预热 |
| `AUDREY_ONNX_VERBOSE` | `0` | 显示ONNX运行时端点分配警告 |
资料来源：[mcp-server/index.ts:doctor相关函数]()
## 性能特性
### 冷启动优化
| 指标 | 优化前 | 优化后 | 提升倍数 |
|-----|-------|-------|---------|
| 编码响应时间 (p50) | 24.7ms | 15.2ms | ~1.6x |
| 冷启动首次编码 | 525ms | 28ms | ~18.7x |
| 混合检索 (p50) | 30.2ms | 14.3ms | ~2.1x |
### 嵌入向量优化
- 验证、干扰检测、情感共鸣共享主内容向量
- 消除4次冗余嵌入调用中的3次
- 可选`wait_for_consolidation`参数实现写后读语义
资料来源：[CHANGELOG.md:0.22.0版本]()
## 版本历史
| 版本 | 发布日期 | 关键变更 |
|-----|---------|---------|
| 0.22.0 | 2026-04-28 | 性能优化，编码速度提升40%+，冷启动18.7x提升 |
| 0.21.0 | 2026-04 | 添加`audrey doctor`诊断命令，host安装预览 |
| 0.20.0 | 2026-03 | 记忆Preflight和Reflexes，MCP文档完善 |
资料来源：[CHANGELOG.md:版本记录]()
---
## REST API
### 相关页面
相关主题：[MCP集成](#page-mcp-integration)
相关源码文件
以下源码文件用于生成本页说明：
- [src/routes.ts](https://github.com/Evilander/Audrey/blob/main/src/routes.ts)
- [src/server.ts](https://github.com/Evilander/Audrey/blob/main/src/server.ts)
- [README.md](https://github.com/Evilander/Audrey/blob/main/README.md)
- [python/README.md](https://github.com/Evilander/Audrey/blob/main/python/README.md)
- [src/audrey.ts](https://github.com/Evilander/Audrey/blob/main/src/audrey.ts)
# REST API
Audrey 提供了一个基于 Hono 框架构建的 REST API 服务端点，允许外部客户端（包括 Python SDK、命令行工具和其他 AI 代理）通过 HTTP 协议访问记忆功能。该 API 是 Audrey 作为本地优先记忆防火墙的核心通信接口。
## 概述
REST API 作为 Audrey 的远程通信层，默认监听 `http://127.0.0.1:7437`，提供健康检查、记忆编码、记忆召回、记忆胶囊获取以及管理工具等端点。资料来源：[README.md](https://github.com/Evilander/Audrey/blob/main/README.md)
```mermaid
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](https://github.com/Evilander/Audrey/blob/main/CHANGELOG.md)
### 健康检查
| 端点 | 方法 | 说明 |
|------|------|------|
| `/health` | GET | 检查服务健康状态 |
### 记忆操作
| 端点 | 方法 | 说明 |
|------|------|------|
| `/v1/preflight` | POST | 执行行动前检查，返回 allow、warn 或 block 决策 |
| `/v1/recall` | POST | 召回相关记忆上下文 |
| `/v1/capsule` | POST | 获取回合大小的记忆数据包 |
| `/v1/status` | GET | 获取当前记忆状态 |
### 管理工具（需启用）
当 `AUDREY_ENABLE_ADMIN_TOOLS=1` 时，以下端点可用：
| 端点 | 方法 | 说明 |
|------|------|------|
| `/v1/export` | POST | 导出记忆快照 |
| `/v1/import` | POST | 导入记忆快照 |
| `/v1/forget` | POST | 遗忘特定记忆 |
## 请求体结构
所有 POST 端点使用统一的 `RouteBody` 类型定义，支持丰富的参数选项。资料来源：[src/routes.ts:1-50](https://github.com/Evilander/Audrey/blob/main/src/routes.ts)
### 基础参数
| 参数名 | 类型 | 说明 |
|--------|------|------|
| `action` | string | 执行的操作或命令 |
| `query` | string | 查询字符串（action 的别名） |
| `tool` | string | 工具名称（如 Bash、Write） |
| `session_id` / `sessionId` | string | 会话标识符 |
| `cwd` | string | 当前工作目录 |
### 记忆召回参数
| 参数名 | 类型 | 默认值 | 说明 |
|--------|------|--------|------|
| `limit` | number | - | 召回记忆数量限制 |
| `budget_chars` / `budgetChars` | number | 4000 | 记忆胶囊字符预算 |
| `include_capsule` / `includeCapsule` | boolean | false | 是否包含记忆胶囊 |
| `include_status` / `includeStatus` | boolean | false | 是否包含状态信息 |
| `include_preflight` / `includePreflight` | boolean | false | 是否包含预检结果 |
### Preflight 参数
| 参数名 | 类型 | 说明 |
|--------|------|------|
| `mode` | string | 预检模式 |
| `failure_window_hours` | number | 失败窗口小时数 |
| `recent_failure_window_hours` | number | 最近失败窗口小时数 |
| `recent_change_window_hours` | number | 最近变更窗口小时数 |
| `strict` | boolean | 是否启用严格模式 |
| `record_event` / `recordEvent` | boolean | 是否记录事件 |
### 事件反馈参数
| 参数名 | 类型 | 说明 |
|--------|------|------|
| `receipt_id` / `receiptId` | string | 收据标识符 |
| `input` | unknown | 输入数据 |
| `output` | unknown | 输出数据 |
| `outcome` | string | 结果（used/helpful/wrong） |
| `error_summary` / `errorSummary` | string | 错误摘要 |
| `evidence_feedback` | object | 证据反馈映射 |
## 认证机制
### API 密钥认证
非环回地址的请求必须提供 Bearer 令牌认证：
```
Authorization: Bearer
```
API 密钥通过环境变量 `AUDREY_API_KEY` 配置。资料来源：[CHANGELOG.md](https://github.com/Evilander/Audrey/blob/main/CHANGELOG.md)
### 安全措施
1. **时序安全比较**：HTTP API 密钥比较使用 `crypto.timingSafeEqual` 而非字符串 `!==`，防止前缀匹配时序泄露攻击。资料来源：[CHANGELOG.md](https://github.com/Evilander/Audrey/blob/main/CHANGELOG.md)
2. **选项清理**：`/v1/recall` 和 `/v1/capsule` 不再将调用者选项直接传播到 `audrey.recall()`，新增的 `sanitizeRecallOptions()` 白名单函数会过滤不安全的参数，防止 `includePrivate: true` 等 ACL 绕过。资料来源：[CHANGELOG.md](https://github.com/Evilander/Audrey/blob/main/CHANGELOG.md)
3. **绑定安全**：`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)
## 环境变量配置
| 变量名 | 默认值 | 说明 |
|--------|--------|------|
| `AUDREY_PORT` | `7437` | REST API 监听端口 |
| `AUDREY_HOST` | `127.0.0.1` | REST API 绑定地址 |
| `AUDREY_API_KEY` | unset | 非环回请求必需的 Bearer 令牌 |
| `AUDREY_ALLOW_NO_AUTH` | `0` | 允许无认证的非环回绑定 |
| `AUDREY_ENABLE_ADMIN_TOOLS` | `0` | 启用导出、导入和遗忘路由 |
| `AUDREY_DEBUG` | `0` | 打印 MCP 信息日志 |
| `AUDREY_PROFILE` | `0` | 通过 MCP `_meta.diagnostics` 发出每阶段计时 |
## Python SDK 集成
Python 客户端通过 HTTP 调用 REST API 实现所有功能。资料来源：[python/README.md](https://github.com/Evilander/Audrey/blob/main/python/README.md)
### 同步客户端
```python
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()
```
### 异步客户端
```python
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` 处理器
## 部署模式
### 启动服务
```bash
npx audrey serve
```
### Docker 部署
支持通过 Docker 和 Compose 进行容器化部署，REST API 端点暴露在配置的端口上。
## 数据流
```mermaid
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](https://github.com/Evilander/Audrey/blob/main/mcp-server/index.ts)
## 错误处理
### HTTP 状态码
| 状态码 | 说明 |
|--------|------|
| 200 | 请求成功 |
| 400 | 请求参数错误 |
| 401 | 认证失败 |
| 404 | 端点不存在 |
| 500 | 服务器内部错误 |
### 验证错误
请求体中的参数经过验证，非法参数会被拒绝并返回详细的错误信息。资料来源：[src/routes.ts](https://github.com/Evilander/Audrey/blob/main/src/routes.ts)
## 与 MCP 协议的关系
REST API 与 MCP（Model Context Protocol）stdio 服务器共享相同的核心引擎，但通过不同的传输层暴露功能：
| 特性 | MCP | REST API |
|------|-----|----------|
| 传输协议 | stdio | HTTP |
| 主要用途 | 代理集成 | 外部客户端 |
| 实时性 | 更高 | 标准 HTTP 延迟 |
| 工具数量 | 20+ | 4+ |
---
## CLI工具
### 相关页面
相关主题：[Audrey Guard 安全循环](#page-audrey-guard), [快速开始](#page-quick-start)
相关源码文件
以下源码文件用于生成本页说明：
- [README.md](https://github.com/Evilander/Audrey/blob/main/README.md)
- [mcp-server/index.ts](https://github.com/Evilander/Audrey/blob/main/mcp-server/index.ts)
- [src/impact.ts](https://github.com/Evilander/Audrey/blob/main/src/impact.ts)
- [src/routes.ts](https://github.com/Evilander/Audrey/blob/main/src/routes.ts)
- [src/rules-compiler.ts](https://github.com/Evilander/Audrey/blob/main/src/rules-compiler.ts)
- [src/capsule.ts](https://github.com/Evilander/Audrey/blob/main/src/capsule.ts)
- [src/redact.ts](https://github.com/Evilander/Audrey/blob/main/src/redact.ts)
- [CHANGELOG.md](https://github.com/Evilander/Audrey/blob/main/CHANGELOG.md)
# CLI工具
Audrey 提供了一套完整的命令行界面（CLI）工具，用于管理 AI 代理的记忆系统。通过 CLI，用户可以执行记忆检查、原则提升、影响分析、工具观察等核心操作。
## 概述
Audrey CLI 是与 Audrey 记忆系统交互的主要方式之一，支持多种子命令以满足不同的使用场景：
- **guard** — 记忆驱动的动作预检，在执行危险操作前进行检查
- **promote** — 将高置信度记忆提升为持久化规则文件
- **impact** — 生成记忆系统的影响分析报告
- **install** — 安装和配置 Audrey 与目标主机的集成
- **doctor** — 诊断 Audrey 环境配置状态
- **status** — 查看记忆系统当前状态
- **dream** — 触发记忆巩固与整合过程
- **reembed** — 重新生成向量嵌入
- **hook-config** — 生成 Claude Code 钩子配置
- **mcp-config** — 生成 MCP 服务器配置
资料来源：[README.md](https://github.com/Evilander/Audrey/blob/main/README.md)
## 命令详解
### guard 命令
`guard` 是 Audrey 的核心安全循环命令，用于在执行工具操作前进行记忆预检。
```bash
audrey guard --tool "" [options]
```
#### 参数说明
| 参数 | 说明 | 类型 |
|------|------|------|
| `--tool` | 工具名称（如 `Bash`, `Write`） | 字符串 |
| `--explain` | 显示决策依据 | 标志位 |
| `--strict` | 严格模式，拒绝所有警告决策 | 标志位 |
| `--hook` | 以钩子模式运行 | 标志位 |
| `--json` | 输出 JSON 格式结果 | 标志位 |
| `--fail-on-warn` | 遇到警告时返回失败 | 标志位 |
| `--session-id` | 会话标识符 | 字符串 |
| `--cwd` | 工作目录 | 字符串 |
| `--include-capsule` | 在响应中包含记忆胶囊 | 标志位 |
#### 返回值
`guard` 命令返回三种决策结果：
- **`allow`** — 允许执行，提供相关记忆上下文
- **`warn`** — 警告执行，显示需要注意的记忆内容
- **`block`** — 阻止执行，基于记忆中的风险标记
资料来源：[mcp-server/index.ts:45-89](https://github.com/Evilander/Audrey/blob/main/mcp-server/index.ts)
#### 执行流程图
```mermaid
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`）。
```bash
audrey promote [--yes] [--dry-run] [--limit ]
```
#### 参数说明
| 参数 | 说明 | 默认值 |
|------|------|--------|
| `--yes` | 跳过确认直接写入 | false |
| `--dry-run` | 预览将要创建的文件 | false |
| `--limit` | 最大提升数量 | 10 |
#### 生成的文件格式
提升后的规则文件包含 YAML 前置元数据：
```yaml
---
title: Audrey semantic memory
source_memory_ids: []
confidence: 0.85
evidence_count: 3
promoted_at: 2025-01-15T10:30:00Z
---
```
资料来源：[src/rules-compiler.ts:1-45](https://github.com/Evilander/Audrey/blob/main/src/rules-compiler.ts)
### impact 命令
`impact` 命令生成记忆系统的使用影响分析报告，帮助评估记忆系统的实际效果。
```bash
audrey impact [--window-days ] [--format ]
```
#### 报告内容
| 指标 | 说明 |
|------|------|
| `episodic` | 情景记忆总数（来自直接观察） |
| `semantic` | 语义记忆总数（经巩固的原则） |
| `procedural` | 程序性记忆总数（操作步骤） |
| `validatedTotal` | 经过验证的记忆总数 |
| `topUsed` | 使用频率最高的记忆 |
| `weakest` | 置信度最低的记忆 |
| `recentActivity` | 最近的记忆活动 |
#### 情绪指标
报告包含基于近近期记忆的情绪分析：
- **valence** — 情绪效价（积极/消极程度）
- **arousal** — 唤醒度
- **samples** — 用于分析的样本数量
资料来源：[src/impact.ts:1-80](https://github.com/Evilander/Audrey/blob/main/src/impact.ts)
### install 命令
`install` 命令用于将 Audrey 与目标主机进行集成配置。
```bash
audrey install --host [--dry-run]
```
#### 支持的主机
| 主机 | 说明 |
|------|------|
| `claude-code` | Claude Code 编辑器 |
| 其他 | 通用 MCP 配置生成 |
#### 安装流程
```mermaid
graph TD
A[运行 install 命令] --> B[检测主机类型]
B --> C{主机类型}
C -->|claude-code| D[生成 MCP 配置]
C -->|其他| E[生成通用配置]
D --> F[注册 Claude Code 钩子]
E --> G[输出配置供手动添加]
F --> H[验证安装]
```
资料来源：[mcp-server/index.ts:90-130](https://github.com/Evilander/Audrey/blob/main/mcp-server/index.ts)
### hook-config 命令
生成 Claude Code 的钩子配置文件。
```bash
audrey hook-config [--apply] [--scope ] [--project-dir ]
```
| 参数 | 说明 | 可选值 |
|------|------|--------|
| `--scope` | 钩子作用域 | `project`, `user` |
| `--apply` | 直接应用配置 | - |
| `--project-dir` | 项目目录路径 | 路径 |
资料来源：[mcp-server/index.ts:150-200](https://github.com/Evilander/Audrey/blob/main/mcp-server/index.ts)
### status 命令
查看 Audrey 记忆系统的当前状态。
```bash
audrey status [--json]
```
#### 显示内容
- **Mood** — 情绪指标（valence, arousal）
- **Memory** — 各类记忆数量统计
- **Principles** — 学习到的原则列表
- **Identity** — 身份相关记忆
- **Recent memories** — 最近创建的记忆
- **Unresolved** — 未解决的矛盾线索
### 其他命令
| 命令 | 功能 |
|------|------|
| `doctor` | 诊断环境配置问题 |
| `demo` | 运行演示模式 |
| `mcp-config` | 打印 MCP 服务器配置 |
| `dream` | 触发记忆巩固过程 |
| `reembed` | 重新生成向量嵌入 |
| `observe-tool` | 观察工具执行结果 |
| `greeting` | 问候语生成 |
## 环境变量配置
CLI 行为可通过以下环境变量进行配置：
| 变量 | 默认值 | 说明 |
|------|--------|------|
| `AUDREY_DATA_DIR` | `./audrey-data` | 数据存储目录 |
| `AUDREY_PORT` | `7437` | REST API 端口 |
| `AUDREY_HOST` | `127.0.0.1` | REST API 绑定地址 |
| `AUDREY_API_KEY` | 未设置 | API 认证密钥 |
| `AUDREY_ENABLE_ADMIN_TOOLS` | `0` | 启用导出/导入/遗忘工具 |
| `AUDREY_DEBUG` | `0` | 调试日志输出 |
| `AUDREY_PROFILE` | `0` | 性能分析 |
| `AUDREY_DISABLE_WARMUP` | `0` | 跳过嵌入预热 |
资料来源：[README.md](https://github.com/Evilander/Audrey/blob/main/README.md)
## REST API 端点
CLI 底层通过 Hono 服务器提供 REST API：
| 端点 | 方法 | 功能 |
|------|------|------|
| `/health` | GET | 健康检查 |
| `/v1/preflight` | POST | 动作预检（guard 功能） |
| `/v1/recall` | POST | 记忆召回 |
| `/v1/capsule` | POST | 获取记忆胶囊 |
| `/v1/status` | GET | 系统状态 |
资料来源：[src/routes.ts:1-50](https://github.com/Evilander/Audrey/blob/main/src/routes.ts)
## 安全机制
### API 密钥保护
`audrey serve` 默认绑定到 `127.0.0.1`，非回环地址启动需要 `AUDREY_API_KEY`。HTTP API 使用 `crypto.timingSafeEqual` 进行密钥比较，防止时序攻击。
### 写入路径限制
`audrey promote --yes` 拒绝向 `process.cwd()` 之外写入 `.claude/rules/*.md`，除非目标路径在 `AUDREY_PROMOTE_ROOTS` 环境变量中明确指定。
### 敏感信息脱敏
CLI 内置数据脱敏功能，自动处理以下敏感字段：
- 密码相关：`password`, `passwd`, `pwd`
- 密钥相关：`api_key`, `secret`, `token`
- 认证相关：`auth_token`, `bearer_token`, `jwt`
- 云服务：`aws_secret`, `private_key`
资料来源：[src/redact.ts:30-50](https://github.com/Evilander/Audrey/blob/main/src/redact.ts)
## 使用示例
### 动作预检
```bash
# 检查 Bash 命令
audrey guard --tool Bash "rm -rf node_modules" --explain
# JSON 格式输出
audrey guard --tool Bash "npm run deploy" --json
# 严格模式
audrey guard --tool Write "config.yaml" --strict
```
### 提升记忆为规则
```bash
# 预览将要创建的规则
audrey promote --dry-run
# 确认并写入
audrey promote --yes
# 限制数量
audrey promote --yes --limit 5
```
### 查看影响分析
```bash
# 默认 30 天窗口
audrey impact
# 指定窗口天数
audrey impact --window-days 7
# JSON 格式
audrey impact --format json
```
## 版本变更
| 版本 | 变更内容 |
|------|----------|
| 0.23.0 | 新增 `--include-capsule` 参数 |
| 0.22.0 | 性能优化：编码时间提升 40% |
| 0.21.0 | 新增 `usage_count` 和 `last_used_at` 追踪 |
| 0.20.0 | CLI 表面新增 `--help`/`--version` 短路处理 |
资料来源：[CHANGELOG.md](https://github.com/Evilander/Audrey/blob/main/CHANGELOG.md)
---
## JavaScript SDK
### 相关页面
相关主题：[系统架构](#page-system-architecture), [记忆模型](#page-memory-model)
相关源码文件
以下源码文件用于生成本页说明：
- [src/audrey.ts](https://github.com/Evilander/Audrey/blob/main/src/audrey.ts)
- [src/index.ts](https://github.com/Evilander/Audrey/blob/main/src/index.ts)
- [src/types.ts](https://github.com/Evilander/Audrey/blob/main/src/types.ts)
- [mcp-server/index.ts](https://github.com/Evilander/Audrey/blob/main/mcp-server/index.ts)
- [src/capsule.ts](https://github.com/Evilander/Audrey/blob/main/src/capsule.ts)
- [src/reflexes.ts](https://github.com/Evilander/Audrey/blob/main/src/reflexes.ts)
- [src/routes.ts](https://github.com/Evilander/Audrey/blob/main/src/routes.ts)
# JavaScript SDK
Audrey JavaScript SDK 是该项目的核心客户端库，提供与 Audrey 记忆运行时交互的完整 TypeScript 接口。SDK 支持同步和异步操作，可用于 Node.js 环境和 CLI 工具中。
## 核心架构
### 模块结构
```
audrey (SDK)
├── Audrey # 主类，包含所有记忆操作
├── AsyncAudrey # 异步版本
├── AudreyError # 错误类型
└── 类型导出 # 完整的 TypeScript 类型定义
```
### 主类概述
`Audrey` 类是 SDK 的核心，封装了所有与本地记忆存储交互的功能。主要特性包括：
- **记忆编码与检索**：支持三种记忆类型的写入和查询
- **Preflight 检查**：动作执行前的记忆验证
- **记忆胶囊构建**：上下文压缩与摘要生成
- **因果链路管理**：记忆之间的因果关系追踪
- **健康诊断**：运行时状态检查
## 记忆类型系统
Audrey 采用三层记忆架构，对应神经科学的不同记忆系统：
| 记忆类型 | 用途 | 特征 | 典型场景 |
|---------|------|------|---------|
| **情景记忆 (episodic)** | 事件记录 | 时间戳驱动、一次性的经验 | "上次执行 deploy 失败，报 OOM" |
| **语义记忆 (semantic)** | 知识存储 | 跨会话持久、基于重要性 | "项目使用 yarn 而非 npm" |
| **程序记忆 (procedural)** | 流程规范 | 步骤化、可执行 | "审查 PR 的流程是..." |
资料来源：[src/audrey.ts](https://github.com/Evilander/Audrey/blob/main/src/audrey.ts)
## 核心 API
### 记忆编码 (encode)
将信息编码为记忆存入存储系统。
```typescript
const memoryId = brain.encode(
"Stripe API 在超过 100 req/s 时返回 HTTP 429",
source="direct-observation",
tags=["stripe", "rate-limit"]
);
```
**参数说明**：
| 参数 | 类型 | 必需 | 说明 |
|-----|------|-----|------|
| content | string | 是 | 记忆内容 |
| source | string | 否 | 来源标识（默认值：`direct-observation`）|
| tags | string[] | 否 | 标签数组 |
| memoryType | 'episodic' \\| 'semantic' \\| 'procedural' | 否 | 记忆类型 |
| wait_for_consolidation | boolean | 否 | 是否等待一致性确认 |
### 记忆检索 (recall)
根据查询字符串检索相关记忆。
```typescript
const results = brain.recall("stripe rate limits", limit=5);
```
**参数说明**：
| 参数 | 类型 | 默认值 | 说明 |
|-----|------|-------|------|
| query | string | - | 检索查询 |
| limit | number | 16 | 返回结果数量 |
| scope | 'shared' \\| 'agent' | 'shared' | 检索范围 |
| retrieval | 'hybrid' \\| 'vector' | 'hybrid' | 检索模式 |
| mood | MoodOptions | - | 情感参数 |
| context | Record | - | 额外上下文 |
### 记忆快取 (snapshot/restore)
支持记忆状态的导出与恢复。
```typescript
// 导出
const snapshot = brain.snapshot();
// 恢复到空存储
restoreTarget.restore(snapshot);
```
资料来源：[python/README.md](https://github.com/Evilander/Audrey/blob/main/python/README.md)
## Preflight 检查系统
Preflight 是 Audrey 的核心安全机制，在动作执行前验证记忆状态。
### 工作流程
```mermaid
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
```
### 返回决策
| 决策 | 含义 | 触发条件 |
|-----|------|---------|
| `allow` | 允许执行 | 无风险匹配 |
| `warn` | 警告执行 | 存在低置信度风险 |
| `block` | 阻止执行 | 高置信度风险或阻止级反射 |
资料来源：[src/reflexes.ts](https://github.com/Evilander/Audrey/blob/main/src/reflexes.ts)
资料来源：[src/preflight.ts](https://github.com/Evilander/Audrey/blob/main/src/preflight.ts)
## 记忆胶囊 (Memory Capsule)
记忆胶囊是上下文压缩机制，将检索到的记忆压缩为可嵌入 LLM 上下文的格式。
### 胶囊结构
```typescript
interface MemoryCapsule {
sections: {
must_follow: []; // 必须遵循的规则
project_facts: []; // 项目事实
user_preferences: []; // 用户偏好
procedures: []; // 程序流程
risks: []; // 风险警告
contradictions: []; // 矛盾信息
recent_changes: []; // 近期变更
};
mood: MoodState; // 情感状态
health: HealthStatus; // 健康状态
}
```
### 构建选项
| 选项 | 类型 | 默认值 | 说明 |
|-----|------|-------|------|
| mode | 'conservative' \\| 'balanced' \\| 'aggressive' | 'balanced' | 压缩激进程度 |
| budgetChars | number | 4000 | 上下文预算上限 |
| recentChangeWindowHours | number | 24 | 近期变更时间窗口 |
| includeRisks | boolean | true | 是否包含风险 |
| includeContradictions | boolean | true | 是否包含矛盾信息 |
资料来源：[src/capsule.ts](https://github.com/Evilander/Audrey/blob/main/src/capsule.ts)
## 记忆反射 (Memory Reflexes)
记忆反射是预定义的动作-响应模式，用于在 Preflight 阶段自动匹配。
### 反射类型
| 类型 | 响应方式 | 使用场景 |
|-----|---------|---------|
| `block` | 阻止执行 | 已知危险操作 |
| `warn` | 发出警告 | 潜在风险操作 |
| `guide` | 提供引导 | 建议性操作 |
### 反射报告构建
```typescript
const report = await buildReflexReport(audrey, "npm run deploy", {
includeCapsule: true,
includePreflight: true
});
```
资料来源：[src/reflexes.ts](https://github.com/Evilander/Audrey/blob/main/src/reflexes.ts)
## HTTP API 层
SDK 底层通过 HTTP REST API 与本地服务通信。
### 路由结构
| 端点 | 方法 | 说明 |
|-----|------|------|
| `/health` | GET | 健康检查 |
| `/v1/encode` | POST | 编码记忆 |
| `/v1/recall` | POST | 检索记忆 |
| `/v1/snapshot` | GET | 导出快照 |
| `/v1/restore` | POST | 恢复快照 |
| `/v1/guard` | POST | Preflight 检查 |
### 参数清理
`src/routes.ts` 中实现了严格的参数白名单机制：
```typescript
function sanitizeRecallOptions(opts: Record): RecallOptions {
// 仅允许特定字段通过
const allowedKeys = ['limit', 'tags', 'sources', 'after', 'before',
'context', 'mood', 'retrieval', 'scope'];
// ...
}
```
资料来源：[src/routes.ts](https://github.com/Evilander/Audrey/blob/main/src/routes.ts)
## CLI 命令行接口
### guard 命令
在执行工具前运行记忆检查。
```bash
audrey guard --tool Bash "npm run deploy"
```
**参数说明**：
| 参数 | 说明 |
|-----|------|
| `--tool ` | 工具名称 |
| `--session-id ` | 会话标识 |
| `--cwd ` | 工作目录 |
| `--json` | JSON 输出格式 |
| `--explain` | 显示详细解释 |
| `--hook` | Hook 模式运行 |
| `--strict` | 严格模式（block 决策时退出） |
### hook-config 命令
配置 Claude Code 等 IDE 的集成钩子。
```bash
audrey hook-config claude-code --apply --scope project
```
### doctor 命令
诊断运行时健康状态。
```bash
audrey doctor [--verbose]
```
**检查项**：
- Node.js 运行时版本（需 >= 20）
- 数据目录存在性
- MCP 入口点配置
- LLM 提供商配置
- Embedding 提供商配置
资料来源：[mcp-server/index.ts](https://github.com/Evilander/Audrey/blob/main/mcp-server/index.ts)
## 类型系统
### 核心类型定义
```typescript
// 记忆条目
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;
mood?: MoodOptions;
retrieval?: 'hybrid' | 'vector';
scope?: 'shared' | 'agent';
}
```
资料来源：[src/types.ts](https://github.com/Evilander/Audrey/blob/main/src/types.ts)
## 错误处理
### 错误类型
| 错误类型 | 说明 |
|---------|------|
| `AudreyError` | 基础错误类型 |
| 验证错误 | 参数校验失败 |
| 存储错误 | 数据库操作失败 |
| LLM 错误 | AI 提供商调用失败 |
### 错误处理示例
```typescript
try {
await brain.recall("query", { limit: -1 });
} catch (error) {
if (error instanceof AudreyError) {
console.error(`SDK Error: ${error.message}`);
}
}
```
## 情感状态 (Mood)
Audrey 支持情感状态追踪，用于调整检索和响应行为。
```typescript
interface MoodState {
valence: number; // -1.0 到 1.0，情感正负
arousal: number; // 0.0 到 1.0，激活程度
samples: number; // 采样数量
}
```
## 信任评估 (Confidence)
记忆具有置信度评分，影响检索权重和决策。
### 衰减机制
```typescript
function recencyDecay(
createdAt: Date,
halfLifeDays: number = 30
): number {
// 基于时间的衰减计算
}
```
**规则**：
- `halfLifeDays <= 0` 时抛出 `RangeError`
- 默认半衰期为 30 天
- 置信度基于记忆年龄、验证次数、使用频率综合计算
资料来源：[src/causal.ts](https://github.com/Evilander/Audrey/blob/main/src/causal.ts)
## 因果链路 (Causal Links)
记忆之间可以建立因果关系。
```typescript
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` 实现了多层脱敏机制：
```typescript
const SENSITIVE_KEY_PATTERN = /(password|secret|api_key|token|...)/i;
```
**脱敏规则**：
| 类别 | 检测方式 |
|-----|---------|
| API 密钥 | 键名模式匹配 |
| 密码凭证 | 键名 + 值模式 |
| Bearer Token | 值内容检测 |
| JWT | 结构化检测 |
| AWS 密钥 | 特定前缀匹配 |
### JSON 递归遍历
脱敏系统递归遍历 JSON 结构，对象、数组、字符串分别处理，保留原始数据结构。
资料来源：[src/redact.ts](https://github.com/Evilander/Audrey/blob/main/src/redact.ts)
## 配置与环境变量
### 关键环境变量
| 变量 | 说明 | 默认值 |
|-----|------|-------|
| `AUDREY_DATA_DIR` | 数据存储目录 | `~/.audrey` |
| `AUDREY_LLM_PROVIDER` | LLM 提供商 | 自动检测 |
| `AUDREY_EMBEDDING_PROVIDER` | Embedding 提供商 | `local` |
| `AUDREY_API_KEY` | API 认证密钥 | - |
| `AUDREY_ALLOW_NO_AUTH` | 允许无认证 | `false` |
### 提供商支持
**LLM 提供商**：
- OpenAI
- Anthropic
- 本地 Ollama
- 自定义端点
**Embedding 提供商**：
- `local`：本地 GPU 加速（默认）
- 云端服务
## 性能优化
### 近期版本性能改进 (0.22.0)
| 指标 | 改进幅度 |
|-----|---------|
| 编码响应时间 | 40% 提升 (24.7ms → 15.2ms) |
| 冷启动首次编码 | 18.7x 加速 (525ms → 28ms) |
| 混合检索 | 2.1x 加速 (30.2ms → 14.3ms) |
### 优化策略
1. **复用 Embedding**：验证、干扰检测、情感共鸣共享主内容向量
2. **预热机制**：冷启动时执行预热，避免首次延迟
3. **流式检索**：`recallStream` 支持流式响应
资料来源：[CHANGELOG.md](https://github.com/Evilander/Audrey/blob/main/CHANGELOG.md)
## 使用示例
### 基础同步使用
```typescript
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();
```
### 异步使用
```typescript
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 检查
```typescript
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 代理集成：
```mermaid
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](https://github.com/Evilander/Audrey/blob/main/README.md)
## 版本历史关键变更
### 0.23.0
- 移除 `hybrid_strict` 检索模式（曾是 `hybrid` 的别名）
- 新增 `closeAsync(timeoutMs?)` 方法
- 新增 `sanitizeRecallOptions()` 参数白名单工具
### 0.22.0
- 新增 `wait_for_consolidation` 参数
- 新增 `retrieval` 参数（`hybrid` / `vector`）
- 性能大幅优化
资料来源：[CHANGELOG.md](https://github.com/Evilander/Audrey/blob/main/CHANGELOG.md)
---
---
## Doramagic 踩坑日志
项目：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