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

Apache-2.0

Metadata

Release files for actions-graph 0.7.3

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.3
File Size Uploaded Provenance Actions
actions_graph-0.7.3.tar.gz 40.5 kB Without provenance Details for actions_graph-0.7.3.tar.gz

Built distribution (wheel)

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

Total release size: 65.4 kB

Release files / actions_graph-0.7.3.tar.gz

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

Download URL actions_graph-0.7.3-py3-none-any.whl
Size 25.0 kB
Tags Python 3
SHA-256 checksum
How to use checksums
d1e887233d6edb18e3ef74d4c19cffdf91e415655d8f68fd6835d870d45a0325
BLAKE2b-256 checksum
How to use checksums
26ab92d025e3bc065da339bf5ce6b645f2ca890b232ba676cc37b643f51a4157
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.13.9 {"installer":{"name":"uv","version":"0.13.9","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.3

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