memuron 0.1.1__tar.gz

memuron-0.1.1/PKG-INFO

@@ -0,0 +1,242 @@
+Metadata-Version: 2.3
+Name: memuron
+Version: 0.1.1
+Summary: Arthaanu application built on Artha Engine.
+Requires-Dist: artha-engine[auth,mcp,app]>=0.1.3
+Requires-Dist: agno>=2.3.11
+Requires-Dist: fastapi>=0.115.0
+Requires-Dist: uvicorn[standard]>=0.34.0
+Requires-Dist: psycopg[binary]>=3.2.0
+Requires-Dist: psycopg-pool>=3.3.1
+Requires-Dist: pyjwt>=2.10.0
+Requires-Dist: email-validator>=2.2.0
+Requires-Dist: pypdf>=6.0.0
+Requires-Dist: python-multipart>=0.0.20
+Requires-Dist: requests>=2.34.0
+Requires-Dist: pymupdf>=1.23
+Requires-Dist: python-docx>=1.1.0
+Requires-Dist: openpyxl>=3.1.5
+Requires-Dist: python-pptx>=1.0.2
+Requires-Dist: xlrd>=2.0.2
+Requires-Dist: olefile>=0.47
+Requires-Dist: svix>=1.40.0
+Requires-Dist: boto3>=1.35.0
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+
+# memuron
+
+An Arthaanu application built on Artha Engine.
+
+**Documentation:** see [`docs/`](./docs/README.md) for architecture, rich nodes, document ingest, Guardian/spaces, frontend workbench, deployment, [Railway agent deploy guide](./docs/railway-deploy.md), and troubleshooting.
+
+## Mental Model
+
+Keep the engine small and generic. Put product memory behavior here:
+
+- custom Arthaanu types in `memuron/representations.py`
+- encoders that turn raw product input into meaning objects
+- lifecycle steps that normalize, merge, dedupe, or retire objects
+- projections that replay the event ledger into fast read models
+- decoders/API routes that expose product-specific reads
+
+The semantic event ledger is canonical. Projections are derived and rebuildable.
+
+Memuron writes product semantics into that ledger, but keeps the engine model clean:
+
+- memory create/update events stay product-specific: `memory.created`, `memory.updated`
+- memory/link deletes use the canonical engine event type `delete`
+- Memuron-specific delete meaning lives in metadata as `domain_event_type = memory.deleted` or `link.removed`
+- request identity is audit metadata, not hidden global state
+
+## Database
+
+Production uses **PostgreSQL** (Railway project `talented-exploration`).
+
+| Variable | Purpose |
+|----------|---------|
+| `ARTHA_DATABASE_URL` | PostgreSQL DSN for ledger + projections (preferred) |
+| `ARTHA_DB_PATH` | Fallback SQLite path for local-only dev |
+| `OPENROUTER_API_KEY` | OpenRouter key for Agno Guardian writes |
+| `GUARDIAN_MODEL` | Guardian LLM model (default: `inception/mercury-2`) |
+| `ARTHA_EMBEDDER` | `fastembed` (default) or `deterministic` |
+| `ARTHA_EMBED_MODEL` | Nomic embed model (default: `nomic-ai/nomic-embed-text-v1.5-Q`) |
+| `MEMURON_API_KEY` | Optional API key for `/memuron/*` and `/engine/*` routes |
+
+Copy `.env.example` to `.env` and set `ARTHA_DATABASE_URL` to the Railway **public** Postgres URL for local development.
+
+## Run
+
+Use **two terminals**, both starting from the **memuron repo root** (`Documents/memuron`), not `frontend/`.
+
+**Terminal 1 — backend**
+
+```bash
+cd /Users/rakshithg/Documents/memuron
+./scripts/dev-backend.sh
+# or manually:
+# source .env && uv run uvicorn memuron.application.api:create_app --factory --host 127.0.0.1 --port 8767
+```
+
+**Terminal 2 — frontend**
+
+```bash
+cd /Users/rakshithg/Documents/memuron
+./scripts/dev-frontend.sh
+# or: cd frontend && npm run dev
+```
+
+Open http://localhost:3000 — the workbench proxies to `http://127.0.0.1:8767/engine`; Memories uses `http://127.0.0.1:8767/memuron`.
+
+`frontend/.env.local` must use the **`/engine` suffix**:
+
+```bash
+ARTHA_ENGINE_URL=http://127.0.0.1:8767/engine
+MEMURON_API_URL=http://127.0.0.1:8767/memuron
+```
+
+If you see **502** on `/api/engine/*`, the backend is not running or the URL is wrong. Do not run `source .env` or `uv run` from inside `frontend/` — `.env` lives in the repo root and `uv` must use the memuron project.
+
+```bash
+uv sync
+cp .env.example .env   # then edit ARTHA_DATABASE_URL
+uv run pytest          # fast local suite (SQLite, skips integration)
+uv run pytest -m integration  # Postgres job queue + live Guardian (needs .env)
+uv run artha doctor
+```
+
+## MCP and CLI
+
+The stdio MCP server is intentionally restricted to one explicit Clerk user
+and organization. Configure its identity before starting it:
+
+```bash
+export MEMURON_MCP_ACTOR_ID=user_...
+export MEMURON_MCP_TENANT_ID=org_...
+export MEMURON_MCP_SCOPES=memory:read,memory:write,memory:delete,space:admin
+uv run memuron-mcp
+```
+
+The compact MCP surface centers on `memuron_help` and `memuron_query`, with
+memory ingest/get/update/delete/job polling and the complete space lifecycle.
+`memuron_document_source` resolves a document, chunk, image, or document
+collection node to the original uploaded file metadata and a short-lived
+download URL.
+Lower-level graph, list, collection, and bulk operations remain available
+through HTTP and the broader CLI without overwhelming an agent's tool picker.
+`memuron_get` bounds content by default and supports field selection, while
+`memuron_update` exposes flat `memory_id`, `content`, and `scope` arguments.
+Space arguments accept UUIDs, slugs, `space.*` tokens, and `/spaces/space.*`
+paths.
+
+```bash
+uv run memuron --help
+uv run memuron --tenant-id org_... query \
+  --cwd /spaces/space.personal \
+  --query 'semantic "deployment decisions" | head 5'
+uv run memuron --tenant-id org_... space list
+```
+
+All direct-ID operations verify that the target belongs to the active
+organization. API-key and local CLI callers must therefore provide a tenant.
+
+For editor login/logout, use the Railway-hosted Streamable HTTP endpoint:
+
+```json
+{
+  "mcpServers": {
+    "memuron": {
+      "url": "https://memuron-production.up.railway.app/mcp"
+    }
+  }
+}
+```
+
+Cursor discovers Clerk through OAuth protected-resource metadata, opens the
+Clerk consent flow, and stores its own access and refresh tokens. The OAuth
+application only needs the standard `profile` scope. Memuron resolves the
+signed-in user's Clerk organization membership server-side and maps it to the
+configured Memuron tenant. Enable Dynamic client registration in the Clerk
+Dashboard under OAuth applications so MCP clients can register with PKCE
+automatically.
+
+For users who belong to several mapped Clerk organizations, set
+`MEMURON_MCP_DEFAULT_CLERK_ORG_ID` to select one explicitly when the OAuth token
+does not carry an active organization.
+
+### Document storage
+
+Memuron keeps the searchable document graph in Postgres: normalized markdown,
+chunks, embeddings, links, metadata, and append-only events. Original uploads
+and extracted binary assets belong in S3-compatible object storage. This hybrid
+boundary preserves transactional graph queries without turning Postgres into a
+binary file store.
+
+## API (prefix `/memuron`)
+
+Core routes (see [`docs/README.md`](./docs/README.md) for full detail):
+
+| Method | Path | Description |
+|--------|------|-------------|
+| POST | `/memories` | Create memory (async Guardian ingest, returns job id) |
+| POST | `/nodes` | Rich node (text / image / document / collection) + optional auto-link |
+| POST | `/documents/ingest` | Multipart file → collection + source + chunks + filtered images |
+| POST | `/collections` | Collection node |
+| POST | `/collections/{id}/placements` | Place member in collection |
+| GET | `/collections/{id}/members` | List collection members |
+| GET | `/graph/export` | Graph for UI |
+| GET | `/memories` | List memories (`scope`, `limit`, `offset`) |
+| POST | `/memories/search` | Semantic search (`query`, `k`, optional `scope`) |
+| GET | `/memories/{id}` | Get one memory |
+| POST | `/memories/batch` | Get many by id |
+| PUT | `/memories/{id}` | Update content/scope (sync, no Guardian) |
+| DELETE | `/memories/{id}` | Delete one memory |
+| POST | `/memories/bulk-delete` | Delete by scope filter |
+| POST | `/memories/unlink` | Remove link between two memories |
+| GET | `/memories/count` | Count with optional filters |
+| GET | `/jobs/{id}` | Poll async ingest job status |
+| GET | `/spaces` | List org spaces |
+
+## Auth and Audit Metadata
+
+Memuron uses bring-your-own API-key auth at the product boundary. When `MEMURON_API_KEY` is set, protected routes accept either:
+
+```text
+Authorization: Bearer <key>
+X-Memuron-Api-Key: <key>
+```
+
+Optional audit headers are copied into semantic event metadata:
+
+```text
+X-Memuron-Actor-Id: agent_123
+X-Memuron-Tenant-Id: workspace_456
+X-Memuron-Scopes: memory:write,memory:delete
+X-Request-Id: req_abc
+```
+
+This applies to Memuron writes and to the mounted Artha Engine API under `/engine`. The engine remains auth-provider agnostic; Memuron decides how API keys, actors, tenants, and scopes map to product permissions.
+
+The mounted engine exposes profile discovery at:
+
+```text
+GET /engine/runtime/capabilities
+```
+
+Example create → read flow:
+
+```bash
+# Create (async)
+curl -s -X POST http://127.0.0.1:8767/memuron/memories \
+  -H 'Content-Type: application/json' \
+  -d '{"content":"User enjoys rock climbing on weekends.","scope":["fitness.climbing"]}'
+
+# Poll job until completed, then read
+curl -s http://127.0.0.1:8767/memuron/memories/{memory_id}
+
+# List and search
+curl -s 'http://127.0.0.1:8767/memuron/memories?limit=20'
+curl -s -X POST http://127.0.0.1:8767/memuron/memories/search \
+  -H 'Content-Type: application/json' \
+  -d '{"query":"rock climbing","k":5}'
+```

