TAOctx

面向长期运行 Agent 的上下文智能编排中间层（Agent Context Runtime）。

让 Agent 记住重要的，而不是携带全部的。

TAOctx 不是完整 Agent 框架，也不是可替换的「Memory 插件」叙事。它放在 Agent 运行时与主模型之间：以 TurnRecord（轮次）为唯一记忆原子，把跨会话历史 外置存储；每次请求按当前问题 检索 → 打分 → 问题强相关压缩 → 拼装，在有限 Context / KV-cache 预算内注入最有价值的证据。

一句话：

在固定 Token 预算下，持续为 Agent 构建问题相关、跨会话可用的上下文。

English README · 文档索引 · 环境变量

要解决的问题

真实痛点往往不是「Agent 不会记」，而是：

• 历史越长，有效信息密度越低（context rot），长任务越跑越飘；
• 全量拼接超窗口、抬高 TTFT，跨会话噪声抢走注意力；
• 需要的是 何时取什么进 Context、何时压缩、何时跨会话召回，而不是无限堆历史。

TAOctx 采用「Turn 外置存储 + 按需检索 + 问题强相关压缩」：当前会话工作区由 调用方传入（原文保留）；跨会话证据从外部记忆体召回并压缩后注入 <retrieved_memory>。不替换 Claude Code / Codex / OpenClaw / 自研 Agent，只增强 其 Context 能力。

系统架构

架构自上而下分为接入层、应用编排层、记忆状态层、上下文计算层与基础设施层；作为 Context Runtime，核心引擎完成 Retrieve → Score → Compress → Assemble 闭环。 部署在昇腾 NPU上运行，也支持 NVIDIA CUDA；主模型为任意 OpenAI 兼容 /v1 服务。

四项核心技术

技术	要点	差异化价值
Turn 原子记忆	以 Agent 每轮 TAO 交互为最小单元，封装为 TurnRecord 完整持久化	保障块级原子性，避免无限长历史切块时的语义断裂
自适应压缩比	结合重要性与问题关联度，为每块记忆动态输出 compression_ratio	在固定 Token 预算内精细分配保留比例
问题强相关压缩	语义相似度 + 词项重叠逐块打分，高相关保留证据链，低相关激进压缩	Accuracy 相对无压缩 baseline 提升约 8.7%
小模型高效压缩	基于 BEAVER 改进的块级压缩器（Qwen3-4B），可在昇腾 NPU 或 CUDA 上运行，与主模型解耦	prepare p50 从 3.979s 降到 2.603s，Prompt Hash 对齐

四项能力形成「存得细 → 捞得准 → 压得狠 → 算得快」完整链路。

记忆预算策略（MBP） — baseline、balanced、low。推荐在 taoctx.toml 写 profile = "balanced"，或 taoctx-serve --profile balanced（环境变量 TAOMEM_MBP 仍然可用）。详见 docs/policy.md。

适用场景

按收益从高到低：

1. 跨会话记忆召回 —— 用户隔天、隔周再问，Agent 仍能拉回关键历史证据，不靠把历史 全量拼进 prompt。
2. 长任务接近或超出窗口 —— 比滑窗、全量摘要更稳地保住与当前问题相关的信息。
3. 工具调用密集任务 —— tool observation 堆成山时按相关度压掉冗余段，避免日志淹没答案。
4. 主模型很贵 —— 把贵模型的非缓存输入压下来，预处理交给小模型 / NPU，争取净成本下降。
5. 多框架统一接入 —— OpenAI 兼容入口挂在 OpenClaw / LangGraph / 自研 Agent 前面， 统一上下文策略。

不适合、不建议强推的场景：

• 单轮短问短答，基本不超窗、也没有跨会话需求；
• 每一跳都能稳定命中 KV cache、上下文不膨胀的 Turn 内循环；
• 对时延极端敏感、不接受任何 prepare 开销的路径。

前两类接进来在默认阈值下等于直通（见什么时候真正压缩），不会变差但也 没收益；第三类建议直接不接入。

安装

需要 Python 3.10+。TAOctx 是 Python 包，先 install 才能 import taoctx 与使用 taoctx-serve：

git clone https://gitcode.com/aisa-ai/TAOctx.git
cd TAOctx
pip install -e .

安装框架依赖（检索、压缩编排、taoctx-serve、token 计数）。随后按硬件安装 PyTorch，并下载模型权重：

• 昇腾：加载 CANN 后安装配套 torch + torch_npu，压缩设备设为 npu / npu:0
• CUDA：pip install -e ".[torch]"，压缩设备设为 cuda:0 / gpu
• 权重：见 docs/models.md（HF / ModelScope 链接与命令）

完整步骤、对接示例与验收：docs/getting_started.md
按需改参：docs/tuning.md

跑测试加 dev，跑 LangGraph / LangChain 示例加 examples，用 Milvus 加 milvus。

延伸文档：配置（TAOMEM_*） · 昇腾运行时 · 集成方式

使用方式

上下文问题只有两种来源，需要的机制不同，所以入口也分两个：

