# 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.

| Capability | Vlk² | agentmemory | Hindsight | Supermemory |
|-----------|------|-------------|-----------|-------------|
| Fact/persona memory | — | ✅ 53 tools | ✅ hooks | ✅ keywords |
| Cross-language error fingerprinting | ✅ 7 strategies | — | — | — |
| Autonomous loop breaking | ✅ ≥3 repeats auto-archive | — | — | — |
| Reconsolidation on retrieval | ✅ | — | — | — |
| Token-bounded context | ✅ 8K default | — | — | — |

## Quick Start

```bash
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

| Tool | Purpose |
|------|---------|
| `vlk_record_state` | Push a log/error as a PRESENT slot for loop detection |
| `vlk_fetch_context` | Clean context with reconsolidation + loop interception |
| `vlk_time_travel` | Archive PRESENT → PAST and inject a FUTURE constraint |
| `vlk_get_history` | Full timeline audit |
| `vlk_search_memory` | Keyword search across logs and constraints |
| `vlk_summarize_session` | State counts + token estimates |
| `vlk_revoke_future` | Remove incorrectly learned constraints |
| `vlk_get_facts` | Retrieved distilled patterns |
| `vlk_consolidation_status` | Show consolidation agent state with token bar |
| `vlk_pin_memory` | Protect a pattern from forgetting |
| `vlk_unpin_memory` | Restore normal forgetting eligibility |

## 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:

```python
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:

```yaml
# ~/.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.