mragent-oss 0.1.0__tar.gz

mragent_oss-0.1.0/.gitignore

@@ -0,0 +1,12 @@
+__pycache__/
+*.pyc
+*.pyo
+*.egg-info/
+dist/
+build/
+.venv/
+.env
+.pytest_cache/
+.coverage
+htmlcov/
+*.db

mragent_oss-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Shanewas Ahmed <shanewasahmed@gmail.com>
+
+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.

mragent_oss-0.1.0/PKG-INFO

@@ -0,0 +1,159 @@
+Metadata-Version: 2.5
+Name: mragent-oss
+Version: 0.1.0
+Summary: Pluggable open-source agentic memory layer — MRAgent (arXiv:2606.06036)
+Project-URL: Homepage, https://github.com/shanewas/mragent
+Project-URL: Source, https://github.com/shanewas/mragent
+Project-URL: Issues, https://github.com/shanewas/mragent/issues
+Project-URL: Changelog, https://github.com/shanewas/mragent/blob/main/RELEASE_NOTES.md
+Author-email: Shanewas Ahmed <shanewasahmed@gmail.com>
+Maintainer-email: Shanewas Ahmed <shanewasahmed@gmail.com>
+License: MIT
+License-File: LICENSE
+Keywords: agent,llm,long-term-memory,mcp,memory,rag
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Requires-Dist: anyio>=4.0
+Requires-Dist: click>=8.1
+Requires-Dist: fastapi>=0.110
+Requires-Dist: httpx>=0.27
+Requires-Dist: mcp>=1.0
+Requires-Dist: numpy>=1.26
+Requires-Dist: openai>=1.30
+Requires-Dist: pydantic>=2.6
+Requires-Dist: uvicorn[standard]>=0.27
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Provides-Extra: local
+Requires-Dist: sentence-transformers>=2.7; extra == 'local'
+Description-Content-Type: text/markdown
+
+# mragent
+
+**Pluggable open-source agentic memory layer. 96% fewer tokens than LangMem on LongMemEval.**
+
+Implements MRAgent (NUS, arXiv:2606.06036) — the Cue-Tag-Content graph + mid-reasoning
+pruning loop that the paper benchmarks at **118K vs 3.26M tokens vs LangMem** on LongMemEval.
+
+```bash
+pip install -e ".[dev,local]"          # local = sentence-transformers for embeddings
+mragent init                            # creates ~/.mragent/store.db
+mragent ingest path/to/dialogues.jsonl  # populate the CTC graph
+mragent query "what did Nate win?"      # runs the retrieval loop
+mragent mcp claude-code                 # print the Claude Code install recipe
+```
+
+Works with **Claude Code, OpenCode, Cursor, Continue, Goose, Windsurf, VS Code, Gemini CLI, ChatGPT, Hermes** via one MCP server.
+
+## Why MRAgent-OSS
+
+| Framework | Limitation |
+|---|---|
+| LangMem | LangGraph-only |
+| Mem0 | Vendor pull, "easy cloud" |
+| Letta | Full runtime, operational weight |
+| A-MEM | Per-insert LLM call, stale |
+| Graphiti / Cognee | Heavy ingest, no mid-trajectory pruning |
+| Hindsight | Hermes-only |
+
+**MRAgent-OSS is the first memory layer where the agent itself decides mid-trajectory
+which reasoning branch to drop**, while still giving you a single-file SQLite default.
+
+## Plug into Claude Code in 30 seconds
+
+```bash
+claude mcp add mragent --transport stdio \
+  --command "mragent" --args "mcp serve" \
+  --env OPENAI_API_KEY="$OPENAI_API_KEY"
+```
+
+Restart Claude Code — 7 mragent tools light up:
+
+| Tool | Purpose |
+|---|---|
+| `mragent_retain` | Store a fact (CONFIRMED) |
+| `mragent_tentative` | Store reasoning-branch scratch |
+| `mragent_recall` | Top-k vector+keyword recall |
+| `mragent_reflect` | LLM-synthesized answer |
+| `mragent_query` | Full retrieval loop (the killer tool) |
+| `mragent_prune` | Drop a memory with audit trail |
+| `mragent_promote` | Tentative → Confirmed |
+
+## Python API
+
+```python
+from mragent_oss import Memory, MemoryConfig
+
+m = Memory(MemoryConfig(db_path="~/.mragent/store.db"))
+mid = m.retain("Nate won a goldfish at the fair.")
+hits = m.recall("What did Nate win?", k=5)
+for h in hits:
+    print(h.memory_id, h.text, h.score)
+```
+
+The five-verb lifecycle — `retain`, `tentative`, `recall`, `prune`,
+`promote` — is the reasoning-aware memory surface no existing
+framework offers. Tentative memories are excluded from `recall` by
+default; promote them when the reasoning branch proves true, prune
+them when it doesn't.
+
+## HTTP server
+
+```bash
+mragent serve --port 8765
+```
+
+Endpoints: `/health`, `/v1/retain`, `/v1/recall`, `/v1/reflect`,
+`/v1/query`. Single FastAPI process, no Docker, no Postgres.
+
+## What's in v0.1
+
+- ✅ CTC graph core (Cue/Episodic/Semantic/Topic nodes + Link)
+- ✅ Storage protocol with SQLite (default) + in-memory impls
+- ✅ Embeddings: OpenAI / local (sentence-transformers) / deterministic
+- ✅ LLM client (OpenAI-compatible: OpenRouter, Anthropic via OR, vLLM)
+- ✅ Three-stage ingestion pipeline (REWRITE → EMBED → EXTRACT_KEYWORD)
+- ✅ Retrieval loop with active reconstruction + cosine rerank
+- ✅ Seven retrieval tools (per arxiv §3.1)
+- ✅ MCP stdio server (10+ host integrations)
+- ✅ CLI: init, ingest, query, serve, mcp, status, version
+- ✅ HTTP server: /v1/retain, /v1/recall, /v1/reflect, /v1/query
+- ✅ Claude Code wedge adapter
+- ✅ Verbatim prompts (REWRITE, KEYWORD, ANSWER_SORT, EVENT_KEYWORDS)
+- ✅ 30 tests, all passing
+- ✅ MIT licensed
+
+## What's deferred (v0.2+)
+
+- Benchmark harness → separate `mragent-bench` repo
+- OpenCode / Hermes / LangGraph native adapters (community-contributed)
+- Postgres storage backend
+- Hosted cloud (intentionally not planned)
+
+See `SPEC.md` for the algorithm and design rationale, and
+`docs/argument_full_platform.md` + `docs/POSITION-A1-MINIMAL-V0.1.md`
+for the architecture debate that shaped this release.
+
+## Development
+
+```bash
+git clone https://github.com/mragent-oss/mragent
+cd mragent
+pip install -e ".[dev,local]"
+pytest tests/ -v          # 30 tests, ~2s
+```
+
+See `CONTRIBUTING.md` for how to add adapters, storage backends, or LLM providers.
+
+## Status
+
+v0.1.0 — release-ready. See `RELEASE_NOTES.md`.

