Skip to main content

Actions Graph

Store and track LLM actions, tool calls, and sessions in Memgraph.

Part of the Context Graph family — usually wired into memgraph-context-graph to capture Claude Code / Codex sessions automatically. This README covers using it directly.

Actions Graph provides a graph-based storage system for tracking all LLM interactions, including:

  • Tool Calls: Function/tool invocations by the LLM
  • Tool Results: Outputs from tool executions
  • Messages: User, assistant, and system messages
  • Structured Outputs: Validated JSON outputs from the LLM
  • Subagent Events: Subagent lifecycle tracking
  • Sessions: Conversation session management

Features

  • 📊 Graph-based Storage: Store actions as nodes with relationships in Memgraph
  • 🔗 Temporal Sequences: Track action order with FOLLOWED_BY relationships
  • 🌳 Nested Actions: Support for parent-child action relationships (e.g., subagents)
  • 🏷️ Session Management: Create, track, and query sessions
  • 📈 Analytics: Built-in queries for tool usage stats and session summaries
  • 🔌 Memgraph Context Graph Integration: Consume normalized runtime events through ActionsGraphConnector

Installation

pip install actions-graph

For Memgraph Context Graph integration:

pip install "actions-graph[memgraph-context-graph]"

Needs a running Memgraph (default bolt://localhost:7687); ActionsGraph() reads MEMGRAPH_URL, MEMGRAPH_USER, MEMGRAPH_PASSWORD, MEMGRAPH_DATABASE (or takes them as kwargs):

docker run --rm -p 7687:7687 memgraph/memgraph

Quick Start

Basic Usage

from actions_graph import ActionsGraph, Session

# Initialize the graph
graph = ActionsGraph()  # reads MEMGRAPH_URL / MEMGRAPH_USER / MEMGRAPH_PASSWORD
graph.setup()  # Create indexes and constraints

# Create a session
session = Session(
    session_id="session-123",
    model="claude-sonnet-4-20250514",
    working_directory="/path/to/project",
)
graph.create_session(session)

# Record a tool call
tool_call = graph.record_tool_call(
    session_id="session-123",
    tool_name="Read",
    tool_input={"file_path": "/path/to/file.py"},
    tool_use_id="tool-use-001",
)

# Record the result
tool_result = graph.record_tool_result(
    session_id="session-123",
    tool_use_id="tool-use-001",
    tool_name="Read",
    content="def hello():\n    print('Hello, World!')",
)

# Get session summary
summary = graph.get_session_summary("session-123")
print(f"Actions: {summary['action_count']}, Tools: {summary['tool_call_count']}")

Memgraph Context Graph Integration

from actions_graph import ActionsGraph
from actions_graph.connector import ActionsGraphConnector
from memgraph_context_graph import AgentLink
from memgraph_context_graph.adapters.claude import ClaudeAdapter

graph = ActionsGraph()
graph.setup()

link = AgentLink()
link.add_connector(ActionsGraphConnector(graph))

adapter = ClaudeAdapter(link, session_id="my-session-123")
hooks = adapter.get_runtime_hooks()

Actions Graph should consume runtime activity through Memgraph Context Graph when possible. Runtime adapters normalize SDK callbacks and command hooks into the shared Event Protocol; ActionsGraphConnector decides which events become session and action nodes.

Graph Schema

Nodes

  • Session: LLM conversation sessions

    • Properties: session_id, started_at, ended_at, status, model, total_cost_usd, etc.
  • Action: Individual actions with type-specific labels

    • Labels: ToolCall, ToolResult, Message (plus a role label UserMessage/AssistantMessage/SystemMessage), StructuredOutput, SubagentEvent, PermissionRequest, ErrorEvent, RateLimitEvent
    • Properties: action_id, action_type, timestamp, status, duration_ms, parent_action_id, tool_name, tool_use_id (tool calls and results: the harness's id for the call), is_error, is_mcp, mcp_server (MCP tool calls: the server name), text (user and assistant messages only: the plain message text), properties (type-specific), metadata
    • The session link is the HAS_ACTION edge, not a property — there is no session_id on (:Action).

Relationships

(:Session)-[:HAS_ACTION]->(:Action)
(:Action)-[:FOLLOWED_BY]->(:Action)   # temporal sequence
(:Action)-[:PARENT_OF]->(:Action)     # nested, e.g. subagent
(:Session)-[:FORKED_FROM]->(:Session)

API Reference

ActionsGraph

Main class for interacting with the graph.

graph = ActionsGraph()

# Setup
graph.setup()  # Create indexes
graph.drop()  # Remove indexes
graph.clear()  # Clear all data

# Sessions
graph.create_session(session)
graph.get_session(session_id)
graph.end_session(session_id, status=ActionStatus.COMPLETED)
graph.list_sessions(limit=100, status=None)  # keyword-only args

# Actions
graph.record_action(action)
graph.record_tool_call(session_id, tool_name, tool_input, ...)
graph.record_tool_result(session_id, tool_use_id, tool_name, content, ...)
graph.record_message(session_id, role, content, ...)
graph.get_action(action_id)
graph.get_session_actions(session_id, action_type=None, limit=1000)

# Analytics
graph.get_tool_usage_stats(session_id=None)
graph.get_action_sequence(session_id, include_content=False)
graph.get_session_summary(session_id)

Action Types

Type Model Class Description
tool_call ToolCall Tool/function invocation
tool_result ToolResult Tool execution result
user_message Message User input
assistant_message Message LLM response
system_message Message System messages
structured_output StructuredOutput Validated JSON output
subagent_start SubagentEvent Subagent started
subagent_stop SubagentEvent Subagent completed
error ErrorEvent Error occurred
permission_request PermissionRequest Permission requested
rate_limit RateLimitEvent Rate limit event

Memgraph Context Graph Connector

from actions_graph.connector import ActionsGraphConnector

connector = ActionsGraphConnector(graph)
link.add_connector(connector)

The connector records:

  • SessionStartEvent and SessionEndEvent as session lifecycle data
  • ToolStartEvent as ToolCall action nodes
  • ToolEndEvent as ToolResult action nodes
  • MessageEvent, AgentStartEvent, AgentEndEvent, and ErrorOccurredEvent as action nodes

Claude Agent SDK Hooks

Direct Claude Agent SDK hooks remain available for standalone use, but Memgraph Context Graph is the preferred integration path when multiple graph components need the same runtime event stream.

For Claude Agent SDK integration:

from actions_graph.hooks import create_tracking_hooks, ActionTracker

# Simple usage
hooks = create_tracking_hooks(graph, session_id)

# Advanced usage with custom tracker
tracker = ActionTracker(
    graph,
    session_id,
    track_tool_calls=True,
    track_tool_results=True,
    track_messages=True,
    track_subagents=True,
    track_permissions=True,
    track_errors=True,
)

Example Queries

Find sessions with errors

sessions = graph.list_sessions(status=ActionStatus.FAILED)

Get all tool calls in a session

from actions_graph import ActionType

tool_calls = graph.get_session_actions(
    session_id,
    action_type=ActionType.TOOL_CALL,
)

Custom Cypher queries

rows = graph._db.query(
    """
    MATCH (s:Session {session_id: $session_id})-[:HAS_ACTION]->(a:ToolCall)
    RETURN a.tool_name AS tool, count(*) AS count
    ORDER BY count DESC
""",
    params={"session_id": "my-session"},
)

License

MIT

Metadata

Release files for actions-graph 0.5.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for actions-graph 0.5.0
File Size Uploaded Provenance Actions
actions_graph-0.5.0.tar.gz 41.1 kB Without provenance Details for actions_graph-0.5.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for actions-graph 0.5.0
File Interpreter ABI Platform Actions
actions_graph-0.5.0-py3-none-any.whl Python 3 none any Details for actions_graph-0.5.0-py3-none-any.whl

Total release size: 68.4 kB

Release files / actions_graph-0.5.0.tar.gz

Download URL actions_graph-0.5.0.tar.gz
Size 41.1 kB
Tags Source
SHA-256 checksum
How to use checksums
68ae56faf005dd3f370c049c78fdcd7c686e0762bbc4ad19aa7b4a0e4c5a902d
BLAKE2b-256 checksum
How to use checksums
ba1786be3cdc34362657b61331beb6daef84490a2bdc8ef33e139623f226d646
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.13.0 {"installer":{"name":"uv","version":"0.13.0","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

Release files / actions_graph-0.5.0-py3-none-any.whl

Download URL actions_graph-0.5.0-py3-none-any.whl
Size 27.4 kB
Tags Python 3
SHA-256 checksum
How to use checksums
3cd9b86011e4f39bd24c14acba0764941acb4abfa39962f2996774b8a04bc340
BLAKE2b-256 checksum
How to use checksums
90eb8be55de1b78e6f27f22485c0092bf363201b8c2e91d9dc862051a6356b27
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.13.0 {"installer":{"name":"uv","version":"0.13.0","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

Security for actions-graph 0.5.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page