Vlk MemAct

Vlk² — AI Agent 的时间状态机

Vlk² 赋予 AI Agent 时间感：正在发生的事情（PRESENT）、已经尝试过的事情（PAST），以及应当指导未来决策的内容（FUTURE）。它以 MCP 单个二进制文件的形式运行，由 SQLite 提供支持，并自主管理这些时间状态转换。

核心演示：当 Agent 将同一个 Rust/TS/Python/Go 错误重复遇到 3 次时，Vlk² 会自动将该循环归档，并注入一条预防性约束，让 Agent 停止重试同一种错误方法。但其架构具有通用性——这个时间状态机可以在任何 Agent 框架中追踪任意类型的过去→现在→未来状态转换。

功能

• 时间状态机 — 每条记忆都有一个状态：PRESENT（活跃上下文）、PAST（已归档，不显示在上下文中）、FUTURE（预防性约束）、PURGED（已遗忘）。后台 Agent 会在无需 Agent 干预的情况下转换条目的状态。
• 跨语言循环检测 — 按语言而非字符串匹配来为错误生成指纹。可识别 Rust（error[E0277]）、TypeScript/JS（TS2345、TypeError）、Python（ValueError、KeyError）、Go（panic: nil pointer）、HTTP（503 Service Unavailable）、测试框架（expected: X, got: Y），并在无法匹配时回退为剥离时间戳。当同一指纹出现 ≥3 次时，Vlk² 会自动将该循环归档到 PAST，并注入一条 FUTURE 约束。
• 检索时重新巩固 — 每次召回都会检查当前信念；如果存在矛盾，记忆会重写自身。
• 令牌预算强制管理 — 每隔 30s 估算 PRESENT + FUTURE 中的令牌总数。如果超出预算（默认 8K），就归档重要性最低的条目，直到低于预算。
• 自主整合 — 后台任务（每 30s 一个周期）会评估重要性、归档过时条目，并遗忘彼此无关联的条目。

为什么不直接使用记忆系统？

通用记忆系统（agentmemory、Hindsight、Mem0、Supermemory）会存储事实、偏好和上下文。Vlk² 做了一件它们做不到的事：**检测同一个 Rust 编译错误是否在不同文件中重复出现 3 次，并注入一条约束，让 Agent 停止重试同一种错误方法。**它并非替代品，而是一个可与这些系统并行运行的专用故障检测层。

能力	Vlk²	agentmemory	Hindsight	Supermemory
事实/角色记忆	—	✅ 53 个工具	✅ hooks	✅ 关键词
跨语言错误指纹识别	✅ 7 种策略	—	—	—
自主打破循环	✅ 重复 ≥3 次后自动归档	—	—	—
检索时重新巩固	✅	—	—	—
受令牌数限制的上下文	✅ 默认 8K	—	—	—

快速开始

cd vlk-core
cargo build --release
DATABASE_URL="sqlite:vlk.db?mode=rwc" ./target/release/vlk-core

任何 MCP 客户端都可通过 stdin/stdout 连接——JSON-RPC 2.0，每条消息占一行。

MCP 工具

工具	用途
vlk_record_state	将日志/错误推送为 PRESENT 槽位，用于循环检测
vlk_fetch_context	获取经过清理的上下文，并进行重新巩固和循环拦截
vlk_time_travel	将 PRESENT 归档到 PAST，并注入一条 FUTURE 约束
vlk_get_history	完整的时间线审计
vlk_search_memory	跨日志和约束进行关键词搜索
vlk_summarize_session	状态计数和令牌估算
vlk_revoke_future	移除错误学习到的约束
vlk_get_facts	检索提炼后的模式
vlk_consolidation_status	显示整合 Agent 状态和令牌进度条
vlk_pin_memory	保护模式，避免被遗忘
vlk_unpin_memory	恢复正常的遗忘资格

循环检测的工作原理

