内容
# gaius
**用于 AI 编程代理的 Ops 内存生命周期管理器**
不是另一个 RAG 聊天机器人内存 —— 一个生产级系统，从 Claude Code、Gemini CLI、Grok 和 Codex 会话中提取事实，通过人工审核，强制执行行为门控，并防止您在凌晨 3 点破坏生产环境。
```
gaius retire # 扫描会话 → 阶段总结
gaius batch # 审查阶段总结
gaius inject # 将上下文注入活动会话
```
---
## 功能描述
每天运行 Claude Code 的工程师会产生大量的机构知识，这些知识在上下文窗口关闭时就会消失。gaius 捕获了它：
1. **提取** — 扫描 Claude Code（和 Gemini CLI）会话 JSONLs，提取具有类型信号的紧凑摘要（知识、模式、错误）
2. **审查** — 在提升事实之前，将摘要排队进行人工审查。坏事实不会悄悄进入语料库。
3. **索引** — 将审查过的事实提升到混合关键词 + 语义 SQLite 数据库（`facts.db`）
4. **注入** — 在任务开始时，检索相关事实并将技能上下文加载到会话中
---
## 基准测试
> 下面的演示是一个**回归/烟雾测试**，而不是质量评分：
> 它确认检索在全新克隆上仍然有效。完美的分数证明了在手建的 27 个事实的语料库上，管道运行正常，但仅此而已。实际质量通过外部的第三方基准测试（参见*外部评估*）来衡量，而不是通过我们自己评分的数字。
`bench_inject.py` 从 `benchmarks/demo_corpus/` 构建一个临时 SQLite 语料库：
```
$ python3 benchmarks/bench_inject.py
gaius 注入基准测试（25 个查询，捆绑演示语料库）
════════════════════════════════════════════════════════════
召回率： 25/25（100%） 回归检查，不是质量评分
精确警告： 3/25
语料库： 27 个演示事实 （临时 SQLite，无守护进程，约 0.08 秒/查询）
语义模式（嵌入守护进程，真实语料库）：
冷启动： ~7 秒 （第一个查询，模型加载）
守护进程热启动： ~8 毫秒 （Unix 套接字，模型保持在内存中）
存储： sqlite-vec（384 维，all-MiniLM-L6-v2）+ BM25 在单个 SQLite 文件中
无 API 密钥，无云，完全离线运行。
```
---
## 外部评估（LongMemEval-S）
上面的演示只证明了管道在运行。为了获得**无偏见**的衡量标准，gaius 的检索在 [LongMemEval-S](https://github.com/xiaowu0162/LongMemEval)（ICLR 2025）上得分：一个第三方基准测试，其 500 个问题，约 48 个会话的 haystacks 和黄金标签，gaius 没有参与选择。可重现（下载数据集后执行脚本头部，然后）：
```
$ python3 benchmarks/bench_longmemeval.py
LongMemEval-S -- gaius 检索（all-MiniLM-L6-v2 + sqlite-vec），500 个问题
MRR： 0.825
召回率@1 46.1% 召回率@5 85.7%
召回率@10 92.7% 任意命中@10 96.8%
最弱： 单会话用户 88.6%，时间推理 90.8%
最强： 单会话助手 98.2%
```
诚实的阅读：gaius 在**微型/离线嵌入层级**中具有竞争力，但不是 SOTA。召回率@10 约 93% 低于第三方相同模型（all-MiniLM-L6-v2）会话级评估报告的约 96-99%（协议不同），而官方大模型基线（Stella 1.5B，GTE-Qwen2-7B）在更高的成本下得分更高。衡量的是检索引擎，而不是主动注入生命周期。
---
## 真正的新颖之处
| 功能 | 描述 |
|---------|-------------|
| **人工审查门控** | `retire → 阶段 → 审查 → 提升`。坏事实无法悄悄进入语料库。 |
| **多代理验证** | 多个 AI 代理（Claude + Gemini）确认的事实获得 1.5 倍的分数提升。跨模型验证以获得更高的置信度。 |
| **会话类型行为预设** | 根据正在执行的操作加载不同的技能集：运维、交易、安全、代码审查。 |
| **硬强制门控** | 防止动作的内存。`exit:2` 阻止强制推送、实时交易而无需确认、关键资源删除。 |
| **Mnemosyne 健康监测** | 自动内存膨胀预防。行数阈值、误分类审计、分割/修剪提案。 |
| **实时状态注入** | 具有 `kubectl`/`curl` 命令的前置 matter 的领域文件，TTL 缓存。知道当前正在发生什么的内存。 |
| **混合 sqlite-vec 搜索** | 关键词 TF-IDF/BM25 + 单个 SQLite 文件中的语义嵌入。运维基准测试的 100% 召回率@5。 |
| **时间知识图谱** | 具有有效性窗口的实体关系三元组。`gaius kg timeline node` 显示了更改的内容和时间。 |
| **MCP 服务器** | 5 种在会话中访问内存的工具，无需离开 Claude Code。 |
---
## 快速入门
### 安装
```bash
# 选项 1：开发安装（可编辑，从存储库读取）
git clone https://github.com/jkubo/gaius
cd gaius
pip install -e ".[semantic]" # 包括 sentence-transformers + sqlite-vec
# 选项 2：脚本安装（无 pip，使用系统/venv python）
install -m 755 gaius_cli ~/.local/bin/gaius
```
### 初始化
```bash
# 创建配置文件目录
mkdir -p ~/.gaius
# 复制示例配置文件
cp presets/k8s.yaml ~/.gaius/config.yaml # 用于 K8s 集群
# 或：cp presets/default.yaml ~/.gaius/config.yaml
# 编辑以设置您的 sessions_dir 和 domain_dir
$EDITOR ~/.gaius/config.yaml
```
### 首次运行
```bash
# 扫描本地会话并阶段总结。
# 普通 `retire` 也会自动扫描 Grok（~/.grok/sessions）和 Codex（~/.codex/sessions），当这些 CLI 目录存在时； `--format <name>` 限定为一个。
gaius retire
# 审查阶段总结（阅读每个，手动将事实提升到 domain/*.md）
gaius batch # 按顺序打印所有未审查的
gaius next # 一次打印一个
gaius done <uuid> # 在阅读后标记为已审查
# 检查语料库统计
gaius stats
# 在会话开始时注入上下文
gaius inject --task "debug flannel networking" --budget 4000
```
### MCP 服务器（Claude Code）
```bash
# 在 Claude Code 中注册 MCP 服务器
claude mcp add gaius -- python3 -m gaius.mcp_server
# 或如果使用脚本安装：
claude mcp add gaius -- /path/to/gaius/gaius/mcp_server.py
```
在会话中可用的 5 种工具：`gaius_search`、`gaius_kg_query`、`gaius_kg_timeline`、`gaius_stats`、`gaius_fact_add`。
---
## 架构
```
gaius/
├── gaius/
│ ├── _core.py # 所有逻辑（提取、搜索、知识图谱、注入）
│ ├── mcp_server.py # MCP 服务器（5 种工具）
│ ├── __init__.py # 公共 API 接口
│ └── __main__.py # python -m gaius
├── http_adapter.py # FastAPI REST 适配器（可选，用于远程访问）
├── presets/
│ ├── k8s.yaml # Kubernetes 集群的实体模式
│ └── default.yaml # 任何项目的最小默认设置
├── benchmarks/
│ ├── bench_inject.py # 规范注入基准测试（与语料库无关）
│ └── bench_retrieval.py
├── tests/
│ └── test_gaius.py
├── pyproject.toml
└── LICENSE # Apache 2.0
```
**存储**：单个 `~/.gaius/facts.db` SQLite 文件 — 具有 BM25 虚拟表 + sqlite-vec 嵌入索引的事实表。无需外部服务。
**嵌入守护进程**：可选的 systemd 用户服务（`gaius-embed-daemon`）将 `all-MiniLM-L6-v2` 加载到内存中（约 8 毫秒/查询热启动 vs 约 7 秒冷启动）。
---
## 配置
配置文件：`~/.gaius/config.yaml`
```yaml
# 会话目录（Claude Code 项目 JSONLs）
sessions_dir: ~/.claude/projects
# 领域内存目录（您的 *.md 知识文件）
domain_dir: ~/my-memory/domain
# 技能目录（预期的操作指南）
skills_dir: ~/my-memory/skills
# 主要映射 — 代理分组用于跨代理评分
principals:
default: operator
# 实体提取 — 扩展内置的 K8s 基线
entities:
preset: k8s # 使用内置的 K8s 模式；设置为 "none" 以禁用
patterns:
service: '\b(?:my-api|my-worker|my-scheduler)\b'
namespace: '\b(?:prod|staging|dev)\b'
```
参见 `presets/k8s.yaml` 以获取完整的注解示例。
---
## 命令
| 命令 | 描述 |
|---------|-------------|
| `gaius retire` | 扫描本地会话 → 阶段新摘要（自动扫描 Claude/Grok/Codex； `--format` 限定为一个） |
| `gaius record` | 将聊天会话捕获到 gaius JSONL（vLLM，任何 OpenAI 兼容端点） |
| `gaius s3-retire <agent>` | 从 S3 存档的代理会话中退休（rclone） |
| `gaius harvest` | 扫描冷的 Gemini CLI 会话（`.json` 格式） |
| `gaius grok-retire` | 扫描 Grok CLI 会话（~/.grok/sessions/）→ 阶段决策事件 |
| `gaius codex-retire` | 扫描 Codex CLI 部署（~/.codex/sessions/）→ 阶段决策事件 |
| `gaius next` | 打印最旧的未审查摘要 |
| `gaius batch` | 按顺序打印所有未审查摘要 |
| `gaius done <uuid>` | 将摘要标记为已审查 |
| `gaius show` | 列出所有阶段摘要 |
| `gaius stats` | 提取和语料库统计 |
| `gaius inject` | 将排名语料库 + 技能注入活动会话 |
| `gaius kg query <entity>` | 查询知识图谱中的实体 |
| `gaius kg timeline <entity>` | 显示实体的时间变化 |
| `gaius governor` | 跨代理知识差距分析 |
| `gaius embed` | 构建/重建语义嵌入索引 |
| `gaius index` | 重建内存索引 |
| `gaius landscape` | 显示内存系统景观 |
| `gaius skills` | 列出具有分数的可用技能 |
---
## 依赖项
**核心**（无额外依赖）：`pyyaml>=6.0` — 纯 Python，无二进制依赖。
**语义搜索**（`pip install "gaius-memory[semantic]"`）：
- `sentence-transformers>=2.7` — 本地嵌入模型（`all-MiniLM-L6-v2`，384 维）
- `sqlite-vec>=0.1` — SQLite 的向量搜索扩展
**MCP 服务器**（`pip install "gaius-memory[mcp]"`）：
- `mcp[server]>=1.0`
**HTTP 适配器**（`pip install "gaius-memory[http]"`）：
- `fastapi>=0.100`，`uvicorn[standard]>=0.23`
无需 `[semantic]`，gaius 降级为仅关键词 BM25 搜索（无需嵌入）。
---
## 许可证
Apache 2.0 — 参见 [LICENSE](LICENSE)。
