Skip to main content

History & Auditing

OfSelf tracks changes to nodes over time to support auditing, rollback, and transparency for AI-assisted updates.

Why It Matters​

  • Trust: See what changed and why
  • Collaboration: Attribute edits to agents/apps/users
  • Debugging: Reproduce issues by inspecting past versions
  • Accountability: Full audit trail of every modification

Node History​

Every update to a node creates a history entry with:

  • Version number: Incrementing version for tracking evolution
  • Full snapshot: Complete node state at that point in time
  • Changed fields: Delta showing what fields were modified
  • Agent metadata: Which agent made the change and with what confidence
  • Timestamp: When the change occurred
# Get version history for a node
history = client.nodes.get_history(
    node_id="node_abc",
    include_snapshots=True  # Include full node state at each version
)

for entry in history['items']:
    print(f"Version {entry['version']}: {entry['change_type']}")
    if entry['agent_metadata']:
        print(f"  Agent: {entry['agent_metadata']['agent_name']}")
        print(f"  Confidence: {entry['agent_metadata']['confidence_score']}")
    print(f"  Changed: {list(entry['changed_fields'].keys())}")

Time-Travel Inspection​

View a node's state at any point in time:

# Get node state at a specific timestamp
GET /nodes/:node_id/history/at-time?timestamp=2025-01-15T10:30:00Z

# Get a specific version
GET /nodes/:node_id/history/:version

Node Ledger​

The node ledger provides a summary of all agents that contributed to a node:

ledger = client.nodes.get_ledger(node_id="node_abc")

print(f"Total agents: {ledger['total_agents']}")
for agent in ledger['agents']:
    print(f"  {agent['agent_name']}: {agent['contribution_count']} edits")
    print(f"    Last active: {agent['last_contribution']}")

Field-Level Contributions​

Track which agent contributed which specific field values:

contributions = client.nodes.get_contributions(
    node_id="node_abc",
    status="active"  # active, superseded, rejected, merged, or all
)

for contrib in contributions['contributions']:
    print(f"  Field: {contrib['field_name']}")
    print(f"  Value: {contrib['contributed_value']}")
    print(f"  By: {contrib['contributor_id']}")
    print(f"  Confidence: {contrib['confidence_score']}")

Parsing Sessions​

Group related agent operations together:

# List parsing sessions
sessions = client.sessions.list(status="completed")

# Get session details with contribution stats
session = client.sessions.get(session_id="sess_abc")
# Includes: total contributions, unique nodes, unique contributors

Graph Snapshots (Time Travel)​

View the entire graph state at a point in time:

GET /graph/snapshot?timestamp=2025-01-15T10:30:00Z

This reconstructs all nodes and relationships as they existed at that timestamp. Useful for:

  • Audit views
  • "What did the graph look like before this change?"
  • Debugging multi-agent collaboration

Next​