GitHub - aranajhonny/vlk

Vlk² — Temporal State Machine for AI Agents

Vlk² gives AI agents a sense of time: what's happening now (PRESENT), what's already been tried (PAST), and what should guide future decisions (FUTURE). It runs as a single binary over MCP, backed by SQLite, and manages these temporal transitions autonomously.

The killer demo: when an agent repeats the same Rust/TS/Python/Go error 3 times, Vlk² auto-archives the loop and injects a preventive constraint so the agent stops retrying the same broken approach. But the architecture is general — the temporal state machine can track any kind of past→present→future transition across any agent framework.

What It Does

• Temporal state machine — each memory has a state: PRESENT (active context), PAST (archived, hidden from context), FUTURE (preventive constraints), PURGED (forgotten). A background agent transitions entries between states without agent intervention.
• Cross-language loop detection — fingerprints errors by language, not by string match. Recognizes Rust (error[E0277]), TypeScript/JS (TS2345, TypeError), Python (ValueError, KeyError), Go (panic: nil pointer), HTTP (503 Service Unavailable), test frameworks (expected: X, got: Y), with a timestamp-stripping fallback. When the same fingerprint appears ≥3 times, Vlk² auto-archives the loop to PAST and injects a FUTURE constraint.
• Reconsolidation on retrieval — every recall checks current beliefs; if contradictory, the memory rewrites itself.
• Token budget enforcement — every 30s, estimates total tokens in PRESENT + FUTURE. If over budget (8K default), archives lowest-importance entries until under budget.
• Autonomous consolidation — background task (30s cycle) evaluates importance, archives stale entries, and forgets disconnected ones.

Why Not Just a Memory System?

General memory systems (agentmemory, Hindsight, Mem0, Supermemory) store facts, preferences, and context. Vlk² does one thing they don't: detect that the same Rust compile error repeated 3 times across different files and inject a constraint so the agent stops retrying the same broken approach. It's not a replacement — it's a specialized fault-detection layer that runs alongside them.

Quick Start

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

Any MCP client connects via stdin/stdout — JSON-RPC 2.0, one line per message.

MCP Tools

How Loop Detection Works

1. Each error is fingerprinted by type: Rust error[E...], TS TS..., Python TypeError:, Go panic:, HTTP 503, test assertion, or first-80-chars fallback
2. Fingerprints group near-duplicates — same error code with different timestamps/line numbers count as one pattern
3. At ≥3 repeats → auto-archives the loop + injects [SYSTEM ANCHOR] preventive constraint
4. Future context fetches include the constraint, so the agent stops repeating

Architecture

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

Verification

What's tested: the core loop detection path is verified: 3 identical Rust errors → auto-archive to PAST + FUTURE constraint injection. All 13 MCP tools respond correctly.

Not yet tested: pin/unpin with non-existent timeline_ids, token budget enforcement under load, conflict resolution.

Loop detection smoke test — sends the same Rust error[E0277] 3 times and verifies auto-archive + constraint injection:

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')

Integration

Add to Hermes, OpenCode, Claude Code, Codex, or any MCP host:

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

Compatible with any MCP client. Works alongside agentmemory, Hindsight, Supermemory, or Hermes built-in memory.

Requirements

• Rust 2021 edition
• SQLite (bundled via sqlx)
• 6.4MB binary

Current Status

Actively developed. The core loop detection and corrective memory cycle is implemented and E2E-tested. Vlk² is a specialized complement to general memory systems — not a replacement.