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

核心概念

Statewave 的数据模型围绕以下核心实体构建：

graph TD
    A[Subject 主体] --> B[Episode 事件片段]
    A --> C[Memory 记忆片段]
    B --> D[Compilation 编译]
    C --> E[Context 上下文]
    F[Resolution 解决方案] --> A
    G[Snapshot 快照] --> A

Subject（主体）

Subject 是最高层级的数据容器，代表一个特定的实体（如客户、项目、用户或任何需要记忆的抽象概念）。每个 Subject 拥有独立的 Episode 和 Memory 存储空间。

资料来源：server/starter_packs/statewave-support-agent/manifest.json:8

Episode（事件片段）

Episode 是 Statewave 中的基础数据单元，代表一次不可变的事件或交互记录。Episode 可以来源于：

• 实时对话转录
• GitHub Issues、Pull Requests
• 文档变更
• Slack 消息
• MCP Server 事件
• 任何自定义数据源

每个 Episode 包含标题、正文内容、元数据以及来源信息，通过 content_hash 实现内容去重和增量更新。

资料来源：scripts/docs_loader.py:30-50

Memory（记忆片段）

Memory 是经过编译（Compile）后的结构化记忆。编译过程从多个 Episode 中提取关键信息，生成包含以下属性的记忆单元：

资料来源：server/api/admin.py:50-80

Resolution（解决方案）

Resolution 用于跟踪会话级别的解决方案状态，支持 SLA 指标计算和响应时间追踪。

资料来源：server/api/timeline.py:60-90

Snapshot（快照）

Snapshot 提供 Subject 的完整状态快照功能，包含 Episodes、Memories 和 Resolutions 的时间点副本，支持数据恢复和迁移场景。

资料来源：server/services/snapshots.py:20-80

系统架构

Statewave 采用现代化的微服务架构设计，主要组件包括：

graph TD
    subgraph 客户端层
        A[Agent 应用]
        B[Connectors]
        C[SDK]
    end
    
    subgraph API 网关层
        D[FastAPI Server<br/>:8100]
        E[OpenAPI / Swagger]
    end
    
    subgraph 业务逻辑层
        F[Episode Service]
        G[Memory Service]
        H[Context Service]
        I[Timeline Service]
    end
    
    subgraph 数据层
        J[(PostgreSQL)]
        K[(Embedding Store)]
    end
    
    subgraph 外部服务
        L[LiteLLM]
        M[LLM Provider]
    end
    
    A --> D
    B --> D
    C --> D
    D --> F
    D --> G
    D --> H
    D --> I
    F --> J
    G --> J
    G --> K
    H --> L
    I --> J
    L --> M

技术栈

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

API 参考

健康检查端点

Episode 管理

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

Memory 管理

Context 上下文组装

Subject 主体管理

时间线与解决方案

资料来源：README.md:35-55

编译模式

Statewave 支持两种编译模式：

LLM 编译（默认）

使用大型语言模型从 Episode 中提取结构化 Memory，提供更高的语义理解能力。需要配置 LLM API Key。

启发式编译

基于规则的编译模式，适用于演示环境或无 LLM 场景，性能更快但语义理解能力有限。

配置方式：STATEWAVE_COMPILER_TYPE=heuristic

资料来源：helm/statewave/README.md:25-30

连接器生态

Statewave 提供了丰富的连接器（Connector）生态系统，用于从不同数据源摄取 Episode：

安装方式（按需选择）：

npm install @statewavedev/connectors-github
npm install @statewavedev/connectors-markdown
npm install @statewavedev/connectors-slack
npm install @statewavedev/connectors-n8n
npm install @statewavedev/connectors-zapier
npm install @statewavedev/mcp-server

资料来源：README.md:80-110

配置参考

环境变量配置

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

部署方式

Docker Compose 部署

services:
  statewave:
    image: statewavedev/statewave:latest
    ports: ["8100:8100"]
    environment:
      STATEWAVE_DATABASE_URL: postgresql+asyncpg://statewave:statewave@db:5432/statewave
      STATEWAVE_LITELLM_API_KEY: sk-...
    depends_on:
      db:
        condition: service_healthy

volumes:
  pgdata:

docker compose up -d
curl http://localhost:8100/healthz

指定版本部署：

STATEWAVE_VERSION=0.7.0 docker compose up -d

Kubernetes Helm 部署

helm install statewave ./helm/statewave \
  --set database.url='postgresql+asyncpg://...' \
  --set llm.apiKey='sk-...'

Helm 安装时会自动运行数据库迁移（Alembic）Job，确保在 API Pod 接收流量前完成 schema 初始化。

资料来源：DOCKER.md:1-50 资料来源：helm/statewave/README.md:1-30

