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

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

@@ -181,14 +181,10 @@ cython_debug/
 # Local agent hook configuration
 /.codex/
 /.claude/settings.local.json
-/AGENTS.md
 /docs/agents/
-/context-graph/CONTEXT-MAP.md
-/context-graph/*/CONTEXT.md
-/context-graph/docs/adr/
-/context-graph/*/docs/adr/
 
 # Project specific files
 /enterprise-context/sic-agent/sic-scrapper/output/*
-unstructured2graph/docs/adr/
-unstructured2graph/CONTEXT.md
+
+# deepeval writes run caches and telemetry here; build artifacts, not source.
+.deepeval/

agent_context_graph-0.3.1/CONTEXT.md

@@ -0,0 +1,97 @@
+# Agent Context Graph
+
+Adapter layer for Context Graph components. Normalizes agent SDK + runtime activity into events, routes to graph connectors.
+
+## Language
+
+**Agent Context Graph**:
+Adapter layer normalizing agent SDK + runtime activity into events, routing to graph connectors.
+_Avoid_: Graph storage, skills graph, memory store
+
+**Graph Connector**:
+Integration point, owned by a graph component, deciding which normalized events matter to it + persisting their meaning.
+_Avoid_: Adapter, hook, writer
+
+**Agent Development SDK**:
+Framework for building agent apps; integrations usually attach via in-process callbacks/hook objects.
+_Avoid_: Runtime hook, command hook
+
+**Runtime Hook**:
+Hook emitted by an agent runtime around an already-running session, often via external command + JSON payload.
+_Avoid_: Agent development SDK
+
+**Runtime Adapter**:
+Integration point translating one SDK/runtime-hook shape into shared event protocol.
+_Avoid_: Graph connector, storage adapter
+
+**Runtime Plugin**:
+Host-specific distribution package installing runtime hooks, skills, commands, setup helpers, other host-native integration files.
+_Avoid_: Graph component, graph connector, storage layer
+
+**Codex Plugin**:
+Runtime Plugin for OpenAI Codex; wires Codex lifecycle hooks to an Agent Context Graph runtime adapter entrypoint.
+_Avoid_: Codex graph, skills graph plugin
+
+**Claude Code Plugin**:
+Runtime Plugin for Claude Code; wires Claude Code lifecycle hooks to an Agent Context Graph runtime adapter entrypoint.
+_Avoid_: Claude graph, skills graph plugin
+
+**Event Protocol**:
+Runtime-agnostic set of agent activity events, emitted by runtime adapters, consumed by graph connectors.
+_Avoid_: Graph event, graph protocol, hook payload, callback data
+
+**Agent Session**:
+Runtime-side unit of agent activity grouping related events under shared session identifier.
+_Avoid_: Session node
+
+**Hook Configuration**:
+Persistent TOML file supplying identity + connection settings to hook subprocesses. Default path `~/.config/context-graph/config.toml`; `CONTEXT_GRAPH_CONFIG` may select another file. At hook runtime, config values come only from selected file. Env var selects file; never supplies a value from it.
+_Avoid_: env config, runtime config, shell config
+
+**Runtime Registration**:
+Python object implementing `RuntimeCLIPlugin`. Package publishes it via `agent_context_graph.runtimes` entry-point group. CLI resolves runtime name through it to find adapter, hook response, hook config, optional initializer.
+
+Not a **Runtime Plugin**: plugin installs host-facing files; registration lets Agent Context Graph discover runtime support via `importlib.metadata.entry_points()`. Adding one needs no central registry change.
+_Avoid_: Runtime Plugin (already means distribution package), Runtime Adapter (a Runtime Registration *references* one via `adapter_class`, isn't one)
+
+**Tool Registration**:
+Object implementing `Tool` (`tools.py`): a name, a description the model reads, an input schema, the connector whose graph it reads, an optional session-start hint, and `call(arguments, config)`. A graph component publishes it via the `agent_context_graph.tools` entry-point group; `agent-context-graph mcp` serves every registered tool, and the CLI runs one by name. Identity + connection come from **Hook Configuration**, never from tool arguments.
+_Avoid_: MCP tool (the protocol it is served over, not the thing), Graph Connector (writes events; a tool reads)
+
+## Relationships
+
+- **Agent Context Graph** belongs to broader **Context Graph** family.
+- **Agent Context Graph** routes events to graph connectors owned by graph components.
+- **Graph Connector** consumes normalized events emitted by **Agent Context Graph**.
+- **Agent Development SDK** integration + **Runtime Hook** integration both use a **Runtime Adapter** to emit same event protocol.
+- **Runtime Plugin** = deployment surface for runtime hooks/setup helpers; not a graph component.
+- **Codex Plugin** installs Codex hook wiring invoking the Codex runtime adapter command.
+- **Claude Code Plugin** installs Claude Code hook wiring invoking the Claude Code runtime adapter command.
+- **Event Protocol** carries agent activity, not graph semantics.
+- **Agent Session** may be persisted as a session node by a graph component; **Event Protocol** only carries the session identifier.
+- Tool/message events carry `agent_name` when runtime identifies a subagent. Agent Context Graph only transports this id; Graph Connectors decide how to use it. Codex adapter doesn't yet handle subagent lifecycle/ids ([#275](https://github.com/memgraph/ai-toolkit/issues/275)).
+- Runtime Plugin's generated command calls `hook run <name>`. CLI resolves name via Runtime Registration; plugin never names an adapter class directly.
+- Built-in Runtime Registrations: `codex`, `claude-code`. Other packages may publish more.
+
+## Example dialogue
+
+> **Dev:** "Should Agent Context Graph write the skill usage edge?"
+> **Domain expert:** "No. Agent Context Graph emits the tool event; Skills Graph decides whether that event represents skill usage."
+
+> **Dev:** "Are OpenAI Agents SDK and Codex hooks the same kind of integration?"
+> **Domain expert:** "No. OpenAI Agents SDK is for agent development; Codex hooks are runtime hooks. Both become normalized events before graph connectors see them."
+
+> **Dev:** "Should the Codex plugin know how to write skill usage?"
+> **Domain expert:** "No. Plugin installs hook wiring. Codex runtime adapter emits events. Skills Graph decides if those events mean skill usage."
+
+## Flagged ambiguities
+
+- "graph" = umbrella **Context Graph** family or specific component? Resolved: **Agent Context Graph** = adapter layer only, never persistence.
+- "connector" can sound like generic transport plumbing. Resolved: **Graph Connector** owns graph-specific event interpretation.
+- "adapter" can mean SDK integrations or runtime hooks. Resolved: **Runtime Adapter** = anything translating agent activity into shared event protocol.
+- "SDK adapter" too narrow: Codex command hooks are runtime hooks, not SDK callbacks. Resolved: code/docs use **Runtime Adapter**.
+- "event" shouldn't carry graph nomenclature. Resolved: graph meaning assigned by **Graph Connectors**, not **Event Protocol**.
+- "Session" = activity or graph state? Use **Agent Session** for activity, "session node" for persisted state.
+- "Plugin" can sound like a graph extension. Use **Runtime Plugin** for host-specific distribution; Graph Connectors own graph interpretation.
+- Entry-point discovery = **Runtime Registration**, not a runtime/CLI plugin ([#269](https://github.com/memgraph/ai-toolkit/issues/269)).
+- Code hasn't fully caught up to **Runtime Adapter** terminology: Event Protocol's `source_sdk` field (`events.py`, set by all 4 adapters, read by Actions Graph's connector) still names the rejected term (ADR 0001). Rename to e.g. `source_adapter` tracked, not done.

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: agent-context-graph
-Version: 0.2.0
+Version: 0.3.1
 Summary: Connect agent SDKs to context-graph components (actions-graph, skills-graph, etc.)
 License: MIT
 License-File: LICENSE
@@ -12,9 +12,12 @@ Requires-Python: >=3.10
 Requires-Dist: memgraph-toolbox>=0.1.11
 Provides-Extra: claude
 Requires-Dist: claude-agent-sdk>=0.1.0; extra == 'claude'
+Provides-Extra: mcp
+Requires-Dist: mcp<3,>=1.23.0; extra == 'mcp'
 Provides-Extra: openai
 Requires-Dist: openai-agents>=0.1.0; extra == 'openai'
 Provides-Extra: test
+Requires-Dist: mcp<3,>=1.23.0; extra == 'test'
 Requires-Dist: pytest-asyncio>=0.24.0; extra == 'test'
 Requires-Dist: pytest>=9.0.3; extra == 'test'
 Description-Content-Type: text/markdown
@@ -40,9 +43,11 @@ Runtime plugins are the distribution layer for host-specific hook wiring. They i
 For command-hook runtimes such as Codex and Claude Code, prefer a user-level tool install:
 
 ```bash
-uv tool install agent-context-graph --with "skills-graph[agent-context-graph]"
+uv tool install "agent-context-graph[mcp]" --with "skills-graph[agent-context-graph]"
 ```
 
+The `mcp` extra is what `agent-context-graph mcp` serves [recall](#recall-memory-for-the-harnesss-model) with.
+
 Or use the plugin bootstrap scripts; they fall back to `uvx` if the tool is not installed yet.
 
 For SDK usage inside an application:
@@ -176,7 +181,7 @@ Prerequisites:
 - 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
+  docker run --rm -p 7687:7687 memgraph/memgraph-mage
   ```
 
 **1. Bootstrap all three connectors** (this is what the installed plugin wires into its hooks):
@@ -230,6 +235,8 @@ OK memgraph: reachable
 OK connector:skills-graph: installed=...; memgraph=reachable
 OK connector:actions-graph: installed=...; memgraph=reachable
 OK connector:sessions-graph: installed=...; memgraph=reachable
+OK embeddings: BAAI/bge-small-en-v1.5 (384 dimensions) inside Memgraph
+OK mcp: serves recall
 OK runtime:claude-code: strict hook smoke passed
 ```
 
@@ -248,17 +255,90 @@ url = "bolt://localhost:7687"
 user = ""
 password = ""
 database = "memgraph"
+
+[llm]
+openai_api_key = ""
+anthropic_api_key = ""
+
+[reconcile]
+auto_reconcile = true
+
+[recall]
+embedding_model = "BAAI/bge-small-en-v1.5"
+turns_k = "8"
 ```
 
+`[llm]` and `[reconcile]` are only relevant if you enable sessions-graph's
+auto-trigger reconciliation (see
+[sessions-graph § reconciliation](../sessions-graph/README.md#session-reconciliation)).
+`[reconcile]` is omitted entirely from a freshly-bootstrapped file — absent
+means "never configured," distinct from an explicit `auto_reconcile = false`.
+`[recall]` is optional too: without it, recall runs with the widths the
+benchmark measured; see [Recall](#recall-memory-for-the-harnesss-model).
+
 Manage it with:
 
 ```bash
 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}
+agent-context-graph config set <key> <value>
+# keys: identity.user_id, memgraph.{url,user,password,database},
+#       llm.{openai_api_key,anthropic_api_key}, reconcile.auto_reconcile,
+#       recall.embedding_model
 ```
 
-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.
+Environment variables (`MEMGRAPH_URL`, `MEMGRAPH_USER`, `MEMGRAPH_PASSWORD`, `MEMGRAPH_DATABASE`, `AGENT_CONTEXT_GRAPH_USER_ID`, `OPENAI_API_KEY`, `ANTHROPIC_API_KEY`) 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.
+
+`reconcile.auto_reconcile` is the one exception: `bootstrap` never captures
+`SESSIONS_GRAPH_AUTO_RECONCILE` from the environment, and re-running
+`bootstrap` preserves whatever it's currently set to rather than resetting it.
+Unlike the keys above, nobody has that env var exported for an unrelated
+reason — it's only ever set via `agent-context-graph config set
+reconcile.auto_reconcile true`.
+
+### Recall: memory for the harness's model
+
+The hooks write sessions into Memgraph; recall reads them back. With
+sessions-graph installed, `agent-context-graph mcp` serves a `recall(question)`
+tool over stdio MCP, and the Codex and Claude Code plugins bundle that server,
+so installing a plugin is all it takes. The tool returns context, not an answer:
+the dated messages and facts from the user's own sessions that match the
+question, behind a header with the rules for reading them. The harness's model
+answers from those rows.
+
+At session start the hook adds one line to the model's context saying the tool
+exists. It never pushes retrieved content; the model calls `recall` when a
+question needs memory.
+
+The same search from a shell:
+
+```bash
+agent-context-graph recall "what did we decide about the deploy window?"
+agent-context-graph recall --json "..."    # the turns and facts as JSON
+```
+
+Whose memory is searched comes from `identity.user_id` in the config file, never
+from the tool call, so a model can only read its own user's sessions.
+`[recall]` overrides the search's lanes and widths, all optional:
+
+| Key | Default | What it sets |
+|---|---|---|
+| `embedding_model` | `BAAI/bge-small-en-v1.5` | The model Memgraph embeds with; set with `config set recall.embedding_model` |
+| `lanes` | all five | Comma-separated subset of `turns,text,entities,facts,user_facts` |
+| `turns_k`, `text_k` | `8`, `8` | Messages found by vector and by text search |
+| `entities_k`, `edges_per_entity` | `15`, `6` | Entities matched, and facts read from each |
+| `facts_k`, `fact_turns_k` | `15`, `8` | Facts matched, and the messages they were read from |
+| `user_fact_types`, `user_facts_k` | `2`, `30` | Relation types gathered whole, for counting questions |
+| `turn_chars` | `1500` | Characters shown per message |
+
+Recall needs Memgraph with MAGE (`memgraph/memgraph-mage`) for its vector lanes;
+without it, it answers from text search and says so. `doctor` checks both
+(`embeddings` and `mcp`).
+
+**What the model sees.** A tool result carries the rendered text only. Claude
+Code and Codex both show the model a result's `structuredContent` JSON
+*instead of* its text when both are present, and the text is the form recall
+was benchmarked in; the JSON is what `--json` prints.
 
 ### OpenAI Codex Plugin
 
@@ -278,13 +358,14 @@ Plugin source:
 context-graph/plugins/agent-context-graph-codex
 ```
 
-Register the public Git-backed marketplace:
+Register the public Git-backed marketplace and install the plugin:
 
 ```bash
 codex plugin marketplace add memgraph/ai-toolkit --sparse .agents/plugins
+codex plugin add context-graph@context-graph-plugins
 ```
 
-Then install or enable `context-graph` from the Codex plugin UI.
+Both are non-interactive; `codex plugin add` installs and enables the plugin in one step (`codex plugin list --json` confirms `"enabled": true`).
 
 Check the installed hook environment with:
 

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

@@ -19,9 +19,11 @@ Runtime plugins are the distribution layer for host-specific hook wiring. They i
 For command-hook runtimes such as Codex and Claude Code, prefer a user-level tool install:
 
 ```bash
-uv tool install agent-context-graph --with "skills-graph[agent-context-graph]"
+uv tool install "agent-context-graph[mcp]" --with "skills-graph[agent-context-graph]"
 ```
 
+The `mcp` extra is what `agent-context-graph mcp` serves [recall](#recall-memory-for-the-harnesss-model) with.
+
 Or use the plugin bootstrap scripts; they fall back to `uvx` if the tool is not installed yet.
 
 For SDK usage inside an application:
@@ -155,7 +157,7 @@ Prerequisites:
 - 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
+  docker run --rm -p 7687:7687 memgraph/memgraph-mage
   ```
 
 **1. Bootstrap all three connectors** (this is what the installed plugin wires into its hooks):
@@ -209,6 +211,8 @@ OK memgraph: reachable
 OK connector:skills-graph: installed=...; memgraph=reachable
 OK connector:actions-graph: installed=...; memgraph=reachable
 OK connector:sessions-graph: installed=...; memgraph=reachable
+OK embeddings: BAAI/bge-small-en-v1.5 (384 dimensions) inside Memgraph
+OK mcp: serves recall
 OK runtime:claude-code: strict hook smoke passed
 ```
 
@@ -227,17 +231,90 @@ url = "bolt://localhost:7687"
 user = ""
 password = ""
 database = "memgraph"
+
+[llm]
+openai_api_key = ""
+anthropic_api_key = ""
+
+[reconcile]
+auto_reconcile = true
+
+[recall]
+embedding_model = "BAAI/bge-small-en-v1.5"
+turns_k = "8"
 ```
 
+`[llm]` and `[reconcile]` are only relevant if you enable sessions-graph's
+auto-trigger reconciliation (see
+[sessions-graph § reconciliation](../sessions-graph/README.md#session-reconciliation)).
+`[reconcile]` is omitted entirely from a freshly-bootstrapped file — absent
+means "never configured," distinct from an explicit `auto_reconcile = false`.
+`[recall]` is optional too: without it, recall runs with the widths the
+benchmark measured; see [Recall](#recall-memory-for-the-harnesss-model).
+
 Manage it with:
 
 ```bash
 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}
+agent-context-graph config set <key> <value>
+# keys: identity.user_id, memgraph.{url,user,password,database},
+#       llm.{openai_api_key,anthropic_api_key}, reconcile.auto_reconcile,
+#       recall.embedding_model
 ```
 
-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.
+Environment variables (`MEMGRAPH_URL`, `MEMGRAPH_USER`, `MEMGRAPH_PASSWORD`, `MEMGRAPH_DATABASE`, `AGENT_CONTEXT_GRAPH_USER_ID`, `OPENAI_API_KEY`, `ANTHROPIC_API_KEY`) 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.
+
+`reconcile.auto_reconcile` is the one exception: `bootstrap` never captures
+`SESSIONS_GRAPH_AUTO_RECONCILE` from the environment, and re-running
+`bootstrap` preserves whatever it's currently set to rather than resetting it.
+Unlike the keys above, nobody has that env var exported for an unrelated
+reason — it's only ever set via `agent-context-graph config set
+reconcile.auto_reconcile true`.
+
+### Recall: memory for the harness's model
+
+The hooks write sessions into Memgraph; recall reads them back. With
+sessions-graph installed, `agent-context-graph mcp` serves a `recall(question)`
+tool over stdio MCP, and the Codex and Claude Code plugins bundle that server,
+so installing a plugin is all it takes. The tool returns context, not an answer:
+the dated messages and facts from the user's own sessions that match the
+question, behind a header with the rules for reading them. The harness's model
+answers from those rows.
+
+At session start the hook adds one line to the model's context saying the tool
+exists. It never pushes retrieved content; the model calls `recall` when a
+question needs memory.
+
+The same search from a shell:
+
+```bash
+agent-context-graph recall "what did we decide about the deploy window?"
+agent-context-graph recall --json "..."    # the turns and facts as JSON
+```
+
+Whose memory is searched comes from `identity.user_id` in the config file, never
+from the tool call, so a model can only read its own user's sessions.
+`[recall]` overrides the search's lanes and widths, all optional:
+
+| Key | Default | What it sets |
+|---|---|---|
+| `embedding_model` | `BAAI/bge-small-en-v1.5` | The model Memgraph embeds with; set with `config set recall.embedding_model` |
+| `lanes` | all five | Comma-separated subset of `turns,text,entities,facts,user_facts` |
+| `turns_k`, `text_k` | `8`, `8` | Messages found by vector and by text search |
+| `entities_k`, `edges_per_entity` | `15`, `6` | Entities matched, and facts read from each |
+| `facts_k`, `fact_turns_k` | `15`, `8` | Facts matched, and the messages they were read from |
+| `user_fact_types`, `user_facts_k` | `2`, `30` | Relation types gathered whole, for counting questions |
+| `turn_chars` | `1500` | Characters shown per message |
+
+Recall needs Memgraph with MAGE (`memgraph/memgraph-mage`) for its vector lanes;
+without it, it answers from text search and says so. `doctor` checks both
+(`embeddings` and `mcp`).
+
+**What the model sees.** A tool result carries the rendered text only. Claude
+Code and Codex both show the model a result's `structuredContent` JSON
+*instead of* its text when both are present, and the text is the form recall
+was benchmarked in; the JSON is what `--json` prints.
 
 ### OpenAI Codex Plugin
 
@@ -257,13 +334,14 @@ Plugin source:
 context-graph/plugins/agent-context-graph-codex
 ```
 
-Register the public Git-backed marketplace:
+Register the public Git-backed marketplace and install the plugin:
 
 ```bash
 codex plugin marketplace add memgraph/ai-toolkit --sparse .agents/plugins
+codex plugin add context-graph@context-graph-plugins
 ```
 
-Then install or enable `context-graph` from the Codex plugin UI.
+Both are non-interactive; `codex plugin add` installs and enables the plugin in one step (`codex plugin list --json` confirms `"enabled": true`).
 
 Check the installed hook environment with:
 

agent_context_graph-0.3.1/docs/adr/0001-runtime-adapter-terminology.md

@@ -0,0 +1,3 @@
+# Use Runtime Adapter terminology
+
+Agent Context Graph supports agent development SDK integrations (OpenAI Agents SDK, Claude Agent SDK) and runtime hook integrations (Codex command hooks). We use **Runtime Adapter** as canonical term: covers both integration shapes. **SDK Adapter** wrongly implies every adapter attaches to an agent development SDK. Keeps Event Protocol independent of whether events came from in-process callbacks or command-hook payloads.

agent_context_graph-0.3.1/docs/adr/0002-config-file-only-hook-resolution.md

@@ -0,0 +1,7 @@
+# Config file as the sole runtime source for hook subprocesses
+
+Agent runtimes (Claude Code, Codex) spawn hook commands as non-interactive subprocesses — don't source shell profile files (`~/.zshrc`, `~/.bashrc`). Env vars set only there never reach hook processes. Instead of documenting fragile workarounds ("put exports in `~/.zshenv`"): hook subprocesses resolve config exclusively from a persistent file at `~/.config/context-graph/config.toml` (after CLI flags). Env vars not consulted at hook runtime — only a write-time convenience during `bootstrap`/`config set`, which persist values to the config file.
+
+Avoids drift between what `doctor` sees (interactive shell, env vars present) and what hooks see (subprocess, env vars absent). One canonical way to configure hooks: the config file.
+
+**Amended by** ADR 0003 (env var may select *which* config file is read, never what's in it) and ADR 0005 (config file also covers LLM API keys, resolved values passed as explicit `env=` to a further subprocess a hook spawns). Both preserve this ADR's core guarantee: config *values* still come only from the file.

agent_context_graph-0.3.1/docs/adr/0003-config-path-override.md

@@ -0,0 +1,26 @@
+# An environment variable may select the config file, never its contents
+
+ADR 0002 made config file sole runtime source for hook subprocesses; env vars not consulted at hook runtime. Still true of config *values*. This ADR carves one exception: `CONTEXT_GRAPH_CONFIG` selects **which file** is read.
+
+## Why the exception is needed
+
+Config path was single global (`~/.config/context-graph/config.toml`), no override. Hooks resolve everything from it -> pointing one Claude Code session at a different Memgraph meant rewriting that file, redirecting **every** session on the machine, not just the intended one.
+
+Not hypothetical: found while building eval gold slice (drives real session against dedicated eval instance). With global config temporarily repointed, an unrelated Claude Code session's activity got recorded into the eval graph — exactly the ambient-session pollution that decision was meant to prevent. Mechanism defeated its own purpose.
+
+No way to isolate a session short of changing `HOME` or running in a container.
+
+## Why it doesn't contradict ADR 0002
+
+ADR 0002 was about **ambient** environment: hook subprocesses don't source shell profiles, so `~/.zshrc` values never reached them, and `doctor` (interactive, env present) disagreed with hooks (subprocess, env absent). That ADR removed config depending on where a process happened to launch from.
+
+A config *path* handed down by the process spawning the session is the opposite: explicit, set by parent for its own child, drift-free — nothing ambient to drift from. `doctor` and the hooks it inspects agree by passing the same variable.
+
+Distinction: **which file** vs **what's in it**. Values still come only from the file — ADR 0002's guarantee intact.
+
+## Consequences
+
+- Callers needing an isolated session write their own config file, pass its path. `context_graph_eval.live.hooks_pointed_at` does this.
+- Unset (normal case): behavior unchanged.
+- `config set`/`bootstrap` write to the overridden path when set — makes a temporary config usable.
+- `doctor` inspects whichever file the variable names — a session under an override diagnosable with same tool.

agent_context_graph-0.3.1/docs/adr/0004-user-id-in-session-start-event.md

@@ -0,0 +1,3 @@
+# Add user_id to SessionStartEvent
+
+Event Protocol's `SessionStartEvent` carried no user identity. Memory Graph needs to own every `Memory` to a user node; Actions Graph + Skills Graph eventually need same. Instead of configuring user identity at `MemoryGraph` init time (couples identity to one component) or a caller-supplied resolver: add optional `user_id` field to `SessionStartEvent`. Keeps identity in shared event stream — all graph connectors access it, no breakage for existing callers that don't supply it.

agent_context_graph-0.3.1/docs/adr/0005-config-file-covers-llm-key-and-subprocess-env.md

@@ -0,0 +1,13 @@
+# Config file also covers LLM API keys; explicit env for spawned subprocesses
+
+ADR 0002 made `~/.config/context-graph/config.toml` sole runtime source for hook subprocess config: identity + Memgraph connection settings. Resolution happens as constructor kwargs passed directly to `SkillGraph`/`SessionsGraph`/`ActionsGraph` inside hook process — never written back to that process's `os.environ`.
+
+`SessionsGraphConnector` (sessions-graph) spawns a **further** detached subprocess on `SESSION_END` when `auto_reconcile` enabled: `sessions-graph reconcile --session <id>`, LLM-backed entity extraction via LightRAG. Plain `subprocess.Popen(...)`, no explicit `env=` -> child only inherited whatever ambient `os.environ` parent hook process had — which, per ADR 0002, excludes resolved Memgraph config, and never had a path to an LLM API key at all (LightRAG's default `llm_model_func` reads `OPENAI_API_KEY` straight from `os.environ`, raises if unset).
+
+Decided:
+
+1. Extend `HookConfig`/`config.toml` with `[llm]` section (`openai_api_key`, `anthropic_api_key`), resolved via `resolve_llm_env()`, mirroring `resolve_memgraph_env()`. `bootstrap` captures these from `OPENAI_API_KEY`/`ANTHROPIC_API_KEY` in env at write time, same as Memgraph credentials — env vars stay write-time convenience only, never consulted at hook runtime.
+2. Spawn site (`sessions_graph.connector._spawn_detached`, env from `_child_env`) builds **explicit `env=`** for child: copy of current `os.environ` overlaid with non-empty `resolve_memgraph_env()`/`resolve_llm_env()` values. Guarantees detached subprocess gets what hook process resolved, regardless of harness's own ambient environment.
+3. Defense in depth: `sessions-graph reconcile` (standalone via cron/manual, not only hook-spawned) also best-effort fills same config-file values via `os.environ.setdefault` at startup — consistent whether invoked by hook or by hand. Optional import of `agent_context_graph`, no-op if not installed (sessions-graph's `reconciliation` extra doesn't require it).
+
+Same philosophy as ADR 0002 (config file canonical), closes the gap it missed: subprocesses spawned *by* a hook process, not just the hook process itself.

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

@@ -69,18 +69,29 @@ memgraph.password
 memgraph.database
 llm.openai_api_key
 llm.anthropic_api_key
+reconcile.auto_reconcile
 ```
 
-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
+The `llm.*` keys and `reconcile.auto_reconcile` are only needed if you enable
+the `sessions-graph` connector's auto-trigger reconciliation
+(`agent-context-graph config set reconcile.auto_reconcile true`):
+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 0005). `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_*`.
+`reconcile.auto_reconcile` is deliberately excluded from that automatic
+capture — unlike those keys, nobody has it exported for an unrelated reason,
+so it is only ever set via `config set reconcile.auto_reconcile true`.
+
+`reconcile.auto_reconcile` itself is read directly by
+`agent_context_graph.hooks.runner._add_sessions_graph_connector` on every hook
+invocation (`resolve_auto_reconcile()`), not just at bootstrap/write time —
+unlike the `llm.*`/`memgraph.*` keys, which are only ever overlaid into a
+child subprocess's environment.
 
 To smoke test the generated command, copy the `"command"` value from `.codex/hooks.json` and run:
 

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

@@ -1,6 +1,6 @@
 [project]
 name = "agent-context-graph"
-version = "0.2.0"
+version = "0.3.1"
 description = "Connect agent SDKs to context-graph components (actions-graph, skills-graph, etc.)"
 readme = "README.md"
 license = { text = "MIT" }
@@ -26,10 +26,14 @@ claude-code = "agent_context_graph.adapters.claude_code:PLUGIN"
 claude = [
     "claude-agent-sdk>=0.1.0",
 ]
+mcp = [
+    "mcp>=1.23.0,<3",
+]
 openai = [
     "openai-agents>=0.1.0",
 ]
 test = [
+    "mcp>=1.23.0,<3",
     "pytest>=9.0.3",
     "pytest-asyncio>=0.24.0",
 ]

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

@@ -42,7 +42,7 @@ from .link import AgentLink
 from .protocols import GraphConnector, RuntimeAdapter
 
 try:
-    __version__ = metadata.version(__package__)
+    __version__ = metadata.version(__package__ or __name__)
 except metadata.PackageNotFoundError:
     # Case where package metadata is not available.
     __version__ = ""