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.6.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.6.0
File Size Uploaded Provenance Actions
actions_graph-0.6.0.tar.gz 34.3 kB Without provenance Details for actions_graph-0.6.0.tar.gz

Built distribution (wheel)

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

Total release size: 55.6 kB

Release files / actions_graph-0.6.0.tar.gz

Download URL actions_graph-0.6.0.tar.gz
Size 34.3 kB
Tags Source
SHA-256 checksum
How to use checksums
888b06851391909285fabd04bbd1699fc5ba2e7653fabf9edbde3e7d764a98cb
BLAKE2b-256 checksum
How to use checksums
861fd33a92cad1fc453c9a5805661e95d15a5969937a6706a0b4669fabf4acc6
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.13.3 {"installer":{"name":"uv","version":"0.13.3","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.6.0-py3-none-any.whl

Download URL actions_graph-0.6.0-py3-none-any.whl
Size 21.3 kB
Tags Python 3
SHA-256 checksum
How to use checksums
697b60fe6fe99ab7b482d8ba97ce3cd18d5a705fa5c887628ce7c189b1e5fc5b
BLAKE2b-256 checksum
How to use checksums
d6888cd442d2580d8ec81040d84512901023ecfbfa40c7b354be56a2f9611435
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.13.3 {"installer":{"name":"uv","version":"0.13.3","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.6.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