memgraph-context-graph 0.9.0__tar.gz → 0.10.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (91) hide show
  1. {memgraph_context_graph-0.9.0 → memgraph_context_graph-0.10.0}/CONTEXT.md +4 -0
  2. {memgraph_context_graph-0.9.0 → memgraph_context_graph-0.10.0}/PKG-INFO +105 -6
  3. {memgraph_context_graph-0.9.0 → memgraph_context_graph-0.10.0}/README.md +103 -4
  4. {memgraph_context_graph-0.9.0 → memgraph_context_graph-0.10.0}/pyproject.toml +2 -2
  5. {memgraph_context_graph-0.9.0 → memgraph_context_graph-0.10.0}/src/memgraph_context_graph/__init__.py +2 -0
  6. {memgraph_context_graph-0.9.0 → memgraph_context_graph-0.10.0}/src/memgraph_context_graph/adapters/_identity.py +22 -14
  7. {memgraph_context_graph-0.9.0 → memgraph_context_graph-0.10.0}/src/memgraph_context_graph/capture_log.py +35 -0
  8. memgraph_context_graph-0.10.0/src/memgraph_context_graph/capture_policy.py +194 -0
  9. {memgraph_context_graph-0.9.0 → memgraph_context_graph-0.10.0}/src/memgraph_context_graph/cli.py +160 -34
  10. memgraph_context_graph-0.10.0/src/memgraph_context_graph/connectors.py +115 -0
  11. memgraph_context_graph-0.10.0/src/memgraph_context_graph/forget.py +116 -0
  12. {memgraph_context_graph-0.9.0 → memgraph_context_graph-0.10.0}/src/memgraph_context_graph/hooks/runner.py +23 -18
  13. {memgraph_context_graph-0.9.0 → memgraph_context_graph-0.10.0}/src/memgraph_context_graph/link.py +12 -2
  14. memgraph_context_graph-0.10.0/src/memgraph_context_graph/session.py +84 -0
  15. {memgraph_context_graph-0.9.0 → memgraph_context_graph-0.10.0}/src/memgraph_context_graph/setup/agents.py +16 -4
  16. {memgraph_context_graph-0.9.0 → memgraph_context_graph-0.10.0}/src/memgraph_context_graph/setup/cli.py +27 -5
  17. {memgraph_context_graph-0.9.0 → memgraph_context_graph-0.10.0}/src/memgraph_context_graph/setup/engine.py +13 -1
  18. {memgraph_context_graph-0.9.0 → memgraph_context_graph-0.10.0}/src/memgraph_context_graph/setup/prompts.py +111 -6
  19. {memgraph_context_graph-0.9.0 → memgraph_context_graph-0.10.0}/src/memgraph_context_graph/setup/tool.py +9 -12
  20. memgraph_context_graph-0.10.0/src/memgraph_context_graph/setup/uninstall.py +245 -0
  21. {memgraph_context_graph-0.9.0 → memgraph_context_graph-0.10.0}/tests/fake_agent_cli.py +13 -3
  22. {memgraph_context_graph-0.9.0 → memgraph_context_graph-0.10.0}/tests/test_capture_log.py +14 -0
  23. memgraph_context_graph-0.10.0/tests/test_capture_policy.py +190 -0
  24. {memgraph_context_graph-0.9.0 → memgraph_context_graph-0.10.0}/tests/test_config_cli.py +27 -0
  25. memgraph_context_graph-0.10.0/tests/test_connectors.py +55 -0
  26. {memgraph_context_graph-0.9.0 → memgraph_context_graph-0.10.0}/tests/test_dev_scripts.py +3 -1
  27. {memgraph_context_graph-0.9.0 → memgraph_context_graph-0.10.0}/tests/test_hook_cli.py +16 -8
  28. {memgraph_context_graph-0.9.0 → memgraph_context_graph-0.10.0}/tests/test_identity.py +6 -7
  29. memgraph_context_graph-0.10.0/tests/test_session.py +85 -0
  30. {memgraph_context_graph-0.9.0 → memgraph_context_graph-0.10.0}/tests/test_setup.py +168 -15
  31. {memgraph_context_graph-0.9.0 → memgraph_context_graph-0.10.0}/tests/test_setup_docker.py +12 -0
  32. memgraph_context_graph-0.9.0/src/memgraph_context_graph/connectors.py +0 -71
  33. memgraph_context_graph-0.9.0/src/memgraph_context_graph/setup/uninstall.py +0 -116
  34. memgraph_context_graph-0.9.0/tests/test_runner_sessions_graph_connector.py +0 -81
  35. {memgraph_context_graph-0.9.0 → memgraph_context_graph-0.10.0}/.gitignore +0 -0
  36. {memgraph_context_graph-0.9.0 → memgraph_context_graph-0.10.0}/LICENSE +0 -0
  37. {memgraph_context_graph-0.9.0 → memgraph_context_graph-0.10.0}/docs/adr/0001-runtime-adapter-terminology.md +0 -0
  38. {memgraph_context_graph-0.9.0 → memgraph_context_graph-0.10.0}/docs/adr/0002-config-file-only-hook-resolution.md +0 -0
  39. {memgraph_context_graph-0.9.0 → memgraph_context_graph-0.10.0}/docs/adr/0003-config-path-override.md +0 -0
  40. {memgraph_context_graph-0.9.0 → memgraph_context_graph-0.10.0}/docs/adr/0004-user-id-in-session-start-event.md +0 -0
  41. {memgraph_context_graph-0.9.0 → memgraph_context_graph-0.10.0}/docs/adr/0005-config-file-covers-llm-key-and-subprocess-env.md +0 -0
  42. {memgraph_context_graph-0.9.0 → memgraph_context_graph-0.10.0}/docs/adr/0006-memory-tool-writes-explicit-memory.md +0 -0
  43. {memgraph_context_graph-0.9.0 → memgraph_context_graph-0.10.0}/docs/command-hooks.md +0 -0
  44. {memgraph_context_graph-0.9.0 → memgraph_context_graph-0.10.0}/docs/research/2026-10-codex-memory.md +0 -0
  45. {memgraph_context_graph-0.9.0 → memgraph_context_graph-0.10.0}/src/memgraph_context_graph/adapters/__init__.py +0 -0
  46. {memgraph_context_graph-0.9.0 → memgraph_context_graph-0.10.0}/src/memgraph_context_graph/adapters/_opencode_plugin.js +0 -0
  47. {memgraph_context_graph-0.9.0 → memgraph_context_graph-0.10.0}/src/memgraph_context_graph/adapters/_spec.py +0 -0
  48. {memgraph_context_graph-0.9.0 → memgraph_context_graph-0.10.0}/src/memgraph_context_graph/adapters/agent_mcp.py +0 -0
  49. {memgraph_context_graph-0.9.0 → memgraph_context_graph-0.10.0}/src/memgraph_context_graph/adapters/agent_memory.py +0 -0
  50. {memgraph_context_graph-0.9.0 → memgraph_context_graph-0.10.0}/src/memgraph_context_graph/adapters/antigravity_cli.py +0 -0
  51. {memgraph_context_graph-0.9.0 → memgraph_context_graph-0.10.0}/src/memgraph_context_graph/adapters/claude.py +0 -0
  52. {memgraph_context_graph-0.9.0 → memgraph_context_graph-0.10.0}/src/memgraph_context_graph/adapters/claude_code.py +0 -0
  53. {memgraph_context_graph-0.9.0 → memgraph_context_graph-0.10.0}/src/memgraph_context_graph/adapters/claude_code_memory.py +0 -0
  54. {memgraph_context_graph-0.9.0 → memgraph_context_graph-0.10.0}/src/memgraph_context_graph/adapters/codex.py +0 -0
  55. {memgraph_context_graph-0.9.0 → memgraph_context_graph-0.10.0}/src/memgraph_context_graph/adapters/codex_memory.py +0 -0
  56. {memgraph_context_graph-0.9.0 → memgraph_context_graph-0.10.0}/src/memgraph_context_graph/adapters/copilot_cli.py +0 -0
  57. {memgraph_context_graph-0.9.0 → memgraph_context_graph-0.10.0}/src/memgraph_context_graph/adapters/cursor.py +0 -0
  58. {memgraph_context_graph-0.9.0 → memgraph_context_graph-0.10.0}/src/memgraph_context_graph/adapters/grok.py +0 -0
  59. {memgraph_context_graph-0.9.0 → memgraph_context_graph-0.10.0}/src/memgraph_context_graph/adapters/openai.py +0 -0
  60. {memgraph_context_graph-0.9.0 → memgraph_context_graph-0.10.0}/src/memgraph_context_graph/adapters/opencode.py +0 -0
  61. {memgraph_context_graph-0.9.0 → memgraph_context_graph-0.10.0}/src/memgraph_context_graph/events.py +0 -0
  62. {memgraph_context_graph-0.9.0 → memgraph_context_graph-0.10.0}/src/memgraph_context_graph/hooks/__init__.py +0 -0
  63. {memgraph_context_graph-0.9.0 → memgraph_context_graph-0.10.0}/src/memgraph_context_graph/hooks/cli.py +0 -0
  64. {memgraph_context_graph-0.9.0 → memgraph_context_graph-0.10.0}/src/memgraph_context_graph/hooks/runtime_plugin.py +0 -0
  65. {memgraph_context_graph-0.9.0 → memgraph_context_graph-0.10.0}/src/memgraph_context_graph/mcp_server.py +0 -0
  66. {memgraph_context_graph-0.9.0 → memgraph_context_graph-0.10.0}/src/memgraph_context_graph/memory_backend.py +0 -0
  67. {memgraph_context_graph-0.9.0 → memgraph_context_graph-0.10.0}/src/memgraph_context_graph/protocols.py +0 -0
  68. {memgraph_context_graph-0.9.0 → memgraph_context_graph-0.10.0}/src/memgraph_context_graph/setup/__init__.py +0 -0
  69. {memgraph_context_graph-0.9.0 → memgraph_context_graph-0.10.0}/src/memgraph_context_graph/setup/memgraph.py +0 -0
  70. {memgraph_context_graph-0.9.0 → memgraph_context_graph-0.10.0}/src/memgraph_context_graph/setup/update.py +0 -0
  71. {memgraph_context_graph-0.9.0 → memgraph_context_graph-0.10.0}/src/memgraph_context_graph/spaces.py +0 -0
  72. {memgraph_context_graph-0.9.0 → memgraph_context_graph-0.10.0}/src/memgraph_context_graph/terminal.py +0 -0
  73. {memgraph_context_graph-0.9.0 → memgraph_context_graph-0.10.0}/src/memgraph_context_graph/tools.py +0 -0
  74. {memgraph_context_graph-0.9.0 → memgraph_context_graph-0.10.0}/tests/__init__.py +0 -0
  75. {memgraph_context_graph-0.9.0 → memgraph_context_graph-0.10.0}/tests/conftest.py +0 -0
  76. {memgraph_context_graph-0.9.0 → memgraph_context_graph-0.10.0}/tests/test_agent_memory_wiring.py +0 -0
  77. {memgraph_context_graph-0.9.0 → memgraph_context_graph-0.10.0}/tests/test_antigravity_cli_adapter.py +0 -0
  78. {memgraph_context_graph-0.9.0 → memgraph_context_graph-0.10.0}/tests/test_claude_code_adapter.py +0 -0
  79. {memgraph_context_graph-0.9.0 → memgraph_context_graph-0.10.0}/tests/test_codex_adapter.py +0 -0
  80. {memgraph_context_graph-0.9.0 → memgraph_context_graph-0.10.0}/tests/test_context_before_tool.py +0 -0
  81. {memgraph_context_graph-0.9.0 → memgraph_context_graph-0.10.0}/tests/test_copilot_cli_adapter.py +0 -0
  82. {memgraph_context_graph-0.9.0 → memgraph_context_graph-0.10.0}/tests/test_cursor_adapter.py +0 -0
  83. {memgraph_context_graph-0.9.0 → memgraph_context_graph-0.10.0}/tests/test_events.py +0 -0
  84. {memgraph_context_graph-0.9.0 → memgraph_context_graph-0.10.0}/tests/test_grok_adapter.py +0 -0
  85. {memgraph_context_graph-0.9.0 → memgraph_context_graph-0.10.0}/tests/test_link.py +0 -0
  86. {memgraph_context_graph-0.9.0 → memgraph_context_graph-0.10.0}/tests/test_opencode_adapter.py +0 -0
  87. {memgraph_context_graph-0.9.0 → memgraph_context_graph-0.10.0}/tests/test_plugin_hooks.py +0 -0
  88. {memgraph_context_graph-0.9.0 → memgraph_context_graph-0.10.0}/tests/test_runtime_plugin.py +0 -0
  89. {memgraph_context_graph-0.9.0 → memgraph_context_graph-0.10.0}/tests/test_spaces.py +0 -0
  90. {memgraph_context_graph-0.9.0 → memgraph_context_graph-0.10.0}/tests/test_terminal.py +0 -0
  91. {memgraph_context_graph-0.9.0 → memgraph_context_graph-0.10.0}/tests/test_tools.py +0 -0