Docker 镜像标签

资料来源：DOCKER.md:30-40

启动包

Statewave 提供了开箱即用的 Starter Pack，其中包含预置的 Episodes 和 Memories：

statewave-support-agent

预编译的支持代理启动包，包含 276 个 Episodes 和 364 个 Memories，涵盖：

• 产品文档
• 架构设计
• 部署指南
• 故障排除
• 竞品对比

版本：1.2026.05.08

导入后可立即启用文档驱动的支持代理，无需额外引导步骤。

资料来源：server/starter_packs/statewave-support-agent/manifest.json:1-20

当前限制

Statewave 目前处于活跃开发阶段（v0.8.0），存在以下已知限制：

速率限制

• 速率限制按 IP 级别：使用分布式（Postgres 后端）实现，但仅按 IP 键控，尚未支持按租户或 API Key 级别限制

多租户

• 多租户隔离在应用层：通过查询作用域数据隔离（v0.5）+ 每租户配置/策略/收据包（v0.8）实现
• 尚未支持 PostgreSQL RLS（行级安全策略）

资料来源：README.md:130-140

测试

运行测试

# 单元测试（无需数据库）
pytest tests/test_*.py -v

# 集成测试（需要 PostgreSQL）
PGPASSWORD=statewave createdb -h localhost -U statewave statewave_test
pytest tests/integration/ -v

# 全部测试
pytest tests/ -v

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

相关资源

• 官方文档：https://statewave.ai
• 仓库地址：https://github.com/smaramwbc/statewave
• 连接器生态：https://github.com/smaramwbc/statewave-connectors
• API 契约文档：https://github.com/smaramwbc/statewave-docs/blob/main/api/v1-contract.md

系统要求

资料来源：docker-compose.yml:1-50

快速启动（Docker Compose）

1. 克隆仓库

git clone https://github.com/smaramwbc/statewave.git
cd statewave

2. 配置环境变量

Statewave 通过环境变量进行配置。在项目根目录创建 .env 文件：

cp .env.example .env

基础配置项：

资料来源：.env.example

3. 启动服务

# docker-compose.yml 核心配置
services:
  app:
    image: statewavedev/statewave:latest
    ports:
      - "8100:8100"
    environment:
      STATEWAVE_DATABASE_URL: postgresql+asyncpg://statewave:statewave@db:5432/statewave
      STATEWAVE_LITELLM_API_KEY: sk-...
    depends_on:
      db:
        condition: service_healthy

volumes:
  pgdata:

docker compose up -d

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

4. 验证服务

服务启动后，通过健康检查端点验证：

curl http://localhost:8100/healthz

预期响应：{"status":"ok"}

资料来源：README.md:50-55

服务架构

graph TD
    A[客户端] --> B[Statewave API<br/>:8100]
    B --> C[PostgreSQL<br/>Database]
    B --> D[LLM Provider<br/>LiteLLM]
    B --> E[Embedding Provider]
    
    F[Connectors] --> B
    G[SDK] --> B
    
    style B fill:#e1f5fe
    style C fill:#f3e5f5

API 基础使用

文档界面

核心 API 端点

资料来源：README.md:40-45

基本请求示例

摄入事件：

curl -X POST http://localhost:8100/v1/episodes \
  -H "Content-Type: application/json" \
  -H "X-Tenant-ID: default" \
  -d '{
    "subject_id": "user-123",
    "source": "api",
    "type": "conversation",
    "payload": {
      "role": "user",
      "content": "如何部署 Statewave？"
    },
    "session_id": "session-001"
  }'

搜索记忆：

curl "http://localhost:8100/v1/memories/search?query=部署" \
  -H "X-Tenant-ID: default"

版本管理

Statewave 支持指定版本部署：

STATEWAVE_VERSION=0.7.0 docker compose up -d

资料来源：DOCKER.md:25-35

运行测试

# 单元测试（无需数据库）
pytest tests/test_*.py -v

# 集成测试（需要 PostgreSQL）
PGPASSWORD=statewave createdb -h localhost -U statewave statewave_test
pytest tests/integration/ -v

# 运行全部测试
pytest tests/ -v

资料来源：README.md:180-190

完整配置选项

资料来源：README.md:155-175

下一步

• 查看 API v1 完整契约
• 阅读部署指南
• 了解 Connectors 生态系统
• 查看架构文档

1. 概述

Statewave 是一个自托管的长期记忆管理系统，专为 AI Agent 设计，旨在帮助 Agents 跨越会话边界保持上下文连贯性。该系统通过摄取事件片段（Episodes）、编译记忆（Memories）、并提供智能检索上下文构建能力，使 AI Agent 能够在多轮对话中持续学习和适应。