• 这一次请求本身就太长（贴进来的文档、工具吐出的长输出、一整段 transcript）。没有 什么需要「记住」，只是要把这段文本压进预算 → 场景一，不涉及存储与检索。
• 证据根本不在这次请求里（昨天定的结论、三次会话前报的 bug）。必须按轮次存下来、 针对当前问题召回、压缩后注入 → 场景二。

场景	能力	入口
一、只做整块压缩	把一段长 prompt 按预算压小；不写库、不检索、无会话状态	enhance_beaver_result / compress_prompt
二、带记忆管理	轮次写回、按问题检索、压缩后注入 <retrieved_memory>	AgentMemoryGateway / LongContextPipeline

场景二有两种部署形态：进程内 SDK，或 taoctx-serve（OpenAI 兼容 HTTP， 给只认 OpenAI 协议的客户端）。taoctx-serve 只是把 SDK 包成 HTTP，不是唯一用法。

配置：taoctx.toml（从 configs/taoctx.example.toml 复制）或 TAOMEM_* 环境变量 （前缀沿用历史名称）。昇腾本机可先：

source scripts/env_local_ascend.sh   # CANN + 本地权重 + beaver_select/balanced

详见 configuration.md、 integrations.md、examples/README.md。

什么时候真正压缩

接入后不是每一轮都付压缩代价。每次请求先按 token 估算决定跑到哪一步：

这次请求	检索	压缩	结果
新对话问历史（请求很短，库里有跨会话证据）	执行	证据总量不到 TAOMEM_COMPRESS_MIN_TOKENS（默认 8192）时不执行	证据原文注入，不引入压缩延迟
长会话 / 召回证据很多	执行	执行	按问题相关度差异化压缩后注入
库里没有可召回的跨会话证据	执行但为空	跳过	等价于直通

检索本身是毫秒级，所以默认始终执行——否则「新对话问三天前的结论」这类请求就拿不到证据。 压缩要加载小模型、直接影响 TTFT，因此只在上下文真的胀起来时才启动。若连检索也想按体量 跳过，设 TAOMEM_RETRIEVE_MIN_TOKENS（默认 0，即不跳过）。判定结果随 taoctx.stage_decision 一起返回，可直接观测。

对时延有硬要求的路径可再设 TAOMEM_PREPARE_BUDGET_MS：压缩超出剩余预算就放弃，改注入召回 原文并打一条 WARNING，compression_skip_reason=prepare_budget_exceeded。注意它只保证调用方 不再等待——被放弃的压缩仍会在后台跑完，所以这是兜尾延迟的手段，不是限流。

这也是适用场景里「不超窗、无跨会话需求」的情况装上不会变差的原因：阈值以下 根本不进压缩路径。

场景一：只做整块压缩

from taoctx.compression.beaver.prompt import compress_prompt

result = compress_prompt(context=long_text, query=question, target_ratio=0.3)
print(result.compressed_text, result.actual_ratio)

compress_prompt 需要已安装 torch 与 TAOMEM_BEAVER_MODEL_PATH。 只用装填步骤（enhance_beaver_result）无额外依赖、不加载压缩模型（不需要 NPU / GPU）：

python examples/compress_block.py               # 仅装填，不加载模型
python examples/compress_block.py --with-model  # 完整整块压缩

场景二 a：Python SDK（进程内）

from taoctx import AgentMemoryGateway

gateway = AgentMemoryGateway.from_env()
# prepared = await gateway.prepare_openai_chat(request=..., session_id=...)
# result = await gateway.complete_openai_chat(request=..., session_id=..., main_llm=...)

只跑上下文拼装 / 记忆注入（不需要主模型，检索与压缩都是真实执行）：

export TAOMEM_BEAVER_MODEL_PATH=/path/to/Qwen3-4B   # 见 docs/models.md
TAOMEM_VECTOR_BACKEND=sqlite TAOMEM_SQLITE_PATH=./taoctx_demo.db \
  TAOMEM_COMPRESSOR=beaver_select TAOMEM_BEAVER_DEVICE=npu:0 \
  python examples/sdk_gateway.py

场景二 b：HTTP 代理（taoctx-serve）

cp configs/taoctx.example.toml taoctx.toml   # 改 [main] / [embed] / 压缩
taoctx-serve --port 8080 --profile balanced

• GET /health — 健康检查
• POST /v1/chat/completions — 注入记忆后转发主模型（SSE）
• 会话：请求头 X-TAOMEM-Session-Id（或 metadata.session_id）

python examples/openai_compatible_client.py --health-only
python examples/openai_compatible_client.py   # 需 serve + 主模型

主流 Agent 示例

Agent / 栈	接法	可运行脚本
自研 Python Agent	SDK AgentMemoryGateway	examples/sdk_gateway.py
任意 OpenAI base_url 客户端	指向 taoctx-serve	examples/openai_compatible_client.py
LangGraph	节点内 prepare_prompt 再调主模型	pip install -e ".[examples]" → examples/langgraph_agent.py
LangChain	Runnable 接在 ChatModel 前	examples/langchain_runnable.py