memuron-0.1.1/README.md

@@ -0,0 +1,216 @@
+# memuron
+
+An Arthaanu application built on Artha Engine.
+
+**Documentation:** see [`docs/`](./docs/README.md) for architecture, rich nodes, document ingest, Guardian/spaces, frontend workbench, deployment, [Railway agent deploy guide](./docs/railway-deploy.md), and troubleshooting.
+
+## Mental Model
+
+Keep the engine small and generic. Put product memory behavior here:
+
+- custom Arthaanu types in `memuron/representations.py`
+- encoders that turn raw product input into meaning objects
+- lifecycle steps that normalize, merge, dedupe, or retire objects
+- projections that replay the event ledger into fast read models
+- decoders/API routes that expose product-specific reads
+
+The semantic event ledger is canonical. Projections are derived and rebuildable.
+
+Memuron writes product semantics into that ledger, but keeps the engine model clean:
+
+- memory create/update events stay product-specific: `memory.created`, `memory.updated`
+- memory/link deletes use the canonical engine event type `delete`
+- Memuron-specific delete meaning lives in metadata as `domain_event_type = memory.deleted` or `link.removed`
+- request identity is audit metadata, not hidden global state
+
+## Database
+
+Production uses **PostgreSQL** (Railway project `talented-exploration`).
+
+| Variable | Purpose |
+|----------|---------|
+| `ARTHA_DATABASE_URL` | PostgreSQL DSN for ledger + projections (preferred) |
+| `ARTHA_DB_PATH` | Fallback SQLite path for local-only dev |
+| `OPENROUTER_API_KEY` | OpenRouter key for Agno Guardian writes |
+| `GUARDIAN_MODEL` | Guardian LLM model (default: `inception/mercury-2`) |
+| `ARTHA_EMBEDDER` | `fastembed` (default) or `deterministic` |
+| `ARTHA_EMBED_MODEL` | Nomic embed model (default: `nomic-ai/nomic-embed-text-v1.5-Q`) |
+| `MEMURON_API_KEY` | Optional API key for `/memuron/*` and `/engine/*` routes |
+
+Copy `.env.example` to `.env` and set `ARTHA_DATABASE_URL` to the Railway **public** Postgres URL for local development.
+
+## Run
+
+Use **two terminals**, both starting from the **memuron repo root** (`Documents/memuron`), not `frontend/`.
+
+**Terminal 1 — backend**
+
+```bash
+cd /Users/rakshithg/Documents/memuron
+./scripts/dev-backend.sh
+# or manually:
+# source .env && uv run uvicorn memuron.application.api:create_app --factory --host 127.0.0.1 --port 8767
+```
+
+**Terminal 2 — frontend**
+
+```bash
+cd /Users/rakshithg/Documents/memuron
+./scripts/dev-frontend.sh
+# or: cd frontend && npm run dev
+```
+
+Open http://localhost:3000 — the workbench proxies to `http://127.0.0.1:8767/engine`; Memories uses `http://127.0.0.1:8767/memuron`.
+
+`frontend/.env.local` must use the **`/engine` suffix**:
+
+```bash
+ARTHA_ENGINE_URL=http://127.0.0.1:8767/engine
+MEMURON_API_URL=http://127.0.0.1:8767/memuron
+```
+
+If you see **502** on `/api/engine/*`, the backend is not running or the URL is wrong. Do not run `source .env` or `uv run` from inside `frontend/` — `.env` lives in the repo root and `uv` must use the memuron project.
+
+```bash
+uv sync
+cp .env.example .env   # then edit ARTHA_DATABASE_URL
+uv run pytest          # fast local suite (SQLite, skips integration)
+uv run pytest -m integration  # Postgres job queue + live Guardian (needs .env)
+uv run artha doctor
+```
+
+## MCP and CLI
+
+The stdio MCP server is intentionally restricted to one explicit Clerk user
+and organization. Configure its identity before starting it:
+
+```bash
+export MEMURON_MCP_ACTOR_ID=user_...
+export MEMURON_MCP_TENANT_ID=org_...
+export MEMURON_MCP_SCOPES=memory:read,memory:write,memory:delete,space:admin
+uv run memuron-mcp
+```
+
+The compact MCP surface centers on `memuron_help` and `memuron_query`, with
+memory ingest/get/update/delete/job polling and the complete space lifecycle.
+`memuron_document_source` resolves a document, chunk, image, or document
+collection node to the original uploaded file metadata and a short-lived
+download URL.
+Lower-level graph, list, collection, and bulk operations remain available
+through HTTP and the broader CLI without overwhelming an agent's tool picker.
+`memuron_get` bounds content by default and supports field selection, while
+`memuron_update` exposes flat `memory_id`, `content`, and `scope` arguments.
+Space arguments accept UUIDs, slugs, `space.*` tokens, and `/spaces/space.*`
+paths.
+
+```bash
+uv run memuron --help
+uv run memuron --tenant-id org_... query \
+  --cwd /spaces/space.personal \
+  --query 'semantic "deployment decisions" | head 5'
+uv run memuron --tenant-id org_... space list
+```
+
+All direct-ID operations verify that the target belongs to the active
+organization. API-key and local CLI callers must therefore provide a tenant.
+
+For editor login/logout, use the Railway-hosted Streamable HTTP endpoint:
+
+```json
+{
+  "mcpServers": {
+    "memuron": {
+      "url": "https://memuron-production.up.railway.app/mcp"
+    }
+  }
+}
+```
+
+Cursor discovers Clerk through OAuth protected-resource metadata, opens the
+Clerk consent flow, and stores its own access and refresh tokens. The OAuth
+application only needs the standard `profile` scope. Memuron resolves the
+signed-in user's Clerk organization membership server-side and maps it to the
+configured Memuron tenant. Enable Dynamic client registration in the Clerk
+Dashboard under OAuth applications so MCP clients can register with PKCE
+automatically.
+
+For users who belong to several mapped Clerk organizations, set
+`MEMURON_MCP_DEFAULT_CLERK_ORG_ID` to select one explicitly when the OAuth token
+does not carry an active organization.
+
+### Document storage
+
+Memuron keeps the searchable document graph in Postgres: normalized markdown,
+chunks, embeddings, links, metadata, and append-only events. Original uploads
+and extracted binary assets belong in S3-compatible object storage. This hybrid
+boundary preserves transactional graph queries without turning Postgres into a
+binary file store.
+
+## API (prefix `/memuron`)
+
+Core routes (see [`docs/README.md`](./docs/README.md) for full detail):
+
+| Method | Path | Description |
+|--------|------|-------------|
+| POST | `/memories` | Create memory (async Guardian ingest, returns job id) |
+| POST | `/nodes` | Rich node (text / image / document / collection) + optional auto-link |
+| POST | `/documents/ingest` | Multipart file → collection + source + chunks + filtered images |
+| POST | `/collections` | Collection node |
+| POST | `/collections/{id}/placements` | Place member in collection |
+| GET | `/collections/{id}/members` | List collection members |
+| GET | `/graph/export` | Graph for UI |
+| GET | `/memories` | List memories (`scope`, `limit`, `offset`) |
+| POST | `/memories/search` | Semantic search (`query`, `k`, optional `scope`) |
+| GET | `/memories/{id}` | Get one memory |
+| POST | `/memories/batch` | Get many by id |
+| PUT | `/memories/{id}` | Update content/scope (sync, no Guardian) |
+| DELETE | `/memories/{id}` | Delete one memory |
+| POST | `/memories/bulk-delete` | Delete by scope filter |
+| POST | `/memories/unlink` | Remove link between two memories |
+| GET | `/memories/count` | Count with optional filters |
+| GET | `/jobs/{id}` | Poll async ingest job status |
+| GET | `/spaces` | List org spaces |
+
+## Auth and Audit Metadata
+
+Memuron uses bring-your-own API-key auth at the product boundary. When `MEMURON_API_KEY` is set, protected routes accept either:
+
+```text
+Authorization: Bearer <key>
+X-Memuron-Api-Key: <key>
+```
+
+Optional audit headers are copied into semantic event metadata:
+
+```text
+X-Memuron-Actor-Id: agent_123
+X-Memuron-Tenant-Id: workspace_456
+X-Memuron-Scopes: memory:write,memory:delete
+X-Request-Id: req_abc
+```
+
+This applies to Memuron writes and to the mounted Artha Engine API under `/engine`. The engine remains auth-provider agnostic; Memuron decides how API keys, actors, tenants, and scopes map to product permissions.
+
+The mounted engine exposes profile discovery at:
+
+```text
+GET /engine/runtime/capabilities
+```
+
+Example create → read flow:
+
+```bash
+# Create (async)
+curl -s -X POST http://127.0.0.1:8767/memuron/memories \
+  -H 'Content-Type: application/json' \
+  -d '{"content":"User enjoys rock climbing on weekends.","scope":["fitness.climbing"]}'
+
+# Poll job until completed, then read
+curl -s http://127.0.0.1:8767/memuron/memories/{memory_id}
+
+# List and search
+curl -s 'http://127.0.0.1:8767/memuron/memories?limit=20'
+curl -s -X POST http://127.0.0.1:8767/memuron/memories/search \
+  -H 'Content-Type: application/json' \
+  -d '{"query":"rock climbing","k":5}'
+```

