Natural Memory Agent Lab

为 Natural Memory v2（Qwen3.5-4B + 模型内记忆层） 量身定制的测试 Agent 框架。 基座是 Pi Agent Harness（MIT）——用它的 pi-agent-core（带状态管理与事件流的 agent runtime）与 pi-ai（统一多 provider LLM API）， 而不是自己重写一个 agent 循环。

为什么用 Pi 而不是别的

理由	事实
provider 接线是现成的	pi-ai 已有 openai-completions 适配器，provider 配置原生支持 baseUrl；本机 DSH 的 Grok/GPT provider 就是这么接的。不需要改 Pi 的代码
插桩是一等公民	agent.subscribe(event => …) 提供 `agent_start / turn_start / message_* / tool_execution_start
多会话天然支持	stateful agent + 独立 SQLite session backend；本框架每个会话新建 Agent（空上下文），而模型记忆持续存在——这正是被测能力
许可	MIT（© 2025 Mario Zechner），改/fork 无约束

架构：进程与语言双重隔离

┌──────────────────────────────┐         HTTP (OpenAI protocol)        ┌────────────────────────────┐
│ model_server/server.py       │ ◄───────────────────────────────────► │ agent/  (Node + Bun)       │
│ 【LLM conda 环境】            │   /v1/chat/completions (tools)        │  pi-agent-core + pi-ai     │
│  torch 2.9/cu128 原样不动     │   /v1/memory/*  /v1/diagnostics       │  自己的 node_modules       │
│  复用 natural_memory_service  │                                       │  工具 / 场景 / 记录          │
└──────────────────────────────┘                                       └────────────────────────────┘

模型侧留在原有的 LLM conda 环境（torch 2.9 + bitsandbytes 不能被 agent 依赖污染）， Agent 侧是独立的 Node 工程——两边只通过 HTTP 说话。

完整接管 NM2：观测面 + 控制面 + 路由即工具

项目的 natural_memory_service.py 只给了一个单条消息的 /v1/chat 和少量记录管理接口。 要「接管」NM2，agent 需要三样它给不了的东西，本 server 全部补齐：

1. 观测面（NM2 内部其实早就记录了，只是没人暴露）

暴露出来的状态	含义
v2_last_decisions	每轮路由决策的全部字段：need_memory、页/记录 id、页/记录分数、hop_count、hop_trace、stop_reason、confidence、score_margin、evidence_score
text_read_seconds	路由+重排耗时（与解码耗时分离，便于成本归因）
text_prefix_tokens / text_prefix_used	实际注入的前缀 token 数
auto_memory_probability / auto_memory_forget_probability	自动记忆策略头的写入/遗忘概率
context_compaction	KV 自动压缩报告
v2_no_evidence	路由器是否判定无证据

每次调用后 server 会 snapshot 这些状态并保留逐轮 trace 历史（GET /v1/nm2/trace）。

2. 控制面（15 个可运行时改写的旋钮 + 治理操作 + 用户隔离）

类别	接口
旋钮读写	GET/POST /v1/nm2/config —— top_k_pages top_k_records max_hops hot_pages read_threshold write_threshold min_read_margin require_evidence auto_memory_threshold auto_forget_threshold gpu_cache_records gpu_cache_tokens context_chunk_tokens kv_budget_tokens kv_keep_recent_tokens（白名单 + 类型/范围校验，拒绝非法键）
记录治理	POST /v1/nm2/write（可信显式写入，带 entity/attribute/value/importance/confidence）、/correct（生成新版本）、/retract、/approve（quarantine → active，此前模型没有公开包装）、GET /v1/nm2/records、/audit、/export
会话/用户隔离	POST /v1/nm2/session —— save/load/list/delete/reset，走 MemoryOSV2.export_payload() / from_payload()，完整搬移记录、页、quarantine、检索阈值与 KV 预算（阈值随会话走，不随进程走）
KV 预算	POST /v1/nm2/compact —— 把长上下文压缩成 NM2 记录并返回热窗口报告
请求级覆盖	chat 请求体里的 nm2: { top_k_pages, top_k_records, max_hops, read_threshold, ... }，只在该次请求内生效（进入前保存旧值、退出时恢复）

3. 路由即工具：POST /v1/nm2/probe

只跑「粗索引 → 候选页 → 页内重排 → Top-K」这条有界路径，不生成任何 token，直接返回： 决策（need/hop/stop_reason/margin/evidence）、命中的记录及其分数、以及 encode_seconds / route_seconds 分解。 这让「这里记忆会给我什么」变成 agent 可调用、harness 可评分的一等操作。

Agent 侧对应的工具

工具	action	用途
nm2_read	probe / search / trace / audit / stats	探测路由、检索记录、回看逐轮决策与延迟
nm2_write	write / correct / retract / approve	记忆治理
nm2_admin	config_get / config_set / compact / session / reset	调参、压缩、切换用户

只用三个工具而不是二十个：4B 模型对「少量工具 + 明确 action 枚举」的可靠性远高于长工具表。

仍然保留的（原有能力，未删）

• 用模型自己的 chat template 渲染完整消息列表，原生支持 Qwen 的 <tool_call> / <tool_response>，是真正的 function calling；
• 保持项目记忆语义：用户轮触发写入、生成只读、reset token 生效、写入自动持久化；
• memory_mode = on | read_only | off，即无记忆对照组的开关。

Agent 侧做了什么

文件	作用
src/provider.ts	把本机模型注册成 pi-ai 的一个 provider（createProvider + OpenAICompletions）
src/memory.ts	模型 server 的记忆/诊断客户端 + MemoryRecorder（逐轮记录，忠实于「每次用户消息 = 一条记录」而不是内部循环次数）
src/tools.ts	工具集：run_shell / read_file / write_file / http_get / notes / memory_admin
src/agent.ts	createTestAgent()：Pi Agent + 事件插桩 + ask() 一次用户往返
src/run_scenario.ts	多会话场景编排、双组（记忆开/关）、断言评分、写出 JSONL 轨迹与 summary.json
scenarios/*.json	场景套件

两个刻意的设计

1. notes 工具（文件便签）是故意的。 对照组若没有任何外部记忆，比较的就不是「模型内记忆 vs 无记忆」而是 「有记忆 vs 什么都没有」。两组都给同一份文件便签，才能真正隔离被测变量。
2. memory_admin 把记忆治理变成可评测的 Agent 能力（列出/审计/撤回），而不是看不见的旁路。

场景套件

场景	考的是什么
cross_session_recall	会话 1 写入 → 会话 2/3（全新上下文、无历史文本）询问
conflict_update	同属性旧值→新值，跨会话必须返回新值且旧值不得活跃
unknown_abstention	从未提及的属性必须明确说不知道，不许编造或硬套相似记忆
multi_hop_chain	项目→负责人→工号，两跳串联
forget_retraction	明确要求遗忘后，跨会话不得再使用该事实

运行

# 1) 启动模型 server（在 LLM conda 环境，占用 GPU）
$env:PYTHONPATH = 'H:\Memory'
& C:\Users\Administrator\miniconda3\envs\LLM\python.exe H:\Memory\agent_lab\model_server\server.py `
    --model-path qwen3_5_4b_natural_memory_v2 --port 8766

