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(plusUserMessage/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 theHAS_ACTIONedge; there is nosession_idon(: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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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.