memuron-0.1.1/pyproject.toml

@@ -0,0 +1,45 @@
+[project]
+name = "memuron"
+version = "0.1.1"
+description = "Arthaanu application built on Artha Engine."
+readme = "README.md"
+requires-python = ">=3.12"
+dependencies = [
+    "artha-engine[auth,mcp,app]>=0.1.3",
+    "agno>=2.3.11",
+    "fastapi>=0.115.0",
+    "uvicorn[standard]>=0.34.0",
+    "psycopg[binary]>=3.2.0",
+    "psycopg-pool>=3.3.1",
+    "pyjwt>=2.10.0",
+    "email-validator>=2.2.0",
+    "pypdf>=6.0.0",
+    "python-multipart>=0.0.20",
+    "requests>=2.34.0",
+    "pymupdf>=1.23",
+    "python-docx>=1.1.0",
+    "openpyxl>=3.1.5",
+    "python-pptx>=1.0.2",
+    "xlrd>=2.0.2",
+    "olefile>=0.47",
+    "svix>=1.40.0",
+    "boto3>=1.35.0",
+]
+
+[project.scripts]
+memuron = "memuron.application.cli:main"
+memuron-mcp = "memuron.application.mcp:main"
+
+[build-system]
+requires = ["uv_build>=0.9.7,<0.10.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = ["pytest>=9.0.3", "pytest-asyncio>=0.25.0", "httpx>=0.28.0"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+addopts = "-m 'not integration'"
+markers = [
+    "integration: hits Postgres and/or live OpenRouter (run with: pytest -m integration)",
+]

memuron-0.1.1/src/memuron/__init__.py

@@ -0,0 +1,3 @@
+from memuron.application.registry import build_registry
+
+__all__ = ["build_registry"]

memuron-0.1.1/src/memuron/actions/__init__.py

@@ -0,0 +1,12 @@
+"""Import all action modules to register handlers on the shared registry."""
+
+from memuron.actions.registry import actions
+from memuron.actions import context as _context  # noqa: F401
+from memuron.actions import memory as _memory  # noqa: F401
+from memuron.actions import memory_write as _memory_write  # noqa: F401
+from memuron.actions import nodes as _nodes  # noqa: F401
+from memuron.actions import runtime as _runtime  # noqa: F401
+from memuron.actions import spaces_documents as _spaces_documents  # noqa: F401
+from memuron.actions import sync as _sync  # noqa: F401
+
+__all__ = ["actions"]

memuron-0.1.1/src/memuron/actions/context.py

@@ -0,0 +1,63 @@
+"""Context assembly actions."""
+
+from __future__ import annotations
+
+from artha_engine import ActionContext, ArthaEngine, HttpExposure
+
+from memuron.actions.helpers import merge_tenant_scope, require_user_org
+from memuron.actions.registry import actions
+from memuron.context import assemble_context
+from memuron.domain.schemas import AssembleContextRequest, AssembleContextResponse
+from memuron.persistence.identity_store import IdentityStore
+from memuron.spaces.service import resolve_space_reference
+
+
+@actions.action(
+    name="context.assemble",
+    description=(
+        "Assemble graph-native prompt context from memory search results, "
+        "collection breadcrumbs, and semantic links with citation metadata."
+    ),
+    kind="read",
+    scopes=["memory:read"],
+    http=HttpExposure("POST", "/memuron/context/assemble"),
+    mcp=False,
+    cli=False,
+    inject={"identity": "identity"},
+    tags=["context"],
+)
+def context_assemble(
+    input: AssembleContextRequest,
+    engine: ArthaEngine,
+    context: ActionContext,
+    identity: IdentityStore,
+) -> AssembleContextResponse:
+    _user_id, org_id = require_user_org(context.auth)
+    scoped = merge_tenant_scope(input.scope, context)
+    preferred_space_token = None
+    if input.space_ref:
+        space = resolve_space_reference(
+            identity,
+            org_id=org_id,
+            space_ref=input.space_ref,
+        )
+        if space is None:
+            raise KeyError("Space not found")
+        preferred_space_token = str(space["token"])
+        scoped = [token for token in scoped if not token.startswith("space.")]
+        if preferred_space_token not in scoped:
+            scoped.append(preferred_space_token)
+
+    payload = assemble_context(
+        engine,
+        query=input.query,
+        k=input.k,
+        scope=scoped or None,
+        org_id=org_id,
+        preferred_space_token=preferred_space_token,
+        token_budget=input.token_budget,
+        char_budget=input.char_budget,
+        include_links=input.include_links,
+        include_breadcrumbs=input.include_breadcrumbs,
+    )
+    return AssembleContextResponse.model_validate(payload)

memuron-0.1.1/src/memuron/actions/helpers.py

@@ -0,0 +1,88 @@
+"""Shared helpers for Memuron Artha actions."""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+from artha_engine.app.context import ActionContext
+from artha_engine.runtime.auth import AuthContext
+
+from memuron.domain.limits import MAX_SCOPE_ITEMS, MAX_SCOPE_TOKEN_LEN
+from memuron.security.tenant import merge_org_scope
+
+
+def require_user_org(auth: AuthContext) -> tuple[str, str]:
+    org_id = auth.tenant_id
+    if not org_id:
+        raise ValueError("Organization context required")
+    return str(auth.actor_id), str(org_id)
+
+
+def require_memory_in_tenant(
+    engine: Any,
+    memory_id: str,
+    context: ActionContext,
+) -> dict[str, Any]:
+    """Return a memory only when it belongs to the caller's active organization."""
+    from memuron.memory.recipes import get_memory
+    from memuron.security.tenant import org_scope_token
+
+    _user_id, org_id = require_user_org(context.auth)
+    memory = get_memory(engine, memory_id)
+    if org_scope_token(org_id) not in set(memory.get("scope") or []):
+        raise KeyError(f"Memory not found: {memory_id}")
+    return memory
+
+
+def event_metadata(
+    context: ActionContext,
+    *,
+    space_context: dict[str, str] | None = None,
+) -> dict[str, object]:
+    metadata = context.auth.event_metadata()
+    if context.request_id:
+        metadata["request_id"] = context.request_id
+    if space_context:
+        metadata["space_context"] = space_context
+    return metadata
+
+
+def merge_tenant_scope(scope: list[str] | None, context: ActionContext) -> list[str]:
+    return merge_org_scope(scope, context.auth.tenant_id)
+
+
+def tenant_scope_query(context: ActionContext, scope: str | None) -> str | None:
+    from memuron.security.tenant import tenant_scope_query as _tenant_scope_query
+
+    return _tenant_scope_query(context.auth.tenant_id, scope)
+
+
+def parse_scope_form(value: str | None) -> list[str] | None:
+    if value is None or not value.strip():
+        return None
+    raw = value.strip()
+    if raw.startswith("["):
+        decoded = json.loads(raw)
+        if not isinstance(decoded, list) or not all(isinstance(item, str) for item in decoded):
+            raise ValueError("scope must be a list of strings")
+        scope = decoded
+    else:
+        scope = [part.strip() for part in raw.split(",") if part.strip()]
+    if len(scope) > MAX_SCOPE_ITEMS:
+        raise ValueError(f"scope can contain at most {MAX_SCOPE_ITEMS} tokens")
+    for token in scope:
+        if len(token) > MAX_SCOPE_TOKEN_LEN:
+            raise ValueError(
+                f"Each scope token must be at most {MAX_SCOPE_TOKEN_LEN} characters"
+            )
+    return scope
+
+
+def parse_metadata_form(value: str | None) -> dict[str, object]:
+    if value is None or not value.strip():
+        return {}
+    decoded = json.loads(value)
+    if not isinstance(decoded, dict):
+        raise ValueError("metadata must be a JSON object")
+    return decoded