mragent_oss-0.1.0/README.md

@@ -0,0 +1,120 @@
+# mragent
+
+**Pluggable open-source agentic memory layer. 96% fewer tokens than LangMem on LongMemEval.**
+
+Implements MRAgent (NUS, arXiv:2606.06036) — the Cue-Tag-Content graph + mid-reasoning
+pruning loop that the paper benchmarks at **118K vs 3.26M tokens vs LangMem** on LongMemEval.
+
+```bash
+pip install -e ".[dev,local]"          # local = sentence-transformers for embeddings
+mragent init                            # creates ~/.mragent/store.db
+mragent ingest path/to/dialogues.jsonl  # populate the CTC graph
+mragent query "what did Nate win?"      # runs the retrieval loop
+mragent mcp claude-code                 # print the Claude Code install recipe
+```
+
+Works with **Claude Code, OpenCode, Cursor, Continue, Goose, Windsurf, VS Code, Gemini CLI, ChatGPT, Hermes** via one MCP server.
+
+## Why MRAgent-OSS
+
+| Framework | Limitation |
+|---|---|
+| LangMem | LangGraph-only |
+| Mem0 | Vendor pull, "easy cloud" |
+| Letta | Full runtime, operational weight |
+| A-MEM | Per-insert LLM call, stale |
+| Graphiti / Cognee | Heavy ingest, no mid-trajectory pruning |
+| Hindsight | Hermes-only |
+
+**MRAgent-OSS is the first memory layer where the agent itself decides mid-trajectory
+which reasoning branch to drop**, while still giving you a single-file SQLite default.
+
+## Plug into Claude Code in 30 seconds
+
+```bash
+claude mcp add mragent --transport stdio \
+  --command "mragent" --args "mcp serve" \
+  --env OPENAI_API_KEY="$OPENAI_API_KEY"
+```
+
+Restart Claude Code — 7 mragent tools light up:
+
+| Tool | Purpose |
+|---|---|
+| `mragent_retain` | Store a fact (CONFIRMED) |
+| `mragent_tentative` | Store reasoning-branch scratch |
+| `mragent_recall` | Top-k vector+keyword recall |
+| `mragent_reflect` | LLM-synthesized answer |
+| `mragent_query` | Full retrieval loop (the killer tool) |
+| `mragent_prune` | Drop a memory with audit trail |
+| `mragent_promote` | Tentative → Confirmed |
+
+## Python API
+
+```python
+from mragent_oss import Memory, MemoryConfig
+
+m = Memory(MemoryConfig(db_path="~/.mragent/store.db"))
+mid = m.retain("Nate won a goldfish at the fair.")
+hits = m.recall("What did Nate win?", k=5)
+for h in hits:
+    print(h.memory_id, h.text, h.score)
+```
+
+The five-verb lifecycle — `retain`, `tentative`, `recall`, `prune`,
+`promote` — is the reasoning-aware memory surface no existing
+framework offers. Tentative memories are excluded from `recall` by
+default; promote them when the reasoning branch proves true, prune
+them when it doesn't.
+
+## HTTP server
+
+```bash
+mragent serve --port 8765
+```
+
+Endpoints: `/health`, `/v1/retain`, `/v1/recall`, `/v1/reflect`,
+`/v1/query`. Single FastAPI process, no Docker, no Postgres.
+
+## What's in v0.1
+
+- ✅ CTC graph core (Cue/Episodic/Semantic/Topic nodes + Link)
+- ✅ Storage protocol with SQLite (default) + in-memory impls
+- ✅ Embeddings: OpenAI / local (sentence-transformers) / deterministic
+- ✅ LLM client (OpenAI-compatible: OpenRouter, Anthropic via OR, vLLM)
+- ✅ Three-stage ingestion pipeline (REWRITE → EMBED → EXTRACT_KEYWORD)
+- ✅ Retrieval loop with active reconstruction + cosine rerank
+- ✅ Seven retrieval tools (per arxiv §3.1)
+- ✅ MCP stdio server (10+ host integrations)
+- ✅ CLI: init, ingest, query, serve, mcp, status, version
+- ✅ HTTP server: /v1/retain, /v1/recall, /v1/reflect, /v1/query
+- ✅ Claude Code wedge adapter
+- ✅ Verbatim prompts (REWRITE, KEYWORD, ANSWER_SORT, EVENT_KEYWORDS)
+- ✅ 30 tests, all passing
+- ✅ MIT licensed
+
+## What's deferred (v0.2+)
+
+- Benchmark harness → separate `mragent-bench` repo
+- OpenCode / Hermes / LangGraph native adapters (community-contributed)
+- Postgres storage backend
+- Hosted cloud (intentionally not planned)
+
+See `SPEC.md` for the algorithm and design rationale, and
+`docs/argument_full_platform.md` + `docs/POSITION-A1-MINIMAL-V0.1.md`
+for the architecture debate that shaped this release.
+
+## Development
+
+```bash
+git clone https://github.com/mragent-oss/mragent
+cd mragent
+pip install -e ".[dev,local]"
+pytest tests/ -v          # 30 tests, ~2s
+```
+
+See `CONTRIBUTING.md` for how to add adapters, storage backends, or LLM providers.
+
+## Status
+
+v0.1.0 — release-ready. See `RELEASE_NOTES.md`.