只跑上下文路径（不调用主模型）：

pip install -e ".[examples]"
TAOMEM_COMPRESSOR=beaver_select TAOMEM_BEAVER_MODEL_PATH=/path/to/Qwen3-4B \
  python examples/langgraph_agent.py --prepare-only
TAOMEM_COMPRESSOR=beaver_select TAOMEM_BEAVER_MODEL_PATH=/path/to/Qwen3-4B \
  python examples/langchain_runnable.py --prepare-only

完整一轮（需 TAOMEM_MAIN_* 或 toml [main]）：

TAOMEM_MAIN_BASE_URL=http://127.0.0.1:8000/v1 TAOMEM_MAIN_MODEL=qwen3-32b \
  python examples/langgraph_agent.py

昇腾 910C 部署

• 昇腾运行时说明
• 模型权重下载

主模型经 vLLM-Ascend 以 OpenAI 兼容 /v1 暴露；在 taoctx.toml 的 [main].base_url（或 TAOMEM_MAIN_BASE_URL）指向该服务即可。

实验结果（昇腾 910C）

在昇腾 910C环境、Qwen3-32B FP16 主模型 + Qwen3-4B TAOctx 压缩器上完成 LongMemEval multi-session 的端到端评测。同一 pipeline，对照为无压缩 baseline 与 TAOctx（r=0.3）。

方案	Accuracy	Prepare p50	主模型 TTFT p50	端到端首词 TTFT p50	总 E2E p50	平均 Prompt Tokens
baseline	46%	0.22s	3.02s	3.25s	7.36s	24,123
TAOctx（r=0.3）	50%	1.04s	0.42s	1.46s	4.14s	7,399

相对 baseline：准确率由 46% 提升至 50%（相对优化约 8.7%），端到端首词 TTFT 由 3.25s 降至 1.46s（优化约 55%）。

TAOctx 压缩 prepare 加速

NPU 上的 TAOctx 压缩路径通过批量 HSP、embedding-only 加载、tokenizer 元数据缓存、 CPU tokenizer 与 NPU 执行流水线、Query tensor 直传等方式降低 prepare 开销。 验证 profile 中，taomem_prepare_ms p50 从 3.979s 降到 2.603s， 并保持 Prompt 输出与原路径对齐。实现细节见 TAOctx 压缩 NPU prepare 优化。

昇腾原生执行路径

本项目在昇腾 910C 上完成全链路验证：主模型推理、记忆压缩与向量检索可运行于 Ascend NPU 算力环境（亦支持 CPU 回退与通用 OpenAI 兼容后端）。

能力	说明
NPU 卸载压缩	Qwen3-4B 块级压缩在 NPU 上执行；算法侧决定「压什么」，小模型侧专注「怎么压」
张量化 token 打分	ScoreBackend 内核级 batch 打分 + NPU sidecar（LongLLMLingua 对照实现也走这条路径）
统一 NPU 后端	CompressionBackend / ScoreBackend 面向昇腾执行（CANN / ACL / Graph Engine）

详见 docs/ascend_runtime.md。

模块职责

模块	职责
gateway.py	Agent 统一入口（上下文拼装 / 生成 / 写回）
session_bridge.py	OpenAI messages ↔ 管线
memory/	Turn 持久化（SQLite / Milvus）
retrieval/	跨会话混合检索
scoring/	重要性与压缩比打分（含 turn_utility）
blocking/ + compression/ + assembly/	上下文重建
policy/	记忆预算策略（MBP）
pipeline.py	管线编排

发展规划

原子单位始终是 TurnRecord。经验 / 状态链等是 可选进阶能力，不替代 Turn。

阶段	目标	重点
现在（核心）	长任务 Context 更稳、更准	Turn 检索 + 问题相关细节保留压缩；跨会话历史可靠写回与注入；默认对齐 balanced / hybrid 等已验证配置
规划中	可观测性与集成	暴露 Context / 预算指标；完善 OpenClaw / LangGraph 接入；补充任务成功率等评测指标
进阶（可选）	状态与经验层	在 Turn 之上叠加任务状态链、Experience 摘要等；任务感知检索；多 Agent 共享任务状态

当前范围外：用 Experience 替换 Turn、把 TAOctx 做成完整 Agent 运行时。

文档

• 架构
• 记忆模型
• 检索
• 策略（MBP）
• 上下文重建
• 基准测试
• 环境变量全表

开发与测试

python -m pytest tests/ -q

参见 CONTRIBUTING.md。

压缩内核（BEAVER）

块级压缩器基于 BEAVER（JusperLee/BEAVER， 上游声明 Apache-2.0）改进。其参考实现内置在 src/taoctx/compression/beaver/official/， 同目录附上游许可证文本与我们的修改说明；TAOctx 在其之上加入 Turn 级调度、按预算装填与 昇腾 prepare 路径优化。若用于学术工作，请一并引用 BEAVER 论文 （arXiv:2603.19635）。

许可证

MIT License — 见 LICENSE。第三方组件见 THIRD_PARTY_LICENSES.md。