axiom-trace 1.4.2

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

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

Method	When to Use	Example
trace.log(msg)	Simple log message	trace.log("Starting")
trace.thought(reasoning)	Agent is thinking/deciding	trace.thought("Need API call")
trace.tool(name, args)	Calling a tool/function	trace.tool("search", {"q": "..."})
trace.done(result)	Task completed	trace.done("Success!")
trace.error(msg, exc)	Something failed	trace.error("Failed", e)
trace.input(text)	User said something	trace.input("What's the weather?")
trace.search(query)	Semantic search traces	trace.search("authentication")
trace.context(query)	Get past context as string	trace.context("API design")

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

Command	Description
axiom log	Pretty print recent traces
axiom watch	Live trace monitoring
axiom query --prompt "..."	Search traces semantically
axiom verify	Check hash chain integrity
axiom stats	Show vault statistics
axiom export --session ID	Export session to Markdown

---

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