From 70a37b713dec870ceb0f7dffc9dac2b6ac1c7283 Mon Sep 17 00:00:00 2001 From: Perseus Computing <51974392+tcconnally@users.noreply.github.com> Date: Sat, 27 Jun 2026 10:36:19 -0500 Subject: [PATCH 1/2] Add Perseus Context integration page MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Adds docs/integrations/perseus.md (catalog tags: code, mcp) plus the assets/perseus.svg icon. The page documents adk-perseus-context — an ADK plugin / before_model_callback that injects a deterministically compiled Perseus context into the system instruction — and the optional Perseus MCP server via McpToolset. The integrations catalog auto-renders from the frontmatter, so no nav changes are needed. --- docs/integrations/assets/perseus.svg | 14 +++ docs/integrations/perseus.md | 162 +++++++++++++++++++++++++++ 2 files changed, 176 insertions(+) create mode 100644 docs/integrations/assets/perseus.svg create mode 100644 docs/integrations/perseus.md diff --git a/docs/integrations/assets/perseus.svg b/docs/integrations/assets/perseus.svg new file mode 100644 index 000000000..c1cbea507 --- /dev/null +++ b/docs/integrations/assets/perseus.svg @@ -0,0 +1,14 @@ + + + + + + + + + P + + + + + diff --git a/docs/integrations/perseus.md b/docs/integrations/perseus.md new file mode 100644 index 000000000..21362784e --- /dev/null +++ b/docs/integrations/perseus.md @@ -0,0 +1,162 @@ +--- +catalog_title: Perseus Context +catalog_description: Compile deterministic, workspace-aware context for ADK agents — no index, no embeddings +catalog_icon: /integrations/assets/perseus.svg +catalog_tags: ["code", "mcp"] +--- + +# Perseus Context integration for ADK + +
+ Supported in ADKPython +
+ +The [`adk-perseus-context`](https://github.com/Perseus-Computing-LLC/adk-perseus-context) +integration injects a deterministically compiled context into your ADK agent's +system instruction. It is powered by +[Perseus](https://github.com/Perseus-Computing-LLC/perseus), an open-source (MIT) +**context compiler**: Perseus resolves directives like `@file`, `@search`, and +`@memory` into one byte-stable context string at inference time — with **no +retrieval index, no embeddings, and no extra LLM round-trip**. Everything runs +locally. + +Perseus is a context *compiler*, not a memory or RAG backend. For persistent +cross-session memory, pair it with its companion, +[Mimir](/integrations/mimir/). + +## Use cases + +- **Deterministic context assembly**: The same inputs always compile to the same + context — byte-identical builds, no per-query retrieval variance +- **Workspace-aware agents**: Resolve `@file`, `@include`, `@search`, and + `@memory` directives so the agent sees current project files and state +- **Index-free, local context**: No vector store, no embeddings, no cloud — the + context is compiled on the machine that runs the agent +- **Full coverage at a fixed size**: Pull in exactly the context you declared, + rather than a top-k slice that can drop facts + +## Prerequisites + +- Python 3.10+ +- `google-adk>=1.0.0` +- `perseus-ctx>=1.0.10` (installed automatically) + +## Installation + +```bash +pip install adk-perseus-context +``` + +## Use with agent + +There are two ways to inject a compiled Perseus context. Use the **plugin** for a +context shared across every agent in a `Runner`, or the **callback** for a single +agent. `source` is a path to a `.perseus` file or an inline string starting with +`@perseus`. + +### Runner-wide (plugin) + +```python +from adk_perseus_context import PerseusContextPlugin +from google.adk.agents import Agent +from google.adk.runners import Runner +from google.adk.sessions import InMemorySessionService + +agent = Agent( + name="assistant", + model="gemini-flash-latest", + instruction="Help the user.", +) + +runner = Runner( + agent=agent, + app_name="perseus_app", + session_service=InMemorySessionService(), + plugins=[PerseusContextPlugin("context.perseus")], +) +``` + +### Single agent (callback) + +```python +from adk_perseus_context import perseus_before_model_callback +from google.adk.agents import Agent + +agent = Agent( + name="assistant", + model="gemini-flash-latest", + instruction="Help the user.", + before_model_callback=perseus_before_model_callback("context.perseus"), +) +``` + +Either way, the compiled context is appended to the request's system instruction +(via ADK's `LlmRequest.append_instructions`) on every model call. If Perseus is +unavailable or a compile fails, the request proceeds without injected context and +a warning is logged (`fail_open=True` by default). + +### Per-session context + +Override the source per session through session state — useful when each user or +task targets a different workspace or directive set: + +```python +session = await runner.session_service.create_session( + app_name="perseus_app", + user_id="user", + state={ + "_perseus_source": "@perseus\n@file AGENTS.md\n@memory deployment", + "_perseus_workspace": "/path/to/project", + }, +) +``` + +## Use as an MCP server (optional) + +Perseus also ships an MCP server that exposes its directives as tools, so you can +consume it through ADK's `McpToolset` instead of (or alongside) the plugin: + +```python +from google.adk.agents import Agent +from google.adk.tools.mcp_tool import McpToolset, StdioConnectionParams +from mcp import StdioServerParameters + +perseus_tools = McpToolset( + connection_params=StdioConnectionParams( + server_params=StdioServerParameters( + command="perseus", + args=["mcp", "serve", "--workspace", "."], + ) + ) +) + +agent = Agent( + name="assistant", + model="gemini-flash-latest", + instruction="Use Perseus tools to read workspace context.", + tools=[perseus_tools], +) +``` + +## Plugin reference + +| Entry point | Scope | Description | +|---|---|---| +| `PerseusContextPlugin(source)` | Runner-wide | Injects the compiled context into every agent's model request | +| `perseus_before_model_callback(source)` | Single agent | A `before_model_callback` that injects the compiled context | +| `_perseus_source` / `_perseus_workspace` | Session state | Per-session overrides of the source and workspace | + +## Comparison + +| Approach | Index / embeddings | Extra LLM call | Output stability | Coverage | +|---|---|---|---|---| +| Naive context dump | None | No | Stable | Full but bloated | +| RAG / vector retrieval | Required | Sometimes | Varies per query | Top-k (can miss facts) | +| **Perseus compile** | **None** | **No** | **Byte-identical** | **Full, declared** | + +## Resources + +- [adk-perseus-context on GitHub](https://github.com/Perseus-Computing-LLC/adk-perseus-context) +- [adk-perseus-context on PyPI](https://pypi.org/project/adk-perseus-context/) +- [Perseus (context engine)](https://github.com/Perseus-Computing-LLC/perseus) +- [Mimir Memory integration](/integrations/mimir/) From d6e71a27ccd7ba7dc33bf48a5568aaad736d66f3 Mon Sep 17 00:00:00 2001 From: Perseus Computing <51974392+tcconnally@users.noreply.github.com> Date: Sun, 28 Jun 2026 10:15:50 -0500 Subject: [PATCH 2/2] Update Perseus icon to the matched Mimir/Perseus icon system Flat SVG: directives (nodes) converging into a single context node (amber #F5A623 on #161420), matched to Mimir's layered-memory mark. --- docs/integrations/assets/perseus.svg | 28 +++++++++++++++------------- 1 file changed, 15 insertions(+), 13 deletions(-) diff --git a/docs/integrations/assets/perseus.svg b/docs/integrations/assets/perseus.svg index c1cbea507..53b94fcc7 100644 --- a/docs/integrations/assets/perseus.svg +++ b/docs/integrations/assets/perseus.svg @@ -1,14 +1,16 @@ - - - - - - - - - P - - - - + + + + + + + + + + + + + + +