当前版本：v0.8.0，采用 AGPL-3.0 开源协议。资料来源：README.md

2. 核心设计理念

Statewave 的架构围绕三个核心概念展开：

系统支持两种编译模式：LLM 编译（语义理解）和 Heuristic 编译（规则提取）。资料来源：server/services/compilers/heuristic.py

3. 系统架构图

graph TB
    subgraph 接入层
        API[REST API v1]
        DOCS[OpenAPI / Swagger]
        REDOC[ReDoc]
    end

    subgraph 应用层
        EP[Episode 管理]
        MEM[Memory 管理]
        CTX[Context 构建]
        TIMELINE[Timeline 服务]
        SNAP[Snapshot 服务]
        ADMIN[Admin API]
    end

    subgraph 服务层
        COMPILER[编译引擎]
        RANKER[排名服务]
        SEARCH[搜索服务]
    end

    subgraph 数据层
        DB[(PostgreSQL)]
        CACHE[缓存层]
    end

    API --> EP
    API --> MEM
    API --> CTX
    API --> TIMELINE
    API --> SNAP
    API --> ADMIN

    EP --> COMPILER
    MEM --> RANKER
    CTX --> RANKER
    CTX --> SEARCH

    COMPILER --> DB
    RANKER --> DB
    SEARCH --> DB
    TIMELINE --> DB
    SNAP --> DB

4. 技术栈

资料来源：DOCKER.md

5. API 架构

5.1 主要端点

资料来源：README.md

5.2 健康检查端点

6. 数据模型

6.1 核心实体关系

