agent-context-graph 0.1.8__tar.gz → 0.2.0__tar.gz

{agent_context_graph-0.1.8 → agent_context_graph-0.2.0}/.gitignore

@@ -190,3 +190,5 @@ cython_debug/
 
 # Project specific files
 /enterprise-context/sic-agent/sic-scrapper/output/*
+unstructured2graph/docs/adr/
+unstructured2graph/CONTEXT.md

{agent_context_graph-0.1.8 → agent_context_graph-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: agent-context-graph
-Version: 0.1.8
+Version: 0.2.0
 Summary: Connect agent SDKs to context-graph components (actions-graph, skills-graph, etc.)
 License: MIT
 License-File: LICENSE
@@ -33,6 +33,8 @@ Runtime Adapter  ->  Event Protocol  ->  Graph Connector(s)
 
 Runtime plugins are the distribution layer for host-specific hook wiring. They install hooks, skills, and setup helpers for a runtime, then call Agent Context Graph. They are not graph components and should not encode graph-specific meaning.
 
+> **Just want to capture your Claude Code / Codex sessions?** Start with the [Context Graph guide](../README.md) — it walks through installing the plugin and wiring all the connectors end to end. This README covers the adapter layer itself and the in-process SDK path.
+
 ## Installation
 
 For command-hook runtimes such as Codex and Claude Code, prefer a user-level tool install:
@@ -109,6 +111,7 @@ from skills_graph.connector import SkillGraphConnector
 skills = SkillGraph()
 skills.setup()
 
+
 # 2. Define a tool whose name matches the SkillGraphConnector defaults
 @function_tool
 def get_skill(name: str) -> str:
@@ -117,6 +120,7 @@ def get_skill(name: str) -> str:
         return f"Skill '{name}' not found."
     return f"{skill.name}: {skill.description}\n{skill.content}"
 
+
 # 3. Wire up the link
 link = AgentLink()
 link.add_connector(SkillGraphConnector(skills))
@@ -164,64 +168,98 @@ Implemented:
 
 ### First-Time Plugin Setup
 
-For Codex and Claude Code plugins, the recommended first-run path is the bootstrap command. It installs the runtime package, checks Memgraph, installs the graph connector extra, and runs `doctor`.
+For Codex and Claude Code plugins, the recommended first-run path is the bootstrap command. It installs the runtime package (with the connector extras), checks Memgraph, and runs `doctor`.
 
 Prerequisites:
 
-- `uv` on `PATH`.
-- Memgraph running and reachable over Bolt. Defaults are `bolt://localhost:7687`, empty user/password, and database `memgraph`.
+- `uv` on `PATH`. (`uv` manages Python for the tool; if uv-managed Python downloads are blocked, install Python 3.10+ and rerun bootstrap.)
+- Memgraph running and reachable over Bolt. Defaults are `bolt://localhost:7687`, empty user/password, database `memgraph`. If it isn't running locally:
+
+  ```bash
+  docker run --rm -p 7687:7687 memgraph/memgraph
+  ```
 
-**Environment variables:**
+**1. Bootstrap all three connectors** (this is what the installed plugin wires into its hooks):
 
-| Variable | Default | Description |
-|---|---|---|
-| `MEMGRAPH_URL` | `bolt://localhost:7687` | Bolt URL — set to a remote host for non-local Memgraph |
-| `MEMGRAPH_USER` | `""` | Bolt username (service account) |
-| `MEMGRAPH_PASSWORD` | `""` | Bolt password or OAuth token |
-| `MEMGRAPH_DATABASE` | `memgraph` | Target database name |
-| `AGENT_CONTEXT_GRAPH_USER_ID` | _(none)_ | Human identity stored on Memory nodes — required for sessions-graph to associate memories with a user |
+```bash
+# Codex
+agent-context-graph bootstrap --runtime codex \
+  --connector skills-graph --connector actions-graph --connector sessions-graph
+
+# Claude Code
+agent-context-graph bootstrap --runtime claude-code \
+  --connector skills-graph --connector actions-graph --connector sessions-graph
+```
 
-If Memgraph is not running locally, start it first:
+The plugin wrapper script runs the same command (and falls back to `uvx` if the tool isn't installed yet):
 
 ```bash
-docker run --rm -p 7687:7687 memgraph/memgraph
+./scripts/bootstrap.sh
 ```
 
-`uv` manages Python for the tool. If uv-managed Python downloads are blocked in your environment, install Python 3.10+ and rerun bootstrap.
+**2. Configure identity and connection.** Bootstrap writes `~/.config/context-graph/config.toml`; hooks read their configuration from that file at runtime (see [Configuration](#configuration) — env vars are **not** read at hook time). Set your identity, which sessions-graph requires:
+
+```bash
+agent-context-graph config set identity.user_id "your-name"
+```
 
-For Codex:
+The Memgraph connection defaults to `bolt://localhost:7687`. For a remote or HA instance:
 
 ```bash
-agent-context-graph bootstrap --runtime codex --connector skills-graph
+agent-context-graph config set memgraph.url "neo4j://<coordinator-host>:7687"
+agent-context-graph config set memgraph.user "<user>"
+agent-context-graph config set memgraph.password        # prompts; stored 0600
+agent-context-graph config set memgraph.database "memgraph"
 ```
 
-For Claude Code:
+**3. Verify:**
 
 ```bash
-agent-context-graph bootstrap --runtime claude-code --connector skills-graph
+agent-context-graph config show
+agent-context-graph doctor --runtime claude-code \
+  --connector skills-graph --connector actions-graph --connector sessions-graph
 ```
 
-Expected successful doctor output looks like:
+Expected successful doctor output (use `--runtime codex` for Codex):
 
 ```text
 OK agent-context-graph executable: ...
 OK agent-context-graph: ...
+OK config: identity.user_id set
+OK memgraph: reachable
 OK connector:skills-graph: installed=...; memgraph=reachable
-OK runtime:codex: strict hook smoke passed
+OK connector:actions-graph: installed=...; memgraph=reachable
+OK connector:sessions-graph: installed=...; memgraph=reachable
+OK runtime:claude-code: strict hook smoke passed
 ```
 
-Use the matching runtime value when checking Claude Code:
+> **Reconciliation is a separate step.** The connectors capture session activity, but turning a session's text into extracted entities (a `:Person`/`:Organization` graph) is done out-of-band — see [sessions-graph § reconciliation](../sessions-graph/README.md#session-reconciliation). By default a finished session is marked `reconciliation_status = 'pending'` and `sessions-graph reconcile --pending` extracts it.
 
-```text
-OK runtime:claude-code: strict hook smoke passed
+### Configuration
+
+Bootstrap and the `config` command write `~/.config/context-graph/config.toml` (mode `0600`). **Hook subprocesses resolve their configuration from CLI flags and this file only — never from environment variables** (they don't inherit your shell), per [ADR 0002](docs/adr/0002-config-file-only-hook-resolution.md).
+
+```toml
+[identity]
+user_id = "your-name"
+
+[memgraph]
+url = "bolt://localhost:7687"
+user = ""
+password = ""
+database = "memgraph"
 ```
 
-The plugin wrapper scripts call the same bootstrap command. If `agent-context-graph` is not installed yet, they fall back to `uvx`:
+Manage it with:
 
 ```bash
-./scripts/bootstrap.sh
+agent-context-graph config show
+agent-context-graph config get memgraph.url
+agent-context-graph config set <key> <value>   # keys: identity.user_id, memgraph.{url,user,password,database}
 ```
 
+Environment variables (`MEMGRAPH_URL`, `MEMGRAPH_USER`, `MEMGRAPH_PASSWORD`, `MEMGRAPH_DATABASE`, `AGENT_CONTEXT_GRAPH_USER_ID`) are consulted **only at bootstrap time** — if set, `bootstrap` persists them into the config file. Exporting them later has no effect on running hooks; use `config set` instead.
+
 ### OpenAI Codex Plugin
 
 Codex hook configuration can be installed as a user-level Codex plugin.
@@ -254,7 +292,7 @@ Check the installed hook environment with:
 agent-context-graph doctor --runtime codex --connector skills-graph --connector actions-graph --connector sessions-graph
 ```
 
-Keep graph credentials in the process environment, not in plugin hook files. Runtime hooks use `memgraph-toolbox` defaults unless the Codex process has `MEMGRAPH_*` variables set.
+Graph credentials live in `~/.config/context-graph/config.toml` (written by `bootstrap`/`config set`), not in plugin hook files or the process environment — hooks read that file at runtime. See [Configuration](#configuration).
 
 ### Claude Code Plugin
 
@@ -353,9 +391,11 @@ All runtime adapters emit runtime-agnostic `Event` dataclasses:
 
 | Connector | Graph Component | Events Handled |
 |-----------|----------------|----------------|
-| `SkillGraphConnector` | skills-graph | Tool events matching skill access/search operations |
+| `SkillGraphConnector` | [skills-graph](../skills-graph/) | Tool/message events matching skill access/search operations |
+| `ActionsGraphConnector` | [actions-graph](../actions-graph/) | Session, tool, message, subagent, and error events → action nodes |
+| `SessionsGraphConnector` | [sessions-graph](../sessions-graph/) | `SessionStartEvent`/`SessionEndEvent` → `(:User)`, `(:Session)`, `HAD_SESSION`; marks sessions for reconciliation on end |
 
-Additional graph connectors should live in the packages that own those graph schemas.
+The installed plugin wires **all three** (`--connector skills-graph --connector actions-graph --connector sessions-graph`). Each connector lives in the package that owns its graph schema; additional connectors should too.
 
 ### Adding a New Runtime Adapter
 
@@ -365,6 +405,7 @@ Implement `RuntimeAdapter`:
 from agent_context_graph import AgentLink, ToolStartEvent
 from agent_context_graph.protocols import RuntimeAdapter
 
+
 class MyRuntimeAdapter(RuntimeAdapter):
     def __init__(self, link: AgentLink, session_id: str):
         self._link = link
@@ -384,6 +425,80 @@ class MyRuntimeAdapter(RuntimeAdapter):
         )
 ```
 
+### Adding a New Command-Hook Runtime Adapter
+
+The pattern above fits **in-process** runtimes — something that calls your Python code directly (an SDK callback, an embedded framework). **Command-hook** runtimes are different: the harness invokes an external command with a JSON payload on stdin (Claude Code, Codex), rather than calling into your process.
+
+Three pieces beyond `RuntimeAdapter` itself, exactly as `adapters/claude_code.py` and `adapters/codex.py` implement them:
+
+1. **A payload translator.** Same idea as `RuntimeAdapter.get_runtime_hooks()`, but the input is the harness's raw JSON payload rather than a native callback. Map each of the harness's hook event names to the matching `Event` subclass and call `link.emit(...)`.
+2. **A hook-config generator** (`build_hooks_config(command)`). Builds whatever config shape the harness expects for wiring hooks, pointing every hook at your CLI entry point.
+3. **A response function** (`response_for_payload(payload)`). Returns the JSON the harness expects back on stdout, or `None`.
+
+The stdin-loading, connector-construction, and CLI-argument-parsing scaffolding around those three pieces is **shared** — `hooks/runner.py`'s `run_hook(plugin, argv)` does that for every registered runtime, so a new adapter doesn't write its own `main()` at all. Register your runtime as a **plugin** and the generic runner (plus `bootstrap`/`doctor`/`hook run`/`hook init`) picks it up automatically — no changes to `agent-context-graph` itself:
+
+```python
+# my_package/adapter.py
+from dataclasses import dataclass
+
+from agent_context_graph.protocols import RuntimeAdapter
+
+
+class MyCommandHookAdapter(RuntimeAdapter):
+    def __init__(self, link, session_id: str | None = None):
+        self._link = link
+        self._session_id = session_id
+
+    def get_runtime_hooks(self):
+        return build_hooks_config("my-runtime hook run my-runtime")
+
+    def handle_payload(self, payload: dict) -> None:
+        for event in self._events_from_payload(payload):
+            self._link.emit(event)
+
+    def _events_from_payload(self, payload: dict):
+        # Map the harness's own hook_event_name / payload shape to Event subclasses.
+        ...
+
+
+def build_hooks_config(command: str, *, timeout: int = 30) -> dict:
+    # Return whatever config format your harness expects, every hook pointing at `command`.
+    ...
+
+
+def response_for_payload(payload: dict) -> dict | None:
+    # Return the JSON your harness expects back, or None.
+    ...
+
+
+@dataclass(frozen=True)
+class MyRuntimePlugin:
+    name: str = "my-runtime"
+    adapter_class: type = MyCommandHookAdapter
+
+    def response_for_payload(self, payload: dict) -> dict | None:
+        return response_for_payload(payload)
+
+    def build_hooks_config(self, command: str, *, timeout: int = 30) -> dict:
+        return build_hooks_config(command, timeout=timeout)
+
+    # init(project_dir, connectors, **kwargs) is optional -- omit it if your
+    # runtime has no project-local hook-config file to generate (matching
+    # ClaudeCodeHooksAdapter's own plugin, which doesn't define one yet).
+
+
+PLUGIN = MyRuntimePlugin()
+```
+
+Then register it in your own package's `pyproject.toml` — this is the entire integration, no fork or PR against this repo required:
+
+```toml
+[project.entry-points."agent_context_graph.runtimes"]
+my-runtime = "my_package.adapter:PLUGIN"
+```
+
+Once installed, `agent-context-graph bootstrap --runtime my-runtime`, `doctor --runtime my-runtime`, `hook run my-runtime`, and `hook init my-runtime` (if `init` is implemented) all work exactly like the built-in Codex and Claude Code plugins — see `runtime_plugin.py` for the full protocol and `pyproject.toml`'s own `[project.entry-points."agent_context_graph.runtimes"]` for how Codex/Claude Code register themselves.
+
 ### Adding a New Graph Component
 
 Implement `GraphConnector` in the graph package:
@@ -392,6 +507,7 @@ Implement `GraphConnector` in the graph package:
 from agent_context_graph import EventType
 from agent_context_graph.protocols import GraphConnector
 
+
 class MyGraphConnector(GraphConnector):
     def supports(self, event):
         return event.event_type in {EventType.TOOL_START, EventType.TOOL_END}

{agent_context_graph-0.1.8 → agent_context_graph-0.2.0}/README.md

@@ -12,6 +12,8 @@ Runtime Adapter  ->  Event Protocol  ->  Graph Connector(s)
 
 Runtime plugins are the distribution layer for host-specific hook wiring. They install hooks, skills, and setup helpers for a runtime, then call Agent Context Graph. They are not graph components and should not encode graph-specific meaning.
 
+> **Just want to capture your Claude Code / Codex sessions?** Start with the [Context Graph guide](../README.md) — it walks through installing the plugin and wiring all the connectors end to end. This README covers the adapter layer itself and the in-process SDK path.
+
 ## Installation
 
 For command-hook runtimes such as Codex and Claude Code, prefer a user-level tool install:
@@ -88,6 +90,7 @@ from skills_graph.connector import SkillGraphConnector
 skills = SkillGraph()
 skills.setup()
 
+
 # 2. Define a tool whose name matches the SkillGraphConnector defaults
 @function_tool
 def get_skill(name: str) -> str:
@@ -96,6 +99,7 @@ def get_skill(name: str) -> str:
         return f"Skill '{name}' not found."
     return f"{skill.name}: {skill.description}\n{skill.content}"
 
+
 # 3. Wire up the link
 link = AgentLink()
 link.add_connector(SkillGraphConnector(skills))
@@ -143,64 +147,98 @@ Implemented:
 
 ### First-Time Plugin Setup
 
-For Codex and Claude Code plugins, the recommended first-run path is the bootstrap command. It installs the runtime package, checks Memgraph, installs the graph connector extra, and runs `doctor`.
+For Codex and Claude Code plugins, the recommended first-run path is the bootstrap command. It installs the runtime package (with the connector extras), checks Memgraph, and runs `doctor`.
 
 Prerequisites:
 
-- `uv` on `PATH`.
-- Memgraph running and reachable over Bolt. Defaults are `bolt://localhost:7687`, empty user/password, and database `memgraph`.
+- `uv` on `PATH`. (`uv` manages Python for the tool; if uv-managed Python downloads are blocked, install Python 3.10+ and rerun bootstrap.)
+- Memgraph running and reachable over Bolt. Defaults are `bolt://localhost:7687`, empty user/password, database `memgraph`. If it isn't running locally:
+
+  ```bash
+  docker run --rm -p 7687:7687 memgraph/memgraph
+  ```
 
-**Environment variables:**
+**1. Bootstrap all three connectors** (this is what the installed plugin wires into its hooks):
 
-| Variable | Default | Description |
-|---|---|---|
-| `MEMGRAPH_URL` | `bolt://localhost:7687` | Bolt URL — set to a remote host for non-local Memgraph |
-| `MEMGRAPH_USER` | `""` | Bolt username (service account) |
-| `MEMGRAPH_PASSWORD` | `""` | Bolt password or OAuth token |
-| `MEMGRAPH_DATABASE` | `memgraph` | Target database name |
-| `AGENT_CONTEXT_GRAPH_USER_ID` | _(none)_ | Human identity stored on Memory nodes — required for sessions-graph to associate memories with a user |
+```bash
+# Codex
+agent-context-graph bootstrap --runtime codex \
+  --connector skills-graph --connector actions-graph --connector sessions-graph
+
+# Claude Code
+agent-context-graph bootstrap --runtime claude-code \
+  --connector skills-graph --connector actions-graph --connector sessions-graph
+```
 
-If Memgraph is not running locally, start it first:
+The plugin wrapper script runs the same command (and falls back to `uvx` if the tool isn't installed yet):
 
 ```bash
-docker run --rm -p 7687:7687 memgraph/memgraph
+./scripts/bootstrap.sh
 ```
 
-`uv` manages Python for the tool. If uv-managed Python downloads are blocked in your environment, install Python 3.10+ and rerun bootstrap.
+**2. Configure identity and connection.** Bootstrap writes `~/.config/context-graph/config.toml`; hooks read their configuration from that file at runtime (see [Configuration](#configuration) — env vars are **not** read at hook time). Set your identity, which sessions-graph requires:
+
+```bash
+agent-context-graph config set identity.user_id "your-name"
+```
 
-For Codex:
+The Memgraph connection defaults to `bolt://localhost:7687`. For a remote or HA instance:
 
 ```bash
-agent-context-graph bootstrap --runtime codex --connector skills-graph
+agent-context-graph config set memgraph.url "neo4j://<coordinator-host>:7687"
+agent-context-graph config set memgraph.user "<user>"
+agent-context-graph config set memgraph.password        # prompts; stored 0600
+agent-context-graph config set memgraph.database "memgraph"
 ```
 
-For Claude Code:
+**3. Verify:**
 
 ```bash
-agent-context-graph bootstrap --runtime claude-code --connector skills-graph
+agent-context-graph config show
+agent-context-graph doctor --runtime claude-code \
+  --connector skills-graph --connector actions-graph --connector sessions-graph
 ```
 
-Expected successful doctor output looks like:
+Expected successful doctor output (use `--runtime codex` for Codex):
 
 ```text
 OK agent-context-graph executable: ...
 OK agent-context-graph: ...
+OK config: identity.user_id set
+OK memgraph: reachable
 OK connector:skills-graph: installed=...; memgraph=reachable
-OK runtime:codex: strict hook smoke passed
+OK connector:actions-graph: installed=...; memgraph=reachable
+OK connector:sessions-graph: installed=...; memgraph=reachable
+OK runtime:claude-code: strict hook smoke passed
 ```
 
-Use the matching runtime value when checking Claude Code:
+> **Reconciliation is a separate step.** The connectors capture session activity, but turning a session's text into extracted entities (a `:Person`/`:Organization` graph) is done out-of-band — see [sessions-graph § reconciliation](../sessions-graph/README.md#session-reconciliation). By default a finished session is marked `reconciliation_status = 'pending'` and `sessions-graph reconcile --pending` extracts it.
 
-```text
-OK runtime:claude-code: strict hook smoke passed
+### Configuration
+
+Bootstrap and the `config` command write `~/.config/context-graph/config.toml` (mode `0600`). **Hook subprocesses resolve their configuration from CLI flags and this file only — never from environment variables** (they don't inherit your shell), per [ADR 0002](docs/adr/0002-config-file-only-hook-resolution.md).
+
+```toml
+[identity]
+user_id = "your-name"
+
+[memgraph]
+url = "bolt://localhost:7687"
+user = ""
+password = ""
+database = "memgraph"
 ```
 
-The plugin wrapper scripts call the same bootstrap command. If `agent-context-graph` is not installed yet, they fall back to `uvx`:
+Manage it with:
 
 ```bash
-./scripts/bootstrap.sh
+agent-context-graph config show
+agent-context-graph config get memgraph.url
+agent-context-graph config set <key> <value>   # keys: identity.user_id, memgraph.{url,user,password,database}
 ```
 
+Environment variables (`MEMGRAPH_URL`, `MEMGRAPH_USER`, `MEMGRAPH_PASSWORD`, `MEMGRAPH_DATABASE`, `AGENT_CONTEXT_GRAPH_USER_ID`) are consulted **only at bootstrap time** — if set, `bootstrap` persists them into the config file. Exporting them later has no effect on running hooks; use `config set` instead.
+
 ### OpenAI Codex Plugin
 
 Codex hook configuration can be installed as a user-level Codex plugin.
@@ -233,7 +271,7 @@ Check the installed hook environment with:
 agent-context-graph doctor --runtime codex --connector skills-graph --connector actions-graph --connector sessions-graph
 ```
 
-Keep graph credentials in the process environment, not in plugin hook files. Runtime hooks use `memgraph-toolbox` defaults unless the Codex process has `MEMGRAPH_*` variables set.
+Graph credentials live in `~/.config/context-graph/config.toml` (written by `bootstrap`/`config set`), not in plugin hook files or the process environment — hooks read that file at runtime. See [Configuration](#configuration).
 
 ### Claude Code Plugin
 
@@ -332,9 +370,11 @@ All runtime adapters emit runtime-agnostic `Event` dataclasses:
 
 | Connector | Graph Component | Events Handled |
 |-----------|----------------|----------------|
-| `SkillGraphConnector` | skills-graph | Tool events matching skill access/search operations |
+| `SkillGraphConnector` | [skills-graph](../skills-graph/) | Tool/message events matching skill access/search operations |
+| `ActionsGraphConnector` | [actions-graph](../actions-graph/) | Session, tool, message, subagent, and error events → action nodes |
+| `SessionsGraphConnector` | [sessions-graph](../sessions-graph/) | `SessionStartEvent`/`SessionEndEvent` → `(:User)`, `(:Session)`, `HAD_SESSION`; marks sessions for reconciliation on end |
 
-Additional graph connectors should live in the packages that own those graph schemas.
+The installed plugin wires **all three** (`--connector skills-graph --connector actions-graph --connector sessions-graph`). Each connector lives in the package that owns its graph schema; additional connectors should too.
 
 ### Adding a New Runtime Adapter
 
@@ -344,6 +384,7 @@ Implement `RuntimeAdapter`:
 from agent_context_graph import AgentLink, ToolStartEvent
 from agent_context_graph.protocols import RuntimeAdapter
 
+
 class MyRuntimeAdapter(RuntimeAdapter):
     def __init__(self, link: AgentLink, session_id: str):
         self._link = link
@@ -363,6 +404,80 @@ class MyRuntimeAdapter(RuntimeAdapter):
         )
 ```
 
+### Adding a New Command-Hook Runtime Adapter
+
+The pattern above fits **in-process** runtimes — something that calls your Python code directly (an SDK callback, an embedded framework). **Command-hook** runtimes are different: the harness invokes an external command with a JSON payload on stdin (Claude Code, Codex), rather than calling into your process.
+
+Three pieces beyond `RuntimeAdapter` itself, exactly as `adapters/claude_code.py` and `adapters/codex.py` implement them:
+
+1. **A payload translator.** Same idea as `RuntimeAdapter.get_runtime_hooks()`, but the input is the harness's raw JSON payload rather than a native callback. Map each of the harness's hook event names to the matching `Event` subclass and call `link.emit(...)`.
+2. **A hook-config generator** (`build_hooks_config(command)`). Builds whatever config shape the harness expects for wiring hooks, pointing every hook at your CLI entry point.
+3. **A response function** (`response_for_payload(payload)`). Returns the JSON the harness expects back on stdout, or `None`.
+
+The stdin-loading, connector-construction, and CLI-argument-parsing scaffolding around those three pieces is **shared** — `hooks/runner.py`'s `run_hook(plugin, argv)` does that for every registered runtime, so a new adapter doesn't write its own `main()` at all. Register your runtime as a **plugin** and the generic runner (plus `bootstrap`/`doctor`/`hook run`/`hook init`) picks it up automatically — no changes to `agent-context-graph` itself:
+
+```python
+# my_package/adapter.py
+from dataclasses import dataclass
+
+from agent_context_graph.protocols import RuntimeAdapter
+
+
+class MyCommandHookAdapter(RuntimeAdapter):
+    def __init__(self, link, session_id: str | None = None):
+        self._link = link
+        self._session_id = session_id
+
+    def get_runtime_hooks(self):
+        return build_hooks_config("my-runtime hook run my-runtime")
+
+    def handle_payload(self, payload: dict) -> None:
+        for event in self._events_from_payload(payload):
+            self._link.emit(event)
+
+    def _events_from_payload(self, payload: dict):
+        # Map the harness's own hook_event_name / payload shape to Event subclasses.
+        ...
+
+
+def build_hooks_config(command: str, *, timeout: int = 30) -> dict:
+    # Return whatever config format your harness expects, every hook pointing at `command`.
+    ...
+
+
+def response_for_payload(payload: dict) -> dict | None:
+    # Return the JSON your harness expects back, or None.
+    ...
+
+
+@dataclass(frozen=True)
+class MyRuntimePlugin:
+    name: str = "my-runtime"
+    adapter_class: type = MyCommandHookAdapter
+
+    def response_for_payload(self, payload: dict) -> dict | None:
+        return response_for_payload(payload)
+
+    def build_hooks_config(self, command: str, *, timeout: int = 30) -> dict:
+        return build_hooks_config(command, timeout=timeout)
+
+    # init(project_dir, connectors, **kwargs) is optional -- omit it if your
+    # runtime has no project-local hook-config file to generate (matching
+    # ClaudeCodeHooksAdapter's own plugin, which doesn't define one yet).
+
+
+PLUGIN = MyRuntimePlugin()
+```
+
+Then register it in your own package's `pyproject.toml` — this is the entire integration, no fork or PR against this repo required:
+
+```toml
+[project.entry-points."agent_context_graph.runtimes"]
+my-runtime = "my_package.adapter:PLUGIN"
+```
+
+Once installed, `agent-context-graph bootstrap --runtime my-runtime`, `doctor --runtime my-runtime`, `hook run my-runtime`, and `hook init my-runtime` (if `init` is implemented) all work exactly like the built-in Codex and Claude Code plugins — see `runtime_plugin.py` for the full protocol and `pyproject.toml`'s own `[project.entry-points."agent_context_graph.runtimes"]` for how Codex/Claude Code register themselves.
+
 ### Adding a New Graph Component
 
 Implement `GraphConnector` in the graph package:
@@ -371,6 +486,7 @@ Implement `GraphConnector` in the graph package:
 from agent_context_graph import EventType
 from agent_context_graph.protocols import GraphConnector
 
+
 class MyGraphConnector(GraphConnector):
     def supports(self, event):
         return event.event_type in {EventType.TOOL_START, EventType.TOOL_END}

{agent_context_graph-0.1.8 → agent_context_graph-0.2.0}/docs/command-hooks.md

@@ -51,6 +51,37 @@ The generated hook command does not embed any Memgraph connection values. At run
 
 If Memgraph requires a password, provide `MEMGRAPH_PASSWORD` to the Codex process environment. `.codex/hooks.json` should not contain Memgraph credentials.
 
+For the Claude Code plugin, connection settings instead come from
+`~/.config/context-graph/config.toml` (see "Persistent hook configuration"
+below) rather than from the hook process's environment.
+
+### Persistent hook configuration
+
+`agent-context-graph config set/get/show` read and write
+`~/.config/context-graph/config.toml`, which hook subprocesses consult
+directly (CLI flag > config file > default; see ADR 0002). Supported keys:
+
+```text
+identity.user_id
+memgraph.url
+memgraph.user
+memgraph.password
+memgraph.database
+llm.openai_api_key
+llm.anthropic_api_key
+```
+
+The `llm.*` keys are only needed if you enable the `sessions-graph` connector
+with `auto_reconcile` (`SESSIONS_GRAPH_AUTO_RECONCILE=1` at connector
+construction time): reconciliation shells out to a detached
+`sessions-graph reconcile` subprocess that does LLM-backed entity extraction
+via LightRAG, and needs an `OPENAI_API_KEY` (or `ANTHROPIC_API_KEY`) the same
+way it needs Memgraph credentials — resolved from this config file and
+injected into that subprocess's environment explicitly, not inherited from
+ambient shell env (see ADR 0003). `agent-context-graph bootstrap` captures
+`OPENAI_API_KEY`/`ANTHROPIC_API_KEY` from its own environment into the config
+file automatically, the same way it already does for `MEMGRAPH_*`.
+
 To smoke test the generated command, copy the `"command"` value from `.codex/hooks.json` and run:
 
 ```bash

{agent_context_graph-0.1.8 → agent_context_graph-0.2.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "agent-context-graph"
-version = "0.1.8"
+version = "0.2.0"
 description = "Connect agent SDKs to context-graph components (actions-graph, skills-graph, etc.)"
 readme = "README.md"
 license = { text = "MIT" }
@@ -18,6 +18,10 @@ dependencies = [
 [project.scripts]
 agent-context-graph = "agent_context_graph.cli:main"
 
+[project.entry-points."agent_context_graph.runtimes"]
+codex = "agent_context_graph.adapters.codex:PLUGIN"
+claude-code = "agent_context_graph.adapters.claude_code:PLUGIN"
+
 [project.optional-dependencies]
 claude = [
     "claude-agent-sdk>=0.1.0",

{agent_context_graph-0.1.8 → agent_context_graph-0.2.0}/src/agent_context_graph/__init__.py

@@ -21,6 +21,8 @@ Quick Start::
     hooks = adapter.get_runtime_hooks()
 """
 
+from importlib import metadata
+
 from .events import (
     AgentEndEvent,
     AgentStartEvent,
@@ -39,6 +41,13 @@ from .events import (
 from .link import AgentLink
 from .protocols import GraphConnector, RuntimeAdapter
 
+try:
+    __version__ = metadata.version(__package__)
+except metadata.PackageNotFoundError:
+    # Case where package metadata is not available.
+    __version__ = ""
+del metadata  # optional, avoids polluting the results of dir(__package__)
+
 __all__ = [
     "AgentEndEvent",
     "AgentLink",
@@ -56,6 +65,5 @@ __all__ = [
     "SessionStartEvent",
     "ToolEndEvent",
     "ToolStartEvent",
+    "__version__",
 ]
-
-__version__ = "0.1.0"