1. 按类型为每个错误生成指纹：Rust error[E...]、TS TS...、Python TypeError:、Go panic:、HTTP 503、测试断言，或前 80 个字符的回退值
2. 指纹将近似重复项归为一组——错误代码相同、时间戳或行号不同，也算作同一种模式
3. 重复次数达到 ≥3 次 → 自动归档循环，并注入 [SYSTEM ANCHOR] 预防性约束
4. 后续上下文获取会包含该约束，因此 Agent 会停止重复错误

架构

memory_contents (immutable, team-agnostic)
  └── FK ──► agent_timeline (PRESENT / PAST / FUTURE / PURGED)
               ├── memory_metadata (temporal vectors, importance, connectivity)
               └── semantic_facts (distilled patterns from errors)
                    └── fact_contradictions (resolution tracking)

Consolidation Agent (background tokio, 30s cycle)
  SCAN → EVALUATE importance → BUDGET_CHECK → ARCHIVE low-value → FORGET stale

验证

已测试内容： 已验证核心循环检测路径：3 次相同的 Rust 错误 → 自动归档至 PAST + 注入 FUTURE 约束。全部 13 个 MCP 工具均能正确响应。

尚未测试： 使用不存在的 timeline_ids 进行固定/取消固定、负载下的令牌预算执行、冲突解决。

循环检测冒烟测试——连续发送相同的 Rust error[E0277] 3 次，并验证自动归档 + 约束注入：

import subprocess, json, tempfile, os, sys

db = tempfile.mktemp(suffix='.db')
proc = subprocess.Popen(['./target/release/vlk-core'],
    stdin=subprocess.PIPE, stdout=subprocess.PIPE,
    stderr=subprocess.DEVNULL,
    env={'DATABASE_URL': f'sqlite:{db}?mode=rwc'})

def rpc(msg):
    proc.stdin.write((json.dumps(msg) + '\n').encode())
    proc.stdin.flush()
    return json.loads(proc.stdout.readline())

# Init
rpc({'jsonrpc':'2.0','id':1,'method':'initialize','params':{
    'protocolVersion':'2024-11-05','capabilities':{},
    'clientInfo':{'name':'test','version':'1.0'}}})

# Send the same Rust error 3 times to trigger loop detection
error = 'error[E0277]: cannot add `str` to `str`'
for i in range(3):
    r = rpc({'jsonrpc':'2.0','id':i+2,'method':'tools/call','params':{
        'name':'vlk_record_state',
        'arguments':{'raw_log': error, 'file_context': f'lib.rs:{i*10}'}}})
    assert 'PRESENT state recorded' in r['result']['content'][0]['text']
    print(f'  Record {i+1}: OK')

# fetch_context triggers loop detection → auto-archive → constraint injection
r = rpc({'jsonrpc':'2.0','id':5,'method':'tools/call','params':{
    'name':'vlk_fetch_context','arguments':{}}})
txt = r['result']['content'][0]['text']
assert 'E0277' in txt, 'error missing after fetch'
assert any(kw in txt for kw in ['SYSTEM ANCHOR', 'PREVENTIVE', 'CONSTRAINT']), \
    'no constraint injected'
print(f'  Fetch: loop archived + constraint injected')

proc.terminate(); proc.wait()
for f in (db, db + '-wal', db + '-shm'):
    try:
        os.remove(f)
    except FileNotFoundError:
        pass
print('PASS: loop detection works')

集成

添加到 Hermes、OpenCode、Claude Code、Codex 或任何 MCP 宿主：

# ~/.hermes/config.yaml or equivalent
mcp_servers:
  vlk2:
    command: "vlk2"
    env:
      DATABASE_URL: "sqlite:~/.hermes/vlk/vlk.db?mode=rwc"
    timeout: 30

兼容任何 MCP 客户端。可与 agentmemory、Hindsight、Supermemory 或 Hermes 内置记忆协同工作。

要求

• Rust 2021 edition
• SQLite（通过 sqlx 捆绑）
• 6.4MB 二进制文件

当前状态

正在积极开发。核心循环检测和纠正性记忆周期已实现并通过 E2E 测试。Vlk² 是对通用记忆系统的专业补充，而非替代品。