Vlk MemAct

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'0 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'0 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.