@@ -74,6 +74,10 @@ _Avoid_: Runtime Plugin (already means distribution package), Runtime Adapter (a
74
74
  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 `memgraph_context_graph.tools` entry-point group; `memgraph-context-graph mcp` serves every registered tool, and the CLI runs one by name. Identity + connection come from the **Space Resolver** over **Hook Configuration**, never from tool arguments.
75
75
  _Avoid_: MCP tool (the protocol it is served over, not the thing), Graph Connector (writes events; a tool reads)
76
76
 
77
+ **Connector Registration**:
78
+ `ConnectorSpec` (`connectors.py`): a graph component's name, its graph class, how to build its **Graph Connector** from **Hook Configuration**, and an optional `doctor` check. Published via the `memgraph_context_graph.connectors` entry-point group; the hook runner, schema setup and `doctor` find connectors only through it. The hub keeps just what it needs before a component is installed: each installable connector's requirement (`INSTALLABLE`) and the default set.
79
+ _Avoid_: Component (the package), Graph Connector (the object a registration builds)
80
+
77
81
  ## Relationships
78
82
 
79
83
  - **Memgraph Context Graph** belongs to broader **Context Graph** family.
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.5
2
2
  Name: memgraph-context-graph
3
- Version: 0.9.0
3
+ Version: 0.10.0
4
4
  Summary: Connect agent SDKs to context-graph components (actions-graph, skills-graph, etc.)
5
5
  License: MIT
6
6
  License-File: LICENSE
@@ -9,7 +9,7 @@ Classifier: Programming Language :: Python :: 3.11
9
9
  Classifier: Programming Language :: Python :: 3.12
10
10
  Classifier: Programming Language :: Python :: 3.13
11
11
  Requires-Python: >=3.10
12
- Requires-Dist: memgraph-toolbox>=0.1.11
12
+ Requires-Dist: memgraph-toolbox>=0.2.2
13
13
  Requires-Dist: tomlkit<1,>=0.13
14
14
  Provides-Extra: claude
15
15
  Requires-Dist: claude-agent-sdk>=0.1.0; extra == 'claude'
@@ -203,7 +203,8 @@ memgraph-context-graph setup claude-code codex # just these agents
203
203
  memgraph-context-graph setup cursor --project-dir ~/work/billing
204
204
  memgraph-context-graph setup --plan # print the plan, change nothing
205
205
  memgraph-context-graph update [runtime ...] # upgrade the package, refresh the wiring and the schema
206
- memgraph-context-graph uninstall [runtime ...] # remove the wiring; the graph and config stay
206
+ memgraph-context-graph uninstall [runtime ...] # remove the wiring; asks about the graph, config and tool
207
+ memgraph-context-graph uninstall --all # the wiring, the graph, the config and the tool
207
208
  ```
208
209
 
209
210
  It finds or starts Memgraph (a `memgraph-mage` container with a volume, on a free port when 7687 is taken),
@@ -212,6 +213,14 @@ wires each agent, and runs `doctor`'s checks. Every step checks before it acts,
212
213
  missing. The TUI starts only when stdin and stdout are both terminals; the plugins' `scripts/bootstrap.sh`
213
214
  runs `setup <runtime> --no-tui`.
214
215
 
216
+ **Uninstalling.** `uninstall` always removes the wiring (plugins, hook files, MCP entries) and gives each
217
+ agent its own memory back. On a terminal it then asks, one question each and every answer defaulting to
218
+ keep, whether to delete the graph (setup's Memgraph container and its volume: every session, for good), the
219
+ config and capture-failure log, and the uv tool. Without a terminal only the flags remove more: `--graph`,
220
+ `--config`, `--tool`, or `--all` for the three. A Memgraph you run yourself is never touched; only the
221
+ container setup started, by name (`--memgraph-container`). On Windows the running tool can't remove itself,
222
+ so it prints the `uv tool uninstall` command to run next.
223
+
215
224
  **Updating.** Upgrading the package moves the code hooks and the MCP server run, but what setup wrote once stays
216
225
  as it was. `update` upgrades the uv tool and its connectors, then, with the new release, refreshes everything
217
226
  that is wired: Claude Code's and Codex's plugin (marketplace refreshed, plugin updated), each per-project agent's
@@ -256,9 +265,13 @@ OK connector:actions-graph: installed=...; memgraph=reachable
256
265
  OK connector:sessions-graph: installed=...; memgraph=reachable
257
266
  OK embeddings: BAAI/bge-small-en-v1.5 (384 dimensions) inside Memgraph
258
267
  OK mcp: serves recall
259
- OK runtime:claude-code: strict hook smoke passed
268
+ OK runtime:claude-code: connectors accept its probe event
269
+ OK plugin:claude-code: context-graph@context-graph-plugins installed and enabled
260
270
  ```
261
271
 
272
+ The `runtime:` probe runs the connectors inside `doctor` itself; `plugin:` is what says Claude Code (or Codex)
273
+ will actually call the hooks.
274
+
262
275
  > **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.
263
276
 
264
277
  ### Configuration
@@ -282,6 +295,11 @@ derive_model = "claude-sonnet-5-5"
282
295
 
283
296
  [capture]
284
297
  connectors = "skills-graph, actions-graph, sessions-graph"
298
+ exclude_projects = "~/clients/*, ~/personal"
299
+ exclude_tools = "TodoWrite, mcp__vault__*"
300
+
301
+ [redact]
302
+ ticket = 'ACME-[0-9]+'
285
303
 
286
304
  [reconcile]
287
305
  auto_reconcile = true
@@ -304,6 +322,8 @@ the model it calls (default `claude-sonnet-5-5` with Anthropic, `gpt-5` with Ope
304
322
  command names no `--connector`, from `skills-graph`, `actions-graph`,
305
323
  `sessions-graph` and `resources-graph`; unset means the first three, and
306
324
  an empty value enables none. Setup installs the ones it names.
325
+ The rest of `[capture]` and `[redact]` are the capture policy, applied to every
326
+ event before any connector stores it (see [Capture privacy](#capture-privacy)).
307
327
  `[reconcile]` is omitted entirely from a file setup wrote — absent
308
328
  means "never configured," distinct from an explicit `auto_reconcile = false`.
309
329
  `[recall]` is optional too: without it, recall runs with the widths the
@@ -323,11 +343,64 @@ memgraph-context-graph config show
323
343
  memgraph-context-graph config get memgraph.url
324
344
  memgraph-context-graph config set <key> <value>
325
345
  # keys: identity.user_id, memgraph.{url,user,password,database},
326
- # llm.{openai_api_key,anthropic_api_key,derive_model}, capture.connectors,
346
+ # llm.{openai_api_key,anthropic_api_key,derive_model},
347
+ # capture.{connectors,redact,max_chars,exclude_tools,exclude_projects},
327
348
  # reconcile.auto_reconcile, recall.embedding_model, ontology.{path,derive}, memory.backend
328
- # [recall] widths and [extraction] are edited in the file.
349
+ # [recall] widths, [extraction] and [redact] patterns are edited in the file.
350
+ ```
351
+
352
+ ### Capture privacy
353
+
354
+ Every hook event passes the capture policy before any connector sees it, so
355
+ what it removes never reaches Memgraph:
356
+
357
+ - **`<private>…</private>`** is stripped from prompts, replies and tool input
358
+ and output. An unclosed `<private>` hides the rest of that text, and a prompt
359
+ that was nothing but private isn't stored at all.
360
+ - **Secrets are redacted** to `[REDACTED:<name>]`: AWS, GitHub, Anthropic,
361
+ OpenAI, Slack, Stripe and Google keys, JWTs, PEM private keys, passwords in
362
+ URLs, and the credentials in this config file. Each `[redact]` key adds a
363
+ pattern (a Python regular expression; quote it with single quotes).
364
+ `capture.redact = false` turns redaction off; `<private>` still applies.
365
+ - **Long text is clipped** at `capture.max_chars` characters per field
366
+ (default 100000; `0` for no limit).
367
+ - **`capture.exclude_tools`** drops those tools' calls and results, by exact
368
+ name or glob (`mcp__vault__*`).
369
+ - **`capture.exclude_projects`** captures nothing from a session whose working
370
+ directory is one of these paths or globs, or inside one (`~` expands). The
371
+ agent's own hooks still answer normally, and recall still works there.
372
+
373
+ Redaction is pattern-based: it catches known credential shapes, not every
374
+ secret. What a session stored before the policy existed stays as it was.
375
+ Library callers driving `AgentLink` directly pass a `CapturePolicy` themselves.
376
+
377
+ ### Forgetting sessions
378
+
379
+ ```bash
380
+ memgraph-context-graph forget session <session-id> [<session-id> ...]
381
+ memgraph-context-graph forget project ~/work/client-repo # every session whose working directory is in it
382
+ memgraph-context-graph forget project . --dry-run # list what matches, delete nothing
329
383
  ```
330
384
 
385
+ `forget` lists the matching sessions and asks before deleting (`--yes` skips the
386
+ question; without a terminal it is required). For each session it deletes, for
387
+ good and with no archive:
388
+
389
+ - what was captured: its Actions, the Agents only it used, its skill uses and
390
+ resource Touches;
391
+ - what was derived from it: its Chunks, entity mentions and extracted
392
+ relationships, any entity left with no other evidence, and the `anon-` User
393
+ made up for it;
394
+ - its lines in the local capture-failure log.
395
+
396
+ What anything else still backs stays: entities other sessions mention, Skills,
397
+ public Resources, and your memory files, including ones the session wrote (their
398
+ versions just stop naming it). A forgotten session leaves only a
399
+ `(:ForgottenSession {session_id})` marker, which stops a hook still running, a
400
+ reconciliation in progress, or a later resume of the same session from capturing
401
+ it again. It runs against your own graph; in Enterprise, shared spaces are not
402
+ touched.
403
+
331
404
  Hooks never read environment variables for these values, and neither does setup: it writes only
332
405
  `memgraph.url` and `identity.user_id`, from its flags or what it found. Everything else is set with
333
406
  `config set`, and setup leaves it alone when it rewrites the file.
@@ -713,6 +786,32 @@ class MyGraphConnector(GraphConnector):
713
786
  ...
714
787
  ```
715
788
 
789
+ Then register it, so hooks, schema setup and `doctor` can find it:
790
+
791
+ ```python
792
+ from memgraph_context_graph.connectors import ConnectorSpec
793
+
794
+ CONNECTOR = ConnectorSpec(
795
+ name="my-graph",
796
+ graph=MyGraph, # called with a Memgraph client, or its connection keyword arguments
797
+ build=lambda graph, config: MyGraphConnector(graph), # config: the config file's HookConfig
798
+ check=None, # optional: (config) -> (ok, detail) for doctor, beyond a reachable Memgraph
799
+ )
800
+ ```
801
+
802
+ ```toml
803
+ [project.entry-points."memgraph_context_graph.connectors"]
804
+ my-graph = "my_graph.connector:CONNECTOR"
805
+ ```
806
+
807
+ Once installed, `hook run <runtime> --connector my-graph`, `[capture] connectors = ["my-graph"]` and
808
+ `doctor` work like the built-in connectors. `setup` only installs the connectors listed in
809
+ `memgraph_context_graph.connectors.INSTALLABLE`; install your own package beside the tool yourself.
810
+
811
+ Give the component's graph class a `forget_session(session_id) -> dict[str, int]`
812
+ that deletes what it hangs off that Session and returns counts, and add it to
813
+ `FORGET_ORDER` in `memgraph_context_graph/forget.py`, so `forget` reaches it.
814
+
716
815
  ## License
717
816
 
718
817
  MIT
@@ -178,7 +178,8 @@ memgraph-context-graph setup claude-code codex # just these agents
178
178
  memgraph-context-graph setup cursor --project-dir ~/work/billing
179
179
  memgraph-context-graph setup --plan # print the plan, change nothing
180
180
  memgraph-context-graph update [runtime ...] # upgrade the package, refresh the wiring and the schema
181
- memgraph-context-graph uninstall [runtime ...] # remove the wiring; the graph and config stay
181
+ memgraph-context-graph uninstall [runtime ...] # remove the wiring; asks about the graph, config and tool
182
+ memgraph-context-graph uninstall --all # the wiring, the graph, the config and the tool
182
183
  ```
183
184
 
184
185
  It finds or starts Memgraph (a `memgraph-mage` container with a volume, on a free port when 7687 is taken),
@@ -187,6 +188,14 @@ wires each agent, and runs `doctor`'s checks. Every step checks before it acts,
187
188
  missing. The TUI starts only when stdin and stdout are both terminals; the plugins' `scripts/bootstrap.sh`
188
189
  runs `setup <runtime> --no-tui`.
189
190
 
191
+ **Uninstalling.** `uninstall` always removes the wiring (plugins, hook files, MCP entries) and gives each
192
+ agent its own memory back. On a terminal it then asks, one question each and every answer defaulting to
193
+ keep, whether to delete the graph (setup's Memgraph container and its volume: every session, for good), the
194
+ config and capture-failure log, and the uv tool. Without a terminal only the flags remove more: `--graph`,
195
+ `--config`, `--tool`, or `--all` for the three. A Memgraph you run yourself is never touched; only the
196
+ container setup started, by name (`--memgraph-container`). On Windows the running tool can't remove itself,
197
+ so it prints the `uv tool uninstall` command to run next.
198
+
190
199
  **Updating.** Upgrading the package moves the code hooks and the MCP server run, but what setup wrote once stays
191
200
  as it was. `update` upgrades the uv tool and its connectors, then, with the new release, refreshes everything
192
201
  that is wired: Claude Code's and Codex's plugin (marketplace refreshed, plugin updated), each per-project agent's
@@ -231,9 +240,13 @@ OK connector:actions-graph: installed=...; memgraph=reachable
231
240
  OK connector:sessions-graph: installed=...; memgraph=reachable
232
241
  OK embeddings: BAAI/bge-small-en-v1.5 (384 dimensions) inside Memgraph
233
242
  OK mcp: serves recall
234
- OK runtime:claude-code: strict hook smoke passed
243
+ OK runtime:claude-code: connectors accept its probe event
244
+ OK plugin:claude-code: context-graph@context-graph-plugins installed and enabled
235
245
  ```
236
246
 
247
+ The `runtime:` probe runs the connectors inside `doctor` itself; `plugin:` is what says Claude Code (or Codex)
248
+ will actually call the hooks.
249
+
237
250
  > **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.
238
251
 
239
252
  ### Configuration
@@ -257,6 +270,11 @@ derive_model = "claude-sonnet-5-5"
257
270
 
258
271
  [capture]
259
272
  connectors = "skills-graph, actions-graph, sessions-graph"
273
+ exclude_projects = "~/clients/*, ~/personal"
274
+ exclude_tools = "TodoWrite, mcp__vault__*"
275
+
276
+ [redact]
277
+ ticket = 'ACME-[0-9]+'
260
278
 
261
279
  [reconcile]
262
280
  auto_reconcile = true
@@ -279,6 +297,8 @@ the model it calls (default `claude-sonnet-5-5` with Anthropic, `gpt-5` with Ope
279
297
  command names no `--connector`, from `skills-graph`, `actions-graph`,
280
298
  `sessions-graph` and `resources-graph`; unset means the first three, and
281
299
  an empty value enables none. Setup installs the ones it names.
300
+ The rest of `[capture]` and `[redact]` are the capture policy, applied to every
301
+ event before any connector stores it (see [Capture privacy](#capture-privacy)).
282
302
  `[reconcile]` is omitted entirely from a file setup wrote — absent
283
303
  means "never configured," distinct from an explicit `auto_reconcile = false`.
284
304
  `[recall]` is optional too: without it, recall runs with the widths the
@@ -298,11 +318,64 @@ memgraph-context-graph config show
298
318
  memgraph-context-graph config get memgraph.url
299
319
  memgraph-context-graph config set <key> <value>
300
320
  # keys: identity.user_id, memgraph.{url,user,password,database},
301
- # llm.{openai_api_key,anthropic_api_key,derive_model}, capture.connectors,
321
+ # llm.{openai_api_key,anthropic_api_key,derive_model},
322
+ # capture.{connectors,redact,max_chars,exclude_tools,exclude_projects},
302
323
  # reconcile.auto_reconcile, recall.embedding_model, ontology.{path,derive}, memory.backend
303
- # [recall] widths and [extraction] are edited in the file.
324
+ # [recall] widths, [extraction] and [redact] patterns are edited in the file.
325
+ ```
326
+
327
+ ### Capture privacy
328
+
329
+ Every hook event passes the capture policy before any connector sees it, so
330
+ what it removes never reaches Memgraph:
331
+
332
+ - **`<private>…</private>`** is stripped from prompts, replies and tool input
333
+ and output. An unclosed `<private>` hides the rest of that text, and a prompt
334
+ that was nothing but private isn't stored at all.
335
+ - **Secrets are redacted** to `[REDACTED:<name>]`: AWS, GitHub, Anthropic,
336
+ OpenAI, Slack, Stripe and Google keys, JWTs, PEM private keys, passwords in
337
+ URLs, and the credentials in this config file. Each `[redact]` key adds a
338
+ pattern (a Python regular expression; quote it with single quotes).
339
+ `capture.redact = false` turns redaction off; `<private>` still applies.
340
+ - **Long text is clipped** at `capture.max_chars` characters per field
341
+ (default 100000; `0` for no limit).
342
+ - **`capture.exclude_tools`** drops those tools' calls and results, by exact
343
+ name or glob (`mcp__vault__*`).
344
+ - **`capture.exclude_projects`** captures nothing from a session whose working
345
+ directory is one of these paths or globs, or inside one (`~` expands). The
346
+ agent's own hooks still answer normally, and recall still works there.
347
+
348
+ Redaction is pattern-based: it catches known credential shapes, not every
349
+ secret. What a session stored before the policy existed stays as it was.
350
+ Library callers driving `AgentLink` directly pass a `CapturePolicy` themselves.
351
+
352
+ ### Forgetting sessions
353
+
354
+ ```bash
355
+ memgraph-context-graph forget session <session-id> [<session-id> ...]
356
+ memgraph-context-graph forget project ~/work/client-repo # every session whose working directory is in it
357
+ memgraph-context-graph forget project . --dry-run # list what matches, delete nothing
304
358
  ```
305
359
 
360
+ `forget` lists the matching sessions and asks before deleting (`--yes` skips the
361
+ question; without a terminal it is required). For each session it deletes, for
362
+ good and with no archive:
363
+
364
+ - what was captured: its Actions, the Agents only it used, its skill uses and
365
+ resource Touches;
366
+ - what was derived from it: its Chunks, entity mentions and extracted
367
+ relationships, any entity left with no other evidence, and the `anon-` User
368
+ made up for it;
369
+ - its lines in the local capture-failure log.
370
+
371
+ What anything else still backs stays: entities other sessions mention, Skills,
372
+ public Resources, and your memory files, including ones the session wrote (their
373
+ versions just stop naming it). A forgotten session leaves only a
374
+ `(:ForgottenSession {session_id})` marker, which stops a hook still running, a
375
+ reconciliation in progress, or a later resume of the same session from capturing
376
+ it again. It runs against your own graph; in Enterprise, shared spaces are not
377
+ touched.
378
+
306
379
  Hooks never read environment variables for these values, and neither does setup: it writes only
307
380
  `memgraph.url` and `identity.user_id`, from its flags or what it found. Everything else is set with
308
381
  `config set`, and setup leaves it alone when it rewrites the file.
@@ -688,6 +761,32 @@ class MyGraphConnector(GraphConnector):
688
761
  ...
689
762
  ```
690
763
 
764
+ Then register it, so hooks, schema setup and `doctor` can find it:
765
+
766
+ ```python
767
+ from memgraph_context_graph.connectors import ConnectorSpec
768
+
769
+ CONNECTOR = ConnectorSpec(
770
+ name="my-graph",
771
+ graph=MyGraph, # called with a Memgraph client, or its connection keyword arguments
772
+ build=lambda graph, config: MyGraphConnector(graph), # config: the config file's HookConfig
773
+ check=None, # optional: (config) -> (ok, detail) for doctor, beyond a reachable Memgraph
774
+ )
775
+ ```
776
+
777
+ ```toml
778
+ [project.entry-points."memgraph_context_graph.connectors"]
779
+ my-graph = "my_graph.connector:CONNECTOR"
780
+ ```
781
+
782
+ Once installed, `hook run <runtime> --connector my-graph`, `[capture] connectors = ["my-graph"]` and
783
+ `doctor` work like the built-in connectors. `setup` only installs the connectors listed in
784
+ `memgraph_context_graph.connectors.INSTALLABLE`; install your own package beside the tool yourself.
785
+
786
+ Give the component's graph class a `forget_session(session_id) -> dict[str, int]`
787
+ that deletes what it hangs off that Session and returns counts, and add it to
788
+ `FORGET_ORDER` in `memgraph_context_graph/forget.py`, so `forget` reaches it.
789
+
691
790
  ## License
692
791
 
693
792
  MIT
@@ -1,6 +1,6 @@
1
1
  [project]
2
2
  name = "memgraph-context-graph"
3
- version = "0.9.0"
3
+ version = "0.10.0"
4
4
  description = "Connect agent SDKs to context-graph components (actions-graph, skills-graph, etc.)"
5
5
  readme = "README.md"
6
6
  license = { text = "MIT" }
@@ -12,7 +12,7 @@ classifiers = [
12
12
  "Programming Language :: Python :: 3.13",
13
13
  ]
14
14
  dependencies = [
15
- "memgraph-toolbox>=0.1.11",
15
+ "memgraph-toolbox>=0.2.2",
16
16
  # Edits ~/.codex/config.toml when switching Codex's memory, keeping the user's comments and layout.
17
17
  "tomlkit>=0.13,<1",
18
18
  ]
@@ -23,6 +23,7 @@ Quick Start::
23
23
 
24
24
  from importlib import metadata
25
25
 
26
+ from .capture_policy import CapturePolicy
26
27
  from .events import (
27
28
  AgentEndEvent,
28
29
  AgentStartEvent,
@@ -52,6 +53,7 @@ __all__ = [
52
53
  "AgentEndEvent",
53
54
  "AgentLink",
54
55
  "AgentStartEvent",
56
+ "CapturePolicy",
55
57
  "ErrorOccurredEvent",
56
58
  "Event",
57
59
  "EventType",
@@ -90,6 +90,11 @@ class HookConfig:
90
90
  #: ``[capture] connectors``: the graph connectors a hook enables when its command names none;
91
91
  #: None (never set) means memgraph_context_graph.connectors.DEFAULT_CONNECTORS.
92
92
  connectors: tuple[str, ...] | None = None
93
+ #: Every other ``[capture]`` key (``redact``, ``max_chars``, ``exclude_tools``, ``exclude_projects``),
94
+ #: as written: memgraph_context_graph.capture_policy validates them, this module only keeps them.
95
+ capture_settings: dict[str, str] = field(default_factory=dict)
96
+ #: ``[redact]``: custom capture redaction patterns, name to regular expression.
97
+ redact_patterns: dict[str, str] = field(default_factory=dict)
93
98
  auto_reconcile: bool | None = None
94
99
  #: The model recall embeds with; None means the consumer's own default.
95
100
  embedding_model: str | None = None
@@ -190,15 +195,6 @@ def resolve_llm_env() -> dict[str, str]:
190
195
  }
191
196
 
192
197
 
193
- def resolve_auto_reconcile() -> bool:
194
- """Resolve whether sessions-graph should auto-trigger reconciliation on SESSION_END.
195
-
196
- Config file only (ADR 0002); never configured means ``False``, matching
197
- ``SessionsGraphConnector``'s default.
198
- """
199
- return bool(load_config().auto_reconcile)
200
-
201
-
202
198
  def resolve_embedding_model() -> str | None:
203
199
  """The configured ``[recall] embedding_model``, or None to leave sessions-graph's default."""
204
200
  return load_config().embedding_model
@@ -239,6 +235,7 @@ def write_config(
239
235
  anthropic_api_key: str | None = None,
240
236
  derive_model: str | None = None,
241
237
  connectors: tuple[str, ...] | None = None,
238
+ capture_settings: dict[str, str] | None = None,
242
239
  auto_reconcile: bool | None = None,
243
240
  embedding_model: str | None = None,
244
241
  ontology_path: str | None = None,
@@ -250,6 +247,7 @@ def write_config(
250
247
  """Write or update the config file. Returns the path written to.
251
248
 
252
249
  Only updates supplied values; preserves existing values for unspecified keys.
250
+ ``capture_settings`` replaces the ``[capture]`` keys other than ``connectors`` as a whole.
253
251
  Creates the file with 0600 permissions if it does not exist.
254
252
  """
255
253
  updates = {
@@ -263,6 +261,7 @@ def write_config(
263
261
  "anthropic_api_key": anthropic_api_key,
264
262
  "derive_model": derive_model,
265
263
  "connectors": connectors,
264
+ "capture_settings": capture_settings,
266
265
  "auto_reconcile": auto_reconcile,
267
266
  "embedding_model": embedding_model,
268
267
  "ontology_path": ontology_path,
@@ -288,7 +287,7 @@ def write_full_config(
288
287
  ) -> Path:
289
288
  """Write a complete config file, resetting identity, Memgraph and LLM settings to what is given.
290
289
 
291
- Every other section (``[capture]``, ``[reconcile]``, ``[recall]``, ``[ontology]``, ``[extraction]``,
290
+ Every other section (``[capture]``, ``[redact]``, ``[reconcile]``, ``[recall]``, ``[ontology]``, ``[extraction]``,
292
291
  ``[github]``, ``[memory]``, ``[session_start]``), ``[llm] derive_model`` and the edition are kept from the existing file, since only ``config set`` or a hand edit ever sets them.
293
292
  ``auto_reconcile`` is kept likewise unless given here. :func:`write_config` is the partial update.
294
293
  """
@@ -356,6 +355,8 @@ def _read_config_file() -> HookConfig:
356
355
  anthropic_api_key=llm.get("anthropic_api_key", _LLM_DEFAULTS["anthropic_api_key"]),
357
356
  derive_model=llm.get("derive_model") or None,
358
357
  connectors=_parse_list(capture["connectors"]) if "connectors" in capture else None,
358
+ capture_settings={key: value for key, value in capture.items() if key != "connectors"},
359
+ redact_patterns=dict(sections.get("redact", {})),
359
360
  auto_reconcile=parse_bool_flag(auto_reconcile_raw) if auto_reconcile_raw is not None else None,
360
361
  embedding_model=recall.get("embedding_model") or None,
361
362
  recall_settings={key: value for key, value in recall.items() if key != "embedding_model"},
@@ -419,8 +420,8 @@ def _render_config(config: HookConfig) -> str:
419
420
 
420
421
  ``[reconcile]`` is omitted while ``auto_reconcile`` is ``None`` so a re-read keeps "never configured"
421
422
  distinct from an explicit ``false``, and ``[session_start]`` likewise while ``session_resume`` is;
422
- ``[capture]`` likewise while ``connectors`` is; ``[recall]``, ``[ontology]``, ``[extraction]``, ``[github]``
423
- and ``[memory]`` are omitted while they hold nothing.
423
+ ``[capture]`` likewise while ``connectors`` is and no other capture key is set; ``[redact]``, ``[recall]``,
424
+ ``[ontology]``, ``[extraction]``, ``[github]`` and ``[memory]`` are omitted while they hold nothing.
424
425
  """
425
426
  user_id = config.user_id or ""
426
427
  lines = [
@@ -442,8 +443,15 @@ def _render_config(config: HookConfig) -> str:
442
443
  f'anthropic_api_key = "{config.anthropic_api_key}"',
443
444
  *([f'derive_model = "{config.derive_model}"'] if config.derive_model else []),
444
445
  ]
445
- if config.connectors is not None:
446
- lines += ["", "[capture]", f'connectors = "{", ".join(config.connectors)}"']
446
+ capture = {
447
+ **({"connectors": ", ".join(config.connectors)} if config.connectors is not None else {}),
448
+ **config.capture_settings,
449
+ }
450
+ if capture:
451
+ lines += ["", "[capture]", *(f'{key} = "{value}"' for key, value in capture.items())]
452
+ if config.redact_patterns:
453
+ # Single quotes: a pattern may hold a double quote, and the parser does no escape processing.
454
+ lines += ["", "[redact]", *(f"{key} = '{value}'" for key, value in config.redact_patterns.items())]
447
455
  if config.auto_reconcile is not None:
448
456
  lines += ["", "[reconcile]", f"auto_reconcile = {'true' if config.auto_reconcile else 'false'}"]
449
457
  recall = (
@@ -281,6 +281,41 @@ def _encode(entry: dict[str, Any]) -> bytes:
281
281
  return line.encode("ascii")
282
282
 
283
283
 
284
+ def forget_session(session_id: str, *, log_path: Path | None = None) -> int:
285
+ """Rewrite the log (and its rotated ``.1``) without *session_id*'s lines; how many went.
286
+
287
+ Each file is replaced atomically, so a reader never sees half of one; a
288
+ failure a hook appends between the read and the replace is lost, which
289
+ a diagnostics log can afford.
290
+ """
291
+ target = log_path or path()
292
+ removed = 0
293
+ for file in (target, target.with_name(target.name + ".1")):
294
+ if not file.is_file():
295
+ continue
296
+ lines = file.read_bytes().splitlines(keepends=True)
297
+ kept = [line for line in lines if not _is_from(line, session_id)]
298
+ if len(kept) == len(lines):
299
+ continue
300
+ removed += len(lines) - len(kept)
301
+ scratch = file.with_name(file.name + ".forget")
302
+ fd = os.open(scratch, os.O_WRONLY | os.O_CREAT | os.O_TRUNC | getattr(os, "O_BINARY", 0), 0o600)
303
+ try:
304
+ os.write(fd, b"".join(kept))
305
+ finally:
306
+ os.close(fd)
307
+ os.replace(scratch, file)
308
+ return removed
309
+
310
+
311
+ def _is_from(line: bytes, session_id: str) -> bool:
312
+ try:
313
+ entry = json.loads(line)
314
+ except ValueError:
315
+ return False
316
+ return isinstance(entry, dict) and entry.get("session_id") == session_id
317
+
318
+
284
319
  def _append(target: Path, line: bytes) -> None:
285
320
  target.parent.mkdir(mode=0o700, parents=True, exist_ok=True)
286
321
  flags = os.O_WRONLY | os.O_APPEND | os.O_CREAT | getattr(os, "O_CLOEXEC", 0) | getattr(os, "O_BINARY", 0)