Axiom Trace

Local-first, append-only trace vault for AI agents with cryptographic integrity.

pip install axiom-trace

Quick Start (3 Lines)

from axiom_trace import trace

trace.log("Processing user request")
trace.thought("Need to fetch user data")
trace.tool("database_query", {"table": "users"})
trace.done("Found 10 users")

That's it! Traces are saved to .axiom_trace/ in your project.

View Your Traces

# Pretty print recent traces
axiom log

# Watch live (like tail -f)
axiom watch

Output:

────────────────────────────────────────────────────────────────────────────────
AXIOM TRACE LOG (4 entries)
────────────────────────────────────────────────────────────────────────────────
2026-01-09T03:56:43 system_event  Processing user request
2026-01-09T03:56:43 thought       Need to fetch user data
2026-01-09T03:56:43 tool_call     ✓ database_query
2026-01-09T03:56:43 final_result  ✓ Found 10 users
────────────────────────────────────────────────────────────────────────────────

API Reference

Quick Trace Methods

Agent Retrospection (Semantic Search)

from axiom_trace import trace

# Search past traces semantically (powered by Memvid)
results = trace.search("user authentication", limit=5)
for r in results:
    print(f"{r['event_type']}: {r['content']}")

# Get context for prompts
past_context = trace.context("building REST APIs")
prompt = f"Based on my past work:\n{past_context}\n\nNow I need to..."

Auto-Trace Decorator

from axiom_trace import auto_trace

@auto_trace
def fetch_user(user_id: int):
    return db.get(user_id)

# Automatically captures: function name, args, result, timing, exceptions

Agent-Friendly Fields

Traces include fields designed for AI agent retrospection:

trace.record({
    "event_type": "tool_call",
    "content": {
        "input": "User asked: Build REST API",      # What prompted this
        "output": "Created api/users.py",           # What was produced
        "reasoning": "Need CRUD endpoints"          # Why this action
    },
    "success": True,                                # Did it work?
    "artifacts": ["api/users.py"],                  # Files created
    "caused_by": "previous-frame-id"                # Causality chain
})

Memvid Cloud (Optional)

For enhanced semantic search, add your Memvid API key:

# In your project's .env file
MEMVID_API_KEY=mv2_your_key_here

Axiom Trace automatically loads from .env when you import it.

CLI Commands

Advanced: Full API

For more control, use the AxiomTrace class directly:

from axiom_trace import AxiomTrace

with AxiomTrace(vault_dir="./my_vault") as ax:
    # Record with full control
    ax.record({
        "event_type": "thought",
        "content": {
            "text": "Analyzing request",
            "rationale_summary": "Need to understand intent"
        }
    })
    
    # Query with semantic search
    results = ax.query("user request", limit=5)
    
    # Verify integrity
    status = ax.verify_integrity()

Vault Structure

.axiom_trace/
├── frames.jsonl           # Your traces (one JSON per line)
├── vault.manifest.json    # Metadata + head hash
├── vault_index.json       # Search index
└── vault.mv2              # Memvid video index

Why Axiom Trace?

• Local-first - Data stays on your machine
• Append-only - Can't delete or modify past traces
• Tamper-evident - SHA-256 hash chain detects modifications
• Agent-friendly - Fields designed for AI retrospection
• Zero config - Works out of the box

License

MIT