# 2) 安装 agent 侧依赖（独立于模型环境）
cd H:\Memory\agent_lab\agent
bun install
bun run typecheck

# 3) 跑单个场景（双组对照）
$env:NATURAL_MEMORY_API_KEY = 'local'
bun run scenario --scenario scenarios/cross_session_recall.json --arm both

# 4) 跑全套
bun run suite

产物：runs/<timestamp>/<scenario>.<arm>.jsonl（逐轮轨迹：用户消息、助手回答、工具调用与结果、记忆诊断） 与 runs/<timestamp>/summary.json（每场景每组的断言通过率、活跃记录数、每轮耗时）。

当前状态（重要，勿误读）

• 模型 server：已成功启动过一次（{"event":"ready", ...}，memory_mode: on），但因用户正在满载训练路由器、 需要让出 GPU，在 tool call 往返验证之前就主动停掉了。
• Agent 侧：代码按 [email protected] 与 pi-agent-core 的实测 API 面编写（createProvider / Model 字段 / AgentTool / 事件名均已核对本机安装与官方 README），但尚未 bun install、尚未 typecheck、尚未真正跑过。 首次运行预计需要少量类型修正。
• 因此：目前没有任何关于该模型 Agent 能力的实测结论。

后续可加

• pass^k 式重复采样稳定性（参考 τ-bench）
• 用户模拟器（多轮协商类场景）
• 记忆容量压力场景（逼近 max_pages / 淘汰行为）
• 多用户隔离场景（两个 user id 交叉询问，验证互不污染）
• 工具输出是否被误写入长期记忆（记忆污染）