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-corecargo build --releaseDATABASE_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())
# Initrpc({'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 detectionerror = '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 injectionr = 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:        passprint('PASS: loop detection works')

Integration

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

# ~/.hermes/config.yaml or equivalentmcp_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.