mragent_oss-0.1.0/RELEASE_NOTES.md

@@ -0,0 +1,94 @@
+# Release Notes — v0.1.0 (2026-06-29)
+
+First public release of MRAgent-OSS, the open-source implementation of
+MRAgent (arXiv:2606.06036).
+
+## What's in this release
+
+- **CTC graph core** (`mragent_oss.core.graph`) — `CueNode`, `EpisodicNode`,
+  `SemanticNode`, `TopicNode`, `Link`, plus the `MemoryGraph` wrapper
+  with all index dicts (`keys`, `episode_events`, `episode_links`,
+  `key_to_values`, `event_to_keys`, `by_tag`, `by_key`, `tag_list`,
+  `topic_dict`, `persona_list`, `topic_embeddings`).
+- **Three-verb + 3 verb lifecycle API** (`mragent_oss.api.Memory`):
+  `retain`, `recall`, `reflect`, `tentative`, `prune`, `promote`, `link`.
+- **Storage protocol** with two impls: `SQLiteStorage` (default, single
+  file at `~/.mragent/store.db` or `$MRAGENT_DB_PATH`) and
+  `MemoryStorage` (in-process dict).
+- **Embeddings protocol** with three backends: `OpenAIEmbeddings`,
+  `LocalEmbeddings` (sentence-transformers, optional), and a
+  `DeterministicEmbeddings` (test/CLI bootstrap).
+- **LLM client** (`mragent_oss.llm.client`) — OpenAI-compatible, works for
+  OpenRouter, Anthropic via OpenRouter, and local vLLM.
+- **Three-stage ingestion pipeline** (REWRITE → EMBED → EXTRACT_KEYWORD)
+  with per-stage file cache.
+- **Retrieval loop** (`mragent_oss.retrieve.loop`) — the active
+  reconstruction loop with seed-pool extension on `query_event_keywords`
+  and embedding rerank on `edges_by_tag` when match set > `RERANK_LIMIT=20`.
+- **Seven tools** (`mragent_oss.retrieve.tools`): `edges_by_tag`,
+  `query_conversation_time`, `query_event_keywords`, `query_event_context`,
+  `query_personal_information`, `query_personal_aspect`, `query_topic_events`.
+- **MCP stdio server** (`mragent_oss.mcp_server`) — exposes the 7 tools and
+  the 6 `Memory` verbs to any MCP-capable host: Claude Code, OpenCode,
+  Cursor, Continue, Goose, Windsurf, VS Code, Gemini CLI, ChatGPT desktop.
+- **CLI** (`mragent_oss.cli`): `init`, `ingest`, `query`, `serve`,
+  `mcp serve`, `mcp claude-code`, `status`, `version`.
+- **HTTP server** (`mragent serve`) — FastAPI on port 8765 with
+  `/health`, `/v1/retain`, `/v1/recall`, `/v1/reflect`, `/v1/query`.
+- **Claude Code wedge adapter** (`mragent_oss.adapters.claude_code`) —
+  prints the exact install recipe + JSON snippet for `.mcp.json`.
+- **Verbatim prompts** for REWRITE, EXTRACT_KEYWORD, EVENT_KEYWORDS,
+  ANSWER_SORT, TOOL_CALL — all faithful to arxiv:2606.06036.
+
+## Install
+
+```bash
+pip install -e ".[dev]"
+```
+
+For local embeddings (avoids OpenAI dependency):
+```bash
+pip install -e ".[local,dev]"
+```
+
+## Quickstart
+
+```bash
+mragent init                                     # create ~/.mragent/store.db
+mragent ingest path/to/dialogues.jsonl           # populate the CTC graph
+mragent query "what did Nate win?"               # ask a question
+mragent mcp claude-code                          # print Claude Code install recipe
+```
+
+Or in Python:
+
+```python
+from mragent_oss import Memory, MemoryConfig
+
+m = Memory(MemoryConfig(db_path="~/.mragent/store.db"))
+mid = m.retain("Nate won a goldfish at the fair.")
+hits = m.recall("What did Nate win?", k=5)
+for h in hits:
+    print(h.memory_id, h.text, h.score)
+```
+
+## Plug into Claude Code in 30 seconds
+
+```bash
+claude mcp add mragent --transport stdio \
+  --command "mragent" --args "mcp serve" \
+  --env OPENAI_API_KEY="$OPENAI_API_KEY"
+```
+
+Restart Claude Code — the 7 mragent tools will appear in the tool list.
+
+## Out of scope (deferred)
+
+- Postgres storage backend (v0.3)
+- OpenCode / Hermes / LangGraph native adapters (community-contributed, v0.2+)
+- Benchmark harness (separate `mragent-bench` repo, v0.2)
+- Hosted cloud (intentionally not planned)
+
+See `SPEC.md` for the full design rationale and
+`docs/argument_full_platform.md` / `docs/POSITION-A1-MINIMAL-V0.1.md`
+for the architecture debate that shaped this release.

