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.

Records each agent session's tool calls, tool results, messages, errors, and subagents as (:Action)/(:Agent) nodes for observability and tool-usage analytics. Collection-tier data, not memory.

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: session_id, started_at, ended_at, status, model, total_cost_usd, token totals, working_directory, git_branch, metadata.
  • Agent: one subagent's lifecycle (agent_id, agent_type, started_at, ended_at, status, description, last_assistant_message).
  • Action: one event, with a type label: ToolCall, ToolResult, Message (plus UserMessage/AssistantMessage/SystemMessage), StructuredOutput, PermissionRequest, ErrorEvent, RateLimitEvent. Properties: action_id, action_type, timestamp, status, duration_ms, parent_action_id, tool_name, tool_use_id (the harness's id for the call), is_error, is_mcp, mcp_server (MCP tool calls), text (user and assistant messages only), properties (type-specific JSON), metadata. The session link is the HAS_ACTION edge; there is no session_id on (:Action).

Relationships

(:Session)-[:HAS_ACTION]->(:Action)   # top-level actions
(:Session)-[:HAS_AGENT]->(:Agent)     # every agent, even when its spawner is unknown
(:Agent)-[:HAS_ACTION]->(:Action)     # actions inside a subagent
(:Action)-[:SPAWNED]->(:Agent)        # spawning tool call, when unambiguous
(:Action)-[:FOLLOWED_BY]->(:Action)   # temporal sequence, one chain per Session/Agent
(:Action)-[:PARENT_OF]->(:Action)     # ToolCall -> its ToolResult

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)

# Subagents
graph.start_agent(agent)
graph.end_agent(agent_id, status=ActionStatus.COMPLETED)
graph.get_agent(agent_id)
graph.get_session_agents(session_id)

# 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
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/ToolEndEvent as ToolCall/ToolResult actions
  • MessageEvent and ErrorOccurredEvent as Message/ErrorEvent actions
  • AgentStartEvent/AgentEndEvent as one Agent node

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.7.1

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.7.1
File Size Uploaded Provenance Actions
actions_graph-0.7.1.tar.gz 37.0 kB Without provenance Details for actions_graph-0.7.1.tar.gz

Built distribution (wheel)

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

Total release size: 59.4 kB

Release files / actions_graph-0.7.1.tar.gz

Download URL actions_graph-0.7.1.tar.gz
Size 37.0 kB
Tags Source
SHA-256 checksum
How to use checksums
6ba8f875915924c03f6a962f9c84df16f48b1c1b9bba656270b8e3888af9fed2
BLAKE2b-256 checksum
How to use checksums
bc2d0e9043daf70400db8f3e7df722ec812e5db92f1a63e17fde5950e263a734
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.13.5 {"installer":{"name":"uv","version":"0.13.5","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.7.1-py3-none-any.whl

Download URL actions_graph-0.7.1-py3-none-any.whl
Size 22.4 kB
Tags Python 3
SHA-256 checksum
How to use checksums
11350460777c8049de24aa4c5ba650678a066fd84ac1fc40774b9326f09cfce0
BLAKE2b-256 checksum
How to use checksums
fecaf3faa4a0460580895908b0f70eae1c9fd6a227e4ed2286510076bd276e99
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.13.5 {"installer":{"name":"uv","version":"0.13.5","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.7.1

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