Skip to main content

Actions Graph

Record agent tool calls, results, messages, errors, and subagents in Memgraph. Inspect a session's timeline or query tool usage across sessions.

Part of Context Graph. The installer enables automatic capture for coding agents; this README shows direct Python use.

Installation

pip install actions-graph

For the runtime connector, install actions-graph[memgraph-context-graph]. A running Memgraph is required; the default connection is bolt://localhost:7687.

Quick start

from actions_graph import ActionsGraph, Session

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

session = Session(
    session_id="session-123",
    working_directory="/path/to/project",
)
graph.create_session(session)

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",
)

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!')",
)

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

ActionsGraph() reads MEMGRAPH_URL, MEMGRAPH_USER, MEMGRAPH_PASSWORD, and MEMGRAPH_DATABASE, or accepts connection keyword arguments. Hook integrations use the Context Graph config file instead.

What is stored

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

Use with an agent runtime

Runtime adapters translate activity into shared events. ActionsGraphConnector records the events as session, action, and subagent nodes.

from actions_graph import ActionsGraph
from actions_graph.connector import ActionsGraphConnector
from memgraph_context_graph import AgentLink

graph = ActionsGraph()
graph.setup()

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

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.

For a complete SDK application, see the SDK quick starts.

Query and API reference

The Python API guide covers recording events, session analytics, action types, and example queries.

Development

From the repository root:

./scripts/dev-memgraph.sh test actions-graph

License

MIT

Metadata

Release files for actions-graph 0.7.2

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.2
File Size Uploaded Provenance Actions
actions_graph-0.7.2.tar.gz 37.2 kB Without provenance Details for actions_graph-0.7.2.tar.gz

Built distribution (wheel)

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

Total release size: 58.8 kB

Release files / actions_graph-0.7.2.tar.gz

Download URL actions_graph-0.7.2.tar.gz
Size 37.2 kB
Tags Source
SHA-256 checksum
How to use checksums
244025341a689bb179834c6209dcb4f9499316a29affcf349be8774c796a7372
BLAKE2b-256 checksum
How to use checksums
f2b2a76dcc02bff322cfaa8cd492db425a9ac76837cc2552f24d4c1978be3e29
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.13.6 {"installer":{"name":"uv","version":"0.13.6","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"26.04","id":"resolute","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.2-py3-none-any.whl

Download URL actions_graph-0.7.2-py3-none-any.whl
Size 21.6 kB
Tags Python 3
SHA-256 checksum
How to use checksums
02deeaf878da72c3b0afde8ff57403112e37cbc689f0488db35265b65c9f2702
BLAKE2b-256 checksum
How to use checksums
59c70dba86554896f827e09d44ababaf7781f037e2ecf644ff62714e74880dca
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.13.6 {"installer":{"name":"uv","version":"0.13.6","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"26.04","id":"resolute","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.2

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