mragent_oss-0.1.0/pyproject.toml

@@ -0,0 +1,77 @@
+[build-system]
+requires = ["hatchling>=1.18"]
+build-backend = "hatchling.build"
+
+[project]
+name = "mragent-oss"
+version = "0.1.0"
+description = "Pluggable open-source agentic memory layer — MRAgent (arXiv:2606.06036)"
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+authors = [{ name = "Shanewas Ahmed", email = "shanewasahmed@gmail.com" }]
+maintainers = [{ name = "Shanewas Ahmed", email = "shanewasahmed@gmail.com" }]
+keywords = ["agent", "memory", "llm", "mcp", "long-term-memory", "rag"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+]
+dependencies = [
+    "pydantic>=2.6",
+    "httpx>=0.27",
+    "click>=8.1",
+    "numpy>=1.26",
+    "openai>=1.30",
+    "mcp>=1.0",
+    "fastapi>=0.110",
+    "uvicorn[standard]>=0.27",
+    "anyio>=4.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0",
+    "pytest-asyncio>=0.23",
+]
+local = [
+    "sentence-transformers>=2.7",
+]
+
+[project.scripts]
+mragent = "mragent_oss.cli:cli"
+
+[project.urls]
+Homepage = "https://github.com/shanewas/mragent"
+Source = "https://github.com/shanewas/mragent"
+Issues = "https://github.com/shanewas/mragent/issues"
+Changelog = "https://github.com/shanewas/mragent/blob/main/RELEASE_NOTES.md"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/mragent_oss"]
+include = [
+    "README.md",
+    "RELEASE_NOTES.md",
+    "LICENSE",
+]
+
+[tool.hatch.build.targets.sdist]
+include = [
+    "src/mragent_oss/**",
+    "README.md",
+    "RELEASE_NOTES.md",
+    "LICENSE",
+    "pyproject.toml",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src"]
+asyncio_mode = "auto"
+addopts = "-ra"

mragent_oss-0.1.0/src/mragent_oss/__init__.py

@@ -0,0 +1,32 @@
+"""
+mragent-oss — pluggable open-source agentic memory layer.
+
+A faithful open-source implementation of MRAgent (NUS, arXiv:2606.06036):
+the Cue-Tag-Content graph + mid-reasoning pruning loop. Single-file
+SQLite default, OpenAI-compatible LLM client, three-stage ingestion
+pipeline, retrieval loop, MCP server, CLI, and HTTP server — all in
+one package.
+
+Quickstart::
+
+    from mragent_oss import Memory, MemoryConfig
+
+    m = Memory(MemoryConfig(db_path="~/.mragent/store.db"))
+    mid = m.retain("Nate won a goldfish at the fair.")
+    hits = m.recall("What did Nate win?", k=5)
+    for h in hits:
+        print(h.memory_id, h.text, h.score)
+
+Drop into Claude Code in 30 seconds::
+
+    claude mcp add mragent --transport stdio \\
+        --command "mragent" --args "mcp serve" \\
+        --env OPENAI_API_KEY="$OPENAI_API_KEY"
+
+See https://github.com/shanewas/mragent for the full documentation.
+"""
+
+from ._version import __version__
+from .api import Memory, MemoryConfig, MemoryHit
+
+__all__ = ["Memory", "MemoryConfig", "MemoryHit", "__version__"]

mragent_oss-0.1.0/src/mragent_oss/_version.py

@@ -0,0 +1,7 @@
+"""Single source of truth for the package version."""
+
+from __future__ import annotations
+
+__all__ = ["__version__"]
+
+__version__: str = "0.1.0"

mragent_oss-0.1.0/src/mragent_oss/adapters/__init__.py

@@ -0,0 +1,24 @@
+"""Host-framework adapters for MRAgent-OSS.
+
+This package contains user-installable recipes / glue code that wires
+``mragent`` into specific agent frameworks. v0.1 ships only the
+**Claude Code** wedge adapter (proof of pluggability); other adapters
+live in user-contributed packages until they prove their worth.
+
+Why an adapter at all when the MCP server covers everything?
+-----------------------------------------------------------
+The MCP server covers any agent that speaks MCP — Claude Code, OpenCode,
+Cursor, Continue, Goose, Windsurf, VS Code, Gemini CLI, ChatGPT desktop.
+The adapters in this package exist for two narrower cases:
+
+1. **Native tool-call integration** — when the host framework exposes
+   hooks for registering native tools (not via MCP) — e.g. Hermes's
+   plugin entry points.
+2. **Lifecycle hooks** — auto-retain on every conversation turn, or
+   auto-inject recalled memories into the system prompt before every
+   LLM call. The MCP server cannot do this for every host.
+"""
+
+from .claude_code import get_install_snippet, get_one_liner
+
+__all__ = ["get_install_snippet", "get_one_liner"]

mragent_oss-0.1.0/src/mragent_oss/adapters/claude_code.py

@@ -0,0 +1,61 @@
+"""Claude Code adapter for MRAgent-OSS.
+
+Prints the exact install recipe a user pastes into their Claude Code
+MCP configuration. The recipe is a JSON snippet, not a Python install
+hook — Claude Code reads the snippet from ``~/.config/claude/settings.json``
+(per-user) or ``.mcp.json`` (per-project) at startup.
+
+Why one-liner + JSON snippet?
+-----------------------------
+The CLI surface mirrors how Claude Code's own ``claude mcp add`` works:
+the one-liner registers the server in the user's global config; the
+JSON snippet is what to commit into a project's ``.mcp.json`` so the
+team gets mragent automatically.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Dict
+
+
+def get_install_snippet() -> Dict[str, Any]:
+    """Return the JSON snippet for ``.mcp.json`` or Claude settings.
+
+    Example ``.mcp.json`` in a project root::
+
+        {
+            "mcpServers": {
+                "mragent": {
+                    "command": "mragent",
+                    "args": ["mcp", "serve"],
+                    "env": {
+                        "OPENAI_API_KEY": "..."
+                    }
+                }
+            }
+        }
+    """
+    return {
+        "mcpServers": {
+            "mragent": {
+                "command": "mragent",
+                "args": ["mcp", "serve"],
+                "env": {
+                    "OPENAI_API_KEY": "${env:OPENAI_API_KEY}",
+                },
+            }
+        }
+    }
+
+
+def get_one_liner() -> str:
+    """Return the shell one-liner that registers mragent globally in Claude Code.
+
+    Equivalent to clicking through the Claude Code UI's MCP setup, but
+    reproducible in any CI / dotfiles repo.
+    """
+    return (
+        'claude mcp add mragent --transport stdio '
+        '--command "mragent" --args "mcp serve" '
+        '--env OPENAI_API_KEY="$OPENAI_API_KEY"'
+    )