erDiagram
    SUBJECT ||--o{ EPISODE : contains
    SUBJECT ||--o{ MEMORY : owns
    EPISODE ||--o{ MEMORY : contributes_to
    SUBJECT ||--o{ RESOLUTION : tracks
    SUBJECT ||--o| SNAPSHOT : preserves

6.2 Episode 数据结构

事件片段是系统的原子输入单元，包含：

{
    "id": "uuid",
    "subject_id": "string",
    "source": "string",           # 来源标识 (e.g., "api", "github", "slack")
    "type": "string",            # 类型 (e.g., "chat", "issue", "doc_section")
    "payload": {
        "text": "string",
        "messages": [...],
        "event_time": "datetime"  # 可选的显式时间戳
    },
    "metadata": {},
    "provenance": {
        "content_hash": "string",
        "pack_version": "int"
    },
    "occurred_at": "datetime",
    "created_at": "datetime",
    "session_id": "string | null"
}

资料来源：server/api/timeline.py

6.3 Memory 数据结构

记忆从事件编译而来，具有时间有效性和置信度：

资料来源：server/services/snapshots.py

7. 服务层架构

7.1 编译引擎

编译引擎负责将 Episodes 转换为 Memories，支持两种模式：

graph LR
    A[Episodes] --> B{编译模式}
    B -->|Heuristic| C[规则提取]
    B -->|LLM| D[语义理解]
    C --> E[Memories]
    D --> E

Heuristic 编译：基于规则提取摘要和配置事实

• episode_summary：从文本提取摘要，置信度 0.8
• profile_fact：提取配置类事实，置信度 0.6

资料来源：server/services/compilers/heuristic.py

7.2 上下文构建服务

上下文构建服务（Context Service）负责根据查询组装最优上下文：

graph TB
    Q[用户查询] --> S[搜索相关Memories和Episodes]
    S --> SC[评分计算]
    SC --> R[相关性评分]
    R --> RANK[排名服务]
    RANK --> TB[Token预算约束]
    TB --> CTX[组装上下文包]

Context Service 内部使用 _ScoredItem 类管理评分：

class _ScoredItem:
    __slots__ = ("score", "kind", "memory_row", "episode_row", "text", "section")

资料来源：server/services/context.py

7.3 快照服务

快照服务支持主体的完整备份和恢复：

资料来源：server/services/snapshots.py

8. 时间线服务

时间线服务（Timeline Service）提供会话视图的事件合并展示：

graph TB
    subgraph 事件类型
        EE[Episode Event]
        RE[Resolution Event]
    end
    
    subgraph 时间线事件
        TEE[TimelineEpisodeEvent]
        TRE[TimelineResolutionEvent]
    end
    
    EE --> TEE
    RE --> TRE
    TEE --> MERGE[合并排序]
    TRE --> MERGE
    MERGE --> RESP[SessionTimelineResponse]

关键指标计算：

• first_response_seconds：首次响应时间
• resolution_seconds：解决时间
• first_response_breached：是否超出 SLA 首次响应阈值
• resolution_breached：是否超出 SLA 解决时间阈值

资料来源：server/api/timeline.py

9. 多租户架构

Statewave 采用应用层多租户隔离：

当前限制：

• 限流基于 IP 地址，未实现 per-tenant 或 per-API-key 限流
• 多租户采用应用层隔离，非 PostgreSQL Row-Level Security (RLS)

资料来源：README.md

10. 配置管理

10.1 环境变量配置

10.2 编译模式配置

资料来源：helm/statewave/README.md

11. 部署架构

11.1 Docker 部署

services:
  statewave:
    image: statewavedev/statewave:latest
    ports: ["8100:8100"]
    environment:
      STATEWAVE_DATABASE_URL: postgresql+asyncpg://statewave:statewave@db:5432/statewave
      STATEWAVE_LITELLM_API_KEY: sk-...
    depends_on:
      db:
        condition: service_healthy

11.2 Kubernetes 部署

使用 Helm Chart 部署，包含：

• Pre-install Job：运行数据库迁移（alembic upgrade head）
• Pre-upgrade Job：升级时重复迁移
• 支持 existingSecret 引用敏感配置

资料来源：DOCKER.md

12. 启动流程

sequenceDiagram
    participant Client
    participant API as FastAPI App
    participant DB as PostgreSQL
    participant Migrator as Alembic
    
    Client->>API: 启动请求
    API->>Migrator: alembic upgrade head
    Migrator->>DB: 执行迁移
    DB-->>Migrator: 迁移完成
    Migrator-->>API: 就绪
    API-->>Client: 服务可用

13. 外部集成

13.1 连接器生态

Statewave 提供官方连接器将外部数据源摄入为 Episodes：

13.2 SDK 支持

提供 Python SDK 支持自定义摄入路径，连接器独立安装：

npm install @statewavedev/connectors-github
npm install @statewavedev/connectors-markdown
npm install @statewavedev/mcp-server

14. 安全特性

15. 测试架构

集成测试数据库配置：

PGPASSWORD=statewave createdb -h localhost -U statewave statewave_test

16. 总结

Statewave 采用分层架构设计，从底层的 PostgreSQL 数据持久化，到服务层的编译引擎、上下文构建、排名服务，再到 API 接入层，构成了一个完整的 AI Agent 记忆管理系统。其核心优势包括：

1. 事件驱动的摄入：支持多种来源（API、连接器、Webhook）
2. 灵活的编译引擎：兼容 LLM 和 Heuristic 两种模式
3. 智能上下文组装：基于 token 预算的排名检索
4. 企业级功能：多租户、快照、SLA 追踪
5. 可观测性：健康检查、Webhook 回调

系统当前处于活跃开发状态（v0.8.0），建议生产环境使用语义版本号固定部署。

概述

Episode（事件）是 Statewave 记忆系统的原子数据单元，代表与特定主题（Subject）相关的每一次交互或事件记录。Episode 采用仅追加（append-only）模式写入，不可直接修改，确保了事件溯源的完整性。

Statewave 通过 Connectors 从多种数据源收集 Episodes，这些事件随后被编译（Compile）为结构化的 Memory（记忆），供 Agent 在推理时检索。

核心职责：

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

概述

编译器系统（Compiler System）是 Statewave 的核心子系统，负责将原始的对话事件（Episodes）转化为结构化的记忆（Memories）。当新的对话片段被摄入系统后，编译器会分析这些事件，提取有价值的信息，生成可供后续检索和推理使用的记忆条目。

编译过程是幂等操作（idempotent），这意味着对同一批事件重复编译不会产生副作用或重复数据。系统会追踪每个记忆的来源事件（source_episode_ids），确保记忆与原始事件之间的可追溯性。

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

架构设计

编译器类型

Statewave 支持两种编译策略，可根据部署环境和技术要求选择合适的模式：

# Helm 部署配置示例
compiler:
  type: llm  # 或 heuristic

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

核心组件

graph TD
    A[Episode 摄入] --> B{编译模式选择}
    B -->|heuristic| C[HeuristicCompiler]
    B -->|llm| D[LLMCompiler]
    C --> E[提取概要信息]
    C --> F[提取 Profile Facts]
    D --> G[语义分析与总结]
    D --> H[关系抽取]
    E --> I[MemoryRow 生成]
    F --> I
    G --> I
    H --> I
    I --> J[冲突检测]
    J --> K[记忆合并/去重]
    K --> L[持久化存储]

主要组件职责：

编译流程

完整工作流

graph LR
    A[收集未编译 Episodes] --> B{遍历 Episodes}
    B --> C[确定时间锚点]
    C --> D{编译模式}
    D -->|heuristic| E[提取概要 + Facts]
    D -->|llm| F[LLM 分析总结]
    E --> G[生成 MemoryRows]
    F --> G
    G --> H[冲突检测]
    H --> I{存在冲突?}
    I -->|是| J[冲突消解]
    I -->|否| K[直接写入]
    J --> K
    K --> L[更新编译状态]
    L --> M{还有更多 Episodes?}
    M -->|是| B
    M -->|否| N[编译完成]

触发方式

编译可以通过以下方式触发：

1. 手动触发：调用 POST /v1/memories/compile API
2. 自动触发：在摄入新 Episode 后自动启动编译
3. 批量触发：通过 POST /v1/episodes/batch 摄入多集后统一编译

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

启发式编译器

概述

启发式编译器（HeuristicCompiler）是一种基于规则的信息提取引擎，无需外部 LLM 依赖即可运行。它通过正则表达式和启发式算法从文本中提取结构化信息。

记忆类型

启发式编译器生成以下类型的记忆：

资料来源：server/services/compilers/heuristic.py:1-80

时间锚点计算

编译器使用以下优先级确定记忆的时间锚点（valid_from）：

def episode_valid_from(ep: EpisodeRow) -> datetime:
    """返回派生记忆的最佳努力时间锚点"""
    # 优先级 1: payload.event_time — 客户端显式设置
    # 优先级 2: payload.messages[0].timestamp — 首条消息时间戳
    # 优先级 3: ep.created_at — 系统记录时间

时间锚点优先级：

资料来源：server/services/compilers/heuristic.py:80-100

Profile Facts 提取

Profile Facts 提取器从对话文本中识别用户相关的结构化信息，包括：

• 用户姓名、职位、公司等基本信息
• 用户偏好和习惯
• 技术栈和技能水平
• 过往交互历史摘要

提取后的 facts 会被封装为独立的 MemoryRow，置信度为 0.6，source_episode_ids 指向原始 Episode。

TTL 计算

每种记忆类型都有预设的存活时间（TTL），通过 compute_valid_to() 函数计算：

def compute_valid_to(kind: str, valid_from: datetime, ttl: dict) -> datetime | None:
    """根据记忆类型计算过期时间"""
    # 返回 valid_from + 对应类型的 TTL

LLM 编译器

概述

LLM 编译器使用大语言模型进行深度语义分析，能够：

• 理解对话意图和情感
• 提取隐含的关系和依赖
• 生成更准确的摘要和总结
• 识别实体和事件之间的关联

配置要求

llm:
  apiKey: sk-...  # 必须配置
  # 可选配置项
  model: gpt-4    # 指定模型
  temperature: 0.3

提示词策略

LLM 编译器使用精心设计的提示词模板，引导模型生成符合 Statewave 数据模型的记忆结构。提示词设计考虑：

• 记忆类型的严格分类
• 置信度评分的指导
• 时间范围的有效期设定
• 避免幻觉和重复提取

记忆数据结构

MemoryRow 字段说明

记忆状态流转

stateDiagram-v2
    [*] --> active: 新建记忆
    active --> superseded: 被新记忆替代
    active --> redacted: 策略过滤
    active --> inactive: 过期
    superseded --> [*]
    redacted --> [*]
    inactive --> [*]

冲突检测与消解

冲突类型

消解策略

资料来源：server/services/conflicts.py:1-50

编译任务管理

同步编译

适用于小批量 Episodes 的实时编译：

result = await compile_job.execute(episode_ids)

持久化任务

对于大批量编译需求，系统提供持久化任务支持：

job = await compile_job_durable.create(
    episode_ids=episode_ids,
    mode="llm",
    priority="normal"
)

重试机制

编译任务失败后自动重试，默认策略：

• 最大重试次数：3
• 重试间隔：指数退避（1s, 4s, 16s）
• 永久失败：记录错误日志，标记任务状态

配置参考

环境变量配置

Helm Chart 配置

compiler:
  type: llm  # 或 heuristic
  timeout: 300  # 编译超时时间（秒）
  batchSize: 50  # 每批处理 Episodes 数

最佳实践

编译模式选择指南

flowchart TD
    A[选择编译模式] --> B{有 LLM 需求?}
    B -->|是| C[生产环境]
    B -->|否| D{需要深度语义理解?}
    D -->|是| C
    D -->|否| E[开发/演示环境]
    C --> F[LLM 编译器]
    E --> G[Heuristic 编译器]

性能优化建议

1. 批量摄入：使用 POST /v1/episodes/batch 批量摄入，减少编译次数
2. 合理选择模式：非必要场景使用 Heuristic 模式降低延迟
3. 配置 TTL：根据业务需求调整各记忆类型的 TTL，减少存储压力
4. 监控编译状态：通过 API 监控编译任务的执行情况

调试编译问题

# 检查编译状态
curl http://localhost:8100/v1/memories/search?subject_id=xxx

# 查看编译任务详情
curl http://localhost:8100/admin/jobs?status=failed

相关文档

• 架构概述
• 编译器模式对比
• 隐私与数据流
• API v1 契约

概述

上下文检索与排名（Context Retrieval and Ranking）是 Statewave 的核心子系统，负责从海量的记忆（Memory）和事件（Episode）数据中筛选出最相关的内容，并将其组装成符合令牌预算限制的上下文包，供下游 AI 代理使用。

该系统的设计目标包括：

• 相关性优先：基于语义相似度、类型匹配、时间衰减等多维度评分机制
• 令牌约束：自动裁剪结果以满足 STATEWAVE_DEFAULT_MAX_CONTEXT_TOKENS 配置的令牌预算
• 幂等性：同一查询在相同数据状态下产生一致的上下文输出
• 多租户隔离：通过 X-Tenant-ID header 确保跨租户数据的严格隔离

资料来源：server/services/context.py:1-50

核心概念

上下文项（Context Item）

在 Statewave 中，所有可被纳入上下文的实体都被抽象为 Context Item。系统支持两类主要实体：

每项实体都关联一个 评分（Score），用于排名决策。

评分项（ScoredItem）

ScoredItem 是上下文组装过程中的内部数据结构，用于封装已评分的条目：

class _ScoredItem:
    """An item (memory or episode) with its computed relevance score."""

    __slots__ = ("score", "kind", "memory_row", "episode_row", "text", "section")

资料来源：server/services/context.py:50-68

系统架构

graph TD
    subgraph "上下文检索与排名系统"
        A[POST /v1/context] --> B[Query Parser]
        B --> C[语义检索模块]
        C --> D[混合评分引擎]
        D --> E[Token Budget Controller]
        E --> F[上下文组装器]
        F --> G[返回 Context Bundle]
    end

    subgraph "数据存储层"
        H[(Memory Table)]
        I[(Episode Table)]
        J[(Embedding Cache)]
    end

    C --> H
    C --> I
    C --> J

检索流程

1. 查询解析与参数验证

客户端通过 POST /v1/context 端点提交上下文请求，请求参数包括：

系统首先验证租户隔离（STATEWAVE_TENANT_HEADER），确保查询仅访问授权数据。

2. 语义检索

系统通过嵌入服务（Embedding Service）将查询文本转换为向量表示：

# 嵌入服务配置
embedding_provider = "litellm"  # 或 "stub" 用于演示模式

嵌入向量随后用于在向量数据库中执行相似度搜索。Statewave 支持两种嵌入模式：

资料来源：server/services/embeddings/litellm.py:1-30

3. 查询缓存

为降低嵌入 API 调用成本，系统实现了查询缓存机制：

# 缓存键生成逻辑
cache_key = hashlib.sha256(
    f"{query_text}:{k}:{include_episodes}".encode()
).hexdigest()

缓存有效期由 STATEWAVE_EMBEDDING_CACHE_TTL 配置控制。

资料来源：server/services/embeddings/query_cache.py:1-40

评分与排名机制

混合评分算法

系统在多个维度上计算相关性分数：

最终分数计算公式：

final_score = 0.4 × semantic_score + 0.2 × type_match + 0.2 × time_decay + 0.2 × confidence

排名策略

1. Primary Sort：按 final_score 降序排列
2. Secondary Sort：相同分数时，按 created_at 降序排列（优先新条目）
3. Diversity Boost：对类型多样的结果给予小幅加分，避免结果过度集中

Memory 类型权重

不同类型的记忆在检索时享有不同的基础权重：

资料来源：server/services/context.py:70-120

Token 预算控制

预算分配策略

系统采用 分层预算分配 策略：

graph LR
    A[总预算<br/>max_tokens] --> B[Memory 层<br/>60%]
    A --> C[Episode 层<br/>30%]
    A --> D[元数据层<br/>10%]

裁剪算法

当候选条目总 token 数超过预算时，系统按以下顺序裁剪：

1. 移除分数最低的 Episode 条目
2. 合并低置信度的 Memory 摘要
3. 截断单个 Memory 的 content 字段至 max_tokens_per_item 限制
4. 若仍超预算，返回部分结果并设置 truncated: true 标志

配置参数

API 端点

POST /v1/context

功能：组装并返回上下文包

请求示例：

curl -X POST http://localhost:8100/v1/context \
  -H "Content-Type: application/json" \
  -H "X-Tenant-ID: tenant-123" \
  -d '{
    "subject_id": "user-001",
    "query": "最近的产品需求讨论",
    "k": 10,
    "max_tokens": 4000
  }'

响应结构：

GET /v1/timeline

功能：获取主题的时间线视图

查询参数：

资料来源：server/api/context.py:1-80

与 SLA/健康检查的集成

健康评分上下文

上下文检索系统与健康服务（Health Service）共享数据访问层：

# 健康评分的上下文因子
health_factors = {
    "recent_memories": memory_count_last_7d,
    "resolution_rate": resolutions.resolved / resolutions.total,
    "avg_response_time": sla_metrics.avg_response_time,
    "sla_breaches": sla_metrics.breach_count
}

系统通过 /v1/subjects/{id}/health 端点暴露综合健康评分，该评分依赖上下文检索获取近期记忆和 SLA 指标。

资料来源：server/services/health.py:1-60

SLA 指标上下文

SLA 服务在计算响应时间和解决时间时，会向上下文检索模块请求相关 Episode 数据：

# SLA 计算的数据依赖链
timeline_episodes → context_retrieval → 
sla_metrics → health_score

资料来源：server/services/sla.py:1-80

性能优化

向量检索优化

1. 批处理嵌入：将多个短查询合并为单次 API 调用
2. HNSW 索引：使用 pgvector 的 HNSW 索引加速近似最近邻搜索
3. 结果缓存：语义相似的结果在短时间窗口内被缓存

缓存策略

错误处理

配置参考

完整的上下文检索相关配置项：

# 令牌预算
STATEWAVE_DEFAULT_MAX_CONTEXT_TOKENS=4000

# 嵌入服务
STATEWAVE_EMBEDDING_PROVIDER=litellm
STATEWAVE_EMBEDDING_MODEL=text-embedding-3-small
STATEWAVE_EMBEDDING_CACHE_TTL=3600

# 多租户
STATEWAVE_TENANT_HEADER=X-Tenant-ID
STATEWAVE_REQUIRE_TENANT=false

扩展阅读

• API v1 契约规范
• 排名算法详解
• 隐私与数据流

概览

Statewave API 基于 FastAPI 构建，提供 RESTful 接口用于管理 Subject（主体）、Episode（事件）、Memory（记忆）、Resolution（解决方案） 等核心实体。API 支持多租户隔离、速率限制和可配置的上下文组装策略。

基础信息

可用文档界面

概述

Statewave 的服务层是业务逻辑的核心载体，负责处理记忆编译、上下文组装、快照管理、内存包操作、交接（handoff）处理、Webhook 通知、速率限制等关键功能。服务层位于 API 路由层与数据库持久层之间，封装了所有复杂的数据处理流程，确保 API 端点保持简洁。

服务层采用异步架构设计，充分利用 Python 的 asyncio 特性处理 I/O 密集型操作。所有服务模块均支持多租户隔离，通过 tenant_id 参数实现数据层面的访问控制。

概述

Statewave 采用 PostgreSQL 作为主数据库，通过 asyncpg 异步驱动实现高性能数据访问。数据库架构围绕三个核心实体构建：Episode（事件）、Memory（记忆） 和 Subject（主体），支持多租户隔离、快照恢复和时间线查询等高级功能。

资料来源：DOCKER.md:8

核心数据模型

Entity-Relationship 概览

erDiagram
    Subject ||--o{ Episode : contains
    Subject ||--o{ Memory : contains
    Episode ||--o{ Memory : generates
    Subject ||--o{ Resolution : tracks
    Subject ||--o{ SubjectSnapshot : snapshots
    Memory }o--o{ Memory : supersedes

主要数据表

资料来源：server/services/snapshots.py:1-100

表结构详解

EpisodeRow（事件表）

事件是 Statewave 的基础数据单元，代表主体（Subject）的任意活动记录。

# 事件创建示例（server/services/snapshots.py:51-65）
EpisodeRow(
    id=uuid.uuid4(),
    subject_id=snapshot_subject,
    session_id=ep.session_id,
    tenant_id=ep.tenant_id,
    source=ep.source,
    type=ep.type,
    payload=ep.payload,
    metadata_=ep.metadata_,
    provenance=ep.provenance,
    occurred_at=ep.occurred_at,
    created_at=ep.created_at,
)

资料来源：server/services/snapshots.py:51-65

MemoryRow（记忆表）

记忆是从事件编译的提炼数据，支持多种类型和有效期管理。

# 记忆创建示例（server/services/compilers/heuristic.py:1-50）
MemoryRow(
    id=uuid.uuid4(),
    subject_id=ep.subject_id,
    kind="episode_summary",
    content=text[:500],
    summary=text[:200],
    confidence=0.8,
    valid_from=ep_valid_from,
    valid_to=compute_valid_to("episode_summary", ep_valid_from, ttl),
    source_episode_ids=[ep.id],
    metadata_={},
    status="active",
)

资料来源：server/services/compilers/heuristic.py:1-50

SubjectSnapshotRow（快照表）

快照用于备份和恢复主体在特定时间点的完整状态。

# 快照创建示例（server/services/snapshots.py:85-95）
SubjectSnapshotRow(
    name=name,
    version=version,
    source_subject_id=snapshot_subject,
    episode_count=len(eps),
    memory_count=len(mems),
    metadata_=metadata or {},
)

资料来源：server/services/snapshots.py:85-95

异步数据库访问模式

引擎与会话管理

Statewave 使用 SQLAlchemy 2.0 异步引擎，结合 asyncpg 驱动实现非阻塞 IO。

# 异步会话获取模式（server/api/timeline.py:100-120）
from server.db import engine as engine_module

async with engine_module.get_session_factory()() as session:
    base = select(MemoryRow)
    # ... 查询操作

查询构建示例

# 复杂查询：查找引用特定事件的记忆（server/api/timeline.py:130-150）
base = select(MemoryRow).where(
    MemoryRow.tenant_id == tenant_id,
    MemoryRow.subject_id == subject_id,
    func.any_(MemoryRow.source_episode_ids) == episode_uuid
)

资料来源：server/api/timeline.py:100-150

仓储层设计

Repository 模式

数据访问通过 Repository 模式封装，提供统一的 CRUD 操作接口。

graph TD
    A[API Layer] --> B[Service Layer]
    B --> C[Repository Layer]
    C --> D[(PostgreSQL)]
    
    E[Memory Repository] --> C
    F[Episode Repository] --> C
    G[Resolution Repository] --> C

核心仓储操作

资料来源：server/db/repositories.py

多租户数据隔离

隔离策略

Statewave 采用应用层多租户隔离，通过 tenant_id 字段实现数据分区。

graph LR
    A[Request] --> B{X-Tenant-ID Header}
    B -->|有租户ID| C[按 tenant_id 过滤]
    B -->|无租户ID| D[拒绝请求]
    
    C --> E[WHERE tenant_id = ?]

环境配置

# 租户过滤查询示例
base = select(MemoryRow).where(
    MemoryRow.tenant_id == tenant_id,
    MemoryRow.subject_id == subject_id
)

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

时间线与快照管理

时间线查询

支持按时间顺序检索主体的事件和记忆，支持事件合并展示。

# 时间线响应模型（server/api/admin.py:50-80）
class SessionTimelineResponse(BaseModel):
    session_id: str
    status: str
    first_message_at: str | None
    resolved_at: str | None
    episode_count: int
    events: list[TimelineEvent]

快照恢复

快照恢复支持时间偏移（Time Shift），确保恢复后时间戳的连续性。

# 时间偏移处理（server/services/snapshots.py:130-160）
time_shift = target_created_at - snapshot_created_at

# 记忆时间戳偏移
created_at=mem_created + time_shift,
updated_at=mem_updated + time_shift,
valid_from=mem_valid_from + time_shift if mem_valid_from else None,

资料来源：server/services/snapshots.py:130-160

索引与性能优化

推荐索引策略

JSONB 字段优化

# JSONB 查询示例
query = select(MemoryRow).where(
    MemoryRow.payload['event_type'].astext == 'message'
)

迁移与版本管理

Alembic 集成

Statewave 使用 Alembic 进行数据库迁移管理。

# Helm 安装时的预安装 Job
alembic upgrade head

迁移执行时机

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

配置参考

数据库连接配置

# Docker Compose 配置示例
environment:
  STATEWAVE_DATABASE_URL: postgresql+asyncpg://statewave:statewave@db:5432/statewave

测试环境配置

# 创建测试数据库
PGPASSWORD=statewave createdb -h localhost -U statewave statewave_test

# 集成测试执行
pytest tests/integration/ -v

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

最佳实践

数据建模建议

1. 事件不可变性：事件一旦写入不应修改，通过新事件表达状态变更
2. 记忆有效期：使用 valid_from/valid_to 管理记忆时效
3. 源事件追踪：始终维护 source_episode_ids 引用链
4. 租户隔离：所有查询必须包含 tenant_id 过滤条件

性能注意事项

1. 避免全表扫描，使用索引覆盖查询
2. 批量操作使用 BATCH_SIZE = 50 分批处理
3. 大型导入使用快照机制而非实时编译

Pitfall Log / 踩坑日志

项目：smaramwbc/statewave

摘要：发现 6 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：能力坑 - 能力判断依赖假设。

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

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

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

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

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

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

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

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

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

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

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

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