memgraph-context-graph 0.5.0__tar.gz

memgraph_context_graph-0.5.0/.gitignore

@@ -0,0 +1,189 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# UV
+#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#uv.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#pdm.lock
+#   pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it
+#   in version control.
+#   https://pdm.fming.dev/latest/usage/project/#working-with-version-control
+.pdm.toml
+.pdm-python
+.pdm-build/
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+#.idea/
+
+# Ruff stuff:
+.ruff_cache/
+
+# PyPI configuration file
+.pypirc
+
+
+# VS Code
+.vscode/
+
+
+# Local agent hook configuration
+/.codex/
+/.claude/settings.local.json
+
+# Project specific files
+/enterprise-context/sic-agent/sic-scrapper/output/*
+
+# deepeval writes run caches and telemetry here; build artifacts, not source.
+.deepeval/

memgraph_context_graph-0.5.0/CONTEXT.md

@@ -0,0 +1,113 @@
+# Memgraph Context Graph
+
+Adapter layer for Context Graph components. Normalizes agent SDK + runtime activity into events, routes to graph connectors.
+
+## Language
+
+**Memgraph 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 Memgraph 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 Memgraph 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
+
+**Turn End**:
+Agent finished one turn (one prompt's work) inside a still-open **Agent Session**. Distinct from session end: most runtimes fire a stop hook after every turn, and several (Codex, Antigravity, `opencode run`) fire nothing at session end. Graph Connectors mark the session for later reconciliation on a Turn End but only start it on session end.
+_Avoid_: Stop (a runtime's hook name, not a protocol term), session end
+
+**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
+
+**Edition**:
+Which multi-user model the **Hook Configuration** selects, by its top-level `edition` key. **Community** (the default): one user, one Memgraph database. **Enterprise**: many users on a shared Memgraph, isolation enforced by Memgraph Enterprise access control, implemented by the separate `context-graph-spaces` package. Chosen explicitly, never detected from the server's licence (map #501).
+_Avoid_: tier, plan, licence (commercial terms, not behaviour)
+
+**Space**:
+A place memory lives. Each user has one **Personal Space**, where hooks write all their activity. Enterprise adds **Shared Spaces** that a set of members can read. A space is one Memgraph database: Memgraph can't query across databases, so reading several spaces means one query per space.
+_Avoid_: tenant (admin vocabulary), workspace, team (a team is just one kind of Shared Space)
+
+**Space Resolver**:
+`SpaceResolver` (`spaces.py`). The one place a component asks who the user is, which space to write to (`personal()`), and which spaces to read (`readable()`). `spaces_for(config)` returns the configured **Edition**'s resolver. Components never read `[identity]` or `[memgraph]` themselves.
+_Avoid_: reading `HookConfig.user_id` / `memgraph_*` directly
+
+**Runtime Registration**:
+Python object implementing `RuntimeCLIPlugin`. Package publishes it via `memgraph_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 Memgraph 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 `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.
+_Avoid_: MCP tool (the protocol it is served over, not the thing), Graph Connector (writes events; a tool reads)
+
+## Relationships
+
+- **Memgraph Context Graph** belongs to broader **Context Graph** family.
+- **Memgraph Context Graph** routes events to graph connectors owned by graph components.
+- **Graph Connector** consumes normalized events emitted by **Memgraph 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. Memgraph 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`, `copilot-cli`, `cursor`, `opencode`, `antigravity-cli`, and `grok`. Other packages may publish more.
+
+## Example dialogue
+
+> **Dev:** "Should Memgraph Context Graph write the skill usage edge?"
+> **Domain expert:** "No. Memgraph 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: **Memgraph 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.

memgraph_context_graph-0.5.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Memgraph
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.