Actions Graph
Store and track LLM actions, tool calls, and sessions in Memgraph.
Part of the Context Graph family — usually wired into
memgraph-context-graphto 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(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
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:
SessionStartEventandSessionEndEventas session lifecycle dataToolStartEvent/ToolEndEventasToolCall/ToolResultactionsMessageEventandErrorOccurredEventasMessage/ErrorEventactionsAgentStartEvent/AgentEndEventas oneAgentnode
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.0
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.0.tar.gz | 36.8 kB | Without provenance | Details for actions_graph-0.7.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| actions_graph-0.7.0-py3-none-any.whl | Python 3 | none | any | Details for actions_graph-0.7.0-py3-none-any.whl |
Total release size: 59.0 kB
Release files / actions_graph-0.7.0.tar.gz
| Download URL | actions_graph-0.7.0.tar.gz |
|---|---|
| Size | 36.8 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
747b0b3f8b27f99d3153d8085b2b08dfbd2f464e5368af722fbedd1480c6ad76
|
|
BLAKE2b-256 checksum How to use checksums |
9e1c752bb11e24a1985c571d31ffc5714cab0e52ba1554f2fe7f66807347927d
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.13.4 {"installer":{"name":"uv","version":"0.13.4","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.0-py3-none-any.whl
| Download URL | actions_graph-0.7.0-py3-none-any.whl |
|---|---|
| Size | 22.2 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
e1b33943c762bbd439545295f602963b69d5b502e9fa79bb63c756901e146390
|
|
BLAKE2b-256 checksum How to use checksums |
288509cf4d6baf6c66ac0854c8011844cefdb8780b582bc2bffaa0ec293d52b2
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.13.4 {"installer":{"name":"uv","version":"0.13.4","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.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.