memuron 0.1.1__py3-none-any.whl

memuron/application/config.py

@@ -0,0 +1,176 @@
+"""Memuron configuration from environment variables."""
+
+from __future__ import annotations
+
+import os
+import secrets
+from dataclasses import dataclass
+
+NOMIC_EMBED_MODEL = "nomic-ai/nomic-embed-text-v1.5-Q"
+DEFAULT_GUARDIAN_MODEL = "inception/mercury-2"
+# OpenRouter max_completion_tokens for inception/mercury-2 (reasoning model).
+DEFAULT_GUARDIAN_MAX_TOKENS = 50_000
+DEFAULT_GUARDIAN_TIMEOUT_SECONDS = 120
+DEFAULT_DOCUMENT_LINK_MODEL = "google/gemini-3.1-flash-lite"
+DEFAULT_IMAGE_VLM_MODEL = "perceptron/perceptron-mk1"
+DEFAULT_JWT_ISSUER = "memuron"
+
+
+def resolve_database_url() -> str:
+    """Prefer explicit memuron config; fall back to Railway Postgres injects."""
+    url = (
+        os.environ.get("ARTHA_DATABASE_URL")
+        or os.environ.get("DATABASE_URL")
+        or os.environ.get("DATABASE_PRIVATE_URL")
+        or ""
+    ).strip()
+    if not url and os.environ.get("RAILWAY_ENVIRONMENT"):
+        raise RuntimeError(
+            "Database URL missing. Set ARTHA_DATABASE_URL=${{ Postgres.DATABASE_URL }} "
+            "on the memuron Railway service."
+        )
+    return url
+
+
+@dataclass(frozen=True)
+class Settings:
+    database_url: str
+    openrouter_api_key: str
+    guardian_model: str
+    guardian_retries: int
+    guardian_max_tokens: int
+    guardian_timeout_seconds: int
+    document_link_model: str
+    document_link_retries: int
+    document_chunk_neighbor_top_k: int
+    document_external_candidate_budget: int
+    search_min_semantic_score: float
+    search_hybrid: bool
+    search_rrf_k: int
+    search_retrieve_multiplier: int
+    ingest_worker_count: int
+    ingest_job_poll_interval_seconds: float
+    ingest_job_lease_seconds: int
+    ingest_job_max_attempts: int
+    embedder: str
+    embed_model: str
+    vector_dimensions: int
+    search_include_links: bool
+    describe_images: bool
+    image_vlm_model: str
+    image_vlm_timeout_seconds: int
+    api_key: str
+    jwt_secret: str
+    jwt_issuer: str
+    jwt_algorithm: str
+    jwt_expire_hours: int
+    auth_required: bool
+    object_storage_bucket: str = ""
+    object_storage_endpoint_url: str = ""
+    object_storage_region: str = "auto"
+    object_storage_access_key_id: str = ""
+    object_storage_secret_access_key: str = ""
+    object_storage_public_base_url: str = ""
+    object_storage_presign_seconds: int = 900
+
+    @classmethod
+    def from_env(cls) -> "Settings":
+        guardian_model = (
+            os.environ.get("GUARDIAN_MODEL")
+            or os.environ.get("MEMURON_GUARDIAN_MODEL")
+            or DEFAULT_GUARDIAN_MODEL
+        )
+        jwt_secret = os.environ.get("MEMURON_JWT_SECRET", "").strip()
+        if not jwt_secret:
+            jwt_secret = secrets.token_urlsafe(32)
+        auth_required = os.environ.get("MEMURON_AUTH_REQUIRED", "1").lower() in {
+            "1",
+            "true",
+            "yes",
+        }
+        return cls(
+            database_url=resolve_database_url(),
+            openrouter_api_key=os.environ.get("OPENROUTER_API_KEY", ""),
+            guardian_model=guardian_model,
+            guardian_retries=int(os.environ.get("MEMURON_GUARDIAN_RETRIES", "3")),
+            guardian_max_tokens=int(
+                os.environ.get("MEMURON_GUARDIAN_MAX_TOKENS", str(DEFAULT_GUARDIAN_MAX_TOKENS))
+            ),
+            guardian_timeout_seconds=int(
+                os.environ.get(
+                    "MEMURON_GUARDIAN_TIMEOUT_SECONDS",
+                    str(DEFAULT_GUARDIAN_TIMEOUT_SECONDS),
+                )
+            ),
+            document_link_model=(
+                os.environ.get("MEMURON_DOCUMENT_LINK_MODEL")
+                or os.environ.get("DOCUMENT_LINK_MODEL")
+                or DEFAULT_DOCUMENT_LINK_MODEL
+            ),
+            document_link_retries=int(
+                os.environ.get("MEMURON_DOCUMENT_LINK_RETRIES", "3")
+            ),
+            document_chunk_neighbor_top_k=int(
+                os.environ.get("MEMURON_DOCUMENT_CHUNK_NEIGHBOR_TOP_K", "10")
+            ),
+            document_external_candidate_budget=int(
+                os.environ.get("MEMURON_DOCUMENT_EXTERNAL_CANDIDATE_BUDGET", "30")
+            ),
+            search_min_semantic_score=float(
+                os.environ.get("MEMURON_SEARCH_MIN_SEMANTIC_SCORE", "0.55")
+            ),
+            search_hybrid=os.environ.get("MEMURON_SEARCH_HYBRID", "1").lower()
+            in {"1", "true", "yes"},
+            search_rrf_k=int(os.environ.get("MEMURON_SEARCH_RRF_K", "60")),
+            search_retrieve_multiplier=int(
+                os.environ.get("MEMURON_SEARCH_RETRIEVE_MULTIPLIER", "4")
+            ),
+            ingest_worker_count=int(os.environ.get("MEMURON_INGEST_WORKER_COUNT", "2")),
+            ingest_job_poll_interval_seconds=float(
+                os.environ.get("MEMURON_INGEST_POLL_INTERVAL_SECONDS", "1.0")
+            ),
+            ingest_job_lease_seconds=int(os.environ.get("MEMURON_INGEST_JOB_LEASE_SECONDS", "600")),
+            ingest_job_max_attempts=int(os.environ.get("MEMURON_INGEST_JOB_MAX_ATTEMPTS", "3")),
+            embedder=os.environ.get("ARTHA_EMBEDDER", "fastembed"),
+            embed_model=os.environ.get("ARTHA_EMBED_MODEL", NOMIC_EMBED_MODEL),
+            vector_dimensions=int(os.environ.get("MEMURON_VECTOR_DIMENSIONS", "768")),
+            search_include_links=os.environ.get("MEMURON_SEARCH_INCLUDE_LINKS", "1").lower()
+            in {"1", "true", "yes"},
+            describe_images=os.environ.get("MEMURON_DESCRIBE_IMAGES", "1").lower()
+            in {"1", "true", "yes"},
+            image_vlm_model=os.environ.get("MEMURON_IMAGE_VLM_MODEL", DEFAULT_IMAGE_VLM_MODEL),
+            image_vlm_timeout_seconds=int(os.environ.get("MEMURON_IMAGE_VLM_TIMEOUT_SECONDS", "60")),
+            api_key=os.environ.get("MEMURON_API_KEY", "").strip(),
+            jwt_secret=jwt_secret,
+            jwt_issuer=os.environ.get("MEMURON_JWT_ISSUER", DEFAULT_JWT_ISSUER),
+            jwt_algorithm=os.environ.get("MEMURON_JWT_ALGORITHM", "HS256"),
+            jwt_expire_hours=int(os.environ.get("MEMURON_JWT_EXPIRE_HOURS", "168")),
+            auth_required=auth_required,
+            object_storage_bucket=os.environ.get("MEMURON_OBJECT_STORAGE_BUCKET", "").strip(),
+            object_storage_endpoint_url=os.environ.get(
+                "MEMURON_OBJECT_STORAGE_ENDPOINT_URL",
+                os.environ.get("AWS_ENDPOINT_URL_S3", ""),
+            ).strip(),
+            object_storage_region=os.environ.get(
+                "MEMURON_OBJECT_STORAGE_REGION",
+                os.environ.get("AWS_REGION", "auto"),
+            ).strip(),
+            object_storage_access_key_id=os.environ.get(
+                "MEMURON_OBJECT_STORAGE_ACCESS_KEY_ID",
+                os.environ.get("AWS_ACCESS_KEY_ID", ""),
+            ).strip(),
+            object_storage_secret_access_key=os.environ.get(
+                "MEMURON_OBJECT_STORAGE_SECRET_ACCESS_KEY",
+                os.environ.get("AWS_SECRET_ACCESS_KEY", ""),
+            ).strip(),
+            object_storage_public_base_url=os.environ.get(
+                "MEMURON_OBJECT_STORAGE_PUBLIC_BASE_URL",
+                "",
+            ).strip().rstrip("/"),
+            object_storage_presign_seconds=int(
+                os.environ.get("MEMURON_OBJECT_STORAGE_PRESIGN_SECONDS", "900")
+            ),
+        )
+
+
+settings = Settings.from_env()

memuron/application/mcp.py

@@ -0,0 +1,44 @@
+"""Memuron MCP stdio server."""
+
+from __future__ import annotations
+
+import os
+
+from artha_engine.app.mcp import run_mcp
+from artha_engine.runtime.auth import AuthContext
+
+from memuron.application.app import close_application, configure_clerk_env, create_application
+
+
+def main() -> None:
+    configure_clerk_env()
+    tenant_id = os.environ.get("MEMURON_MCP_TENANT_ID", "").strip()
+    actor_id = os.environ.get("MEMURON_MCP_ACTOR_ID", "").strip()
+    if not tenant_id or not actor_id:
+        raise RuntimeError(
+            "Set MEMURON_MCP_TENANT_ID and MEMURON_MCP_ACTOR_ID so MCP tools "
+            "operate inside one explicit Memuron organization and user."
+        )
+    scopes = [
+        item.strip()
+        for item in os.environ.get(
+            "MEMURON_MCP_SCOPES",
+            "memory:read,memory:write,memory:delete,space:admin",
+        ).split(",")
+        if item.strip()
+    ]
+    auth = AuthContext(
+        actor_id=actor_id,
+        tenant_id=tenant_id,
+        scopes=scopes,
+        claims={"auth_scheme": "local_mcp"},
+    )
+    application = create_application()
+    try:
+        run_mcp(application, auth=auth)
+    finally:
+        close_application(application)
+
+
+if __name__ == "__main__":
+    main()

memuron/application/mcp_oauth.py

@@ -0,0 +1,290 @@
+"""Clerk OAuth authentication for the remote Streamable HTTP MCP server."""
+
+from __future__ import annotations
+
+import json
+import os
+import time
+from dataclasses import dataclass, field
+from typing import Any
+from urllib.parse import urlparse
+
+import httpx
+from mcp.server.auth.middleware.auth_context import get_access_token
+from mcp.server.auth.provider import AccessToken
+from mcp.server.transport_security import TransportSecuritySettings
+
+from artha_engine.app.auth import AuthenticationError, JwtAuthProvider
+from artha_engine.app.mcp import create_mcp_server
+from artha_engine.runtime.auth import AuthContext
+
+from memuron.application.app import configure_clerk_env
+from memuron.security.clerk_scopes import MEMURON_MEMBER_SCOPES, MEMURON_OWNER_SCOPES
+
+OAUTH_REQUIRED_SCOPES = ["profile"]
+MCP_TOOL_SECURITY_SCHEMES = [{"type": "oauth2", "scopes": OAUTH_REQUIRED_SCOPES}]
+MCP_INSTRUCTIONS = """\
+Memuron is an agent memory system organized as spaces over a semantic graph.
+Start with memuron_list_spaces, then use memuron_query with a cwd such as
+/spaces/space.personal. Prefer head/select/preview before fetching full content.
+Use memuron_get only after discovering an ID; its output is bounded by default.
+Space arguments accept UUIDs, slugs, tokens such as space.work, or paths such as
+/spaces/space.work. memuron_ingest is asynchronous, so poll memuron_job_status.
+Use memuron_document_source with a document, chunk, image, or document collection
+node ID to resolve the original uploaded file and short-lived download URL.
+Call memuron_help with overview, compact, commands, graph, or errors when unsure.
+"""
+
+
+def protected_resource_metadata_path(public_url: str) -> str:
+    resource_url = public_url.rstrip("/")
+    parsed = urlparse(resource_url)
+    resource_path = parsed.path if parsed.path != "/" else ""
+    return f"/.well-known/oauth-protected-resource{resource_path}"
+
+
+def protected_resource_metadata_url(public_url: str) -> str:
+    resource_url = public_url.rstrip("/")
+    parsed = urlparse(resource_url)
+    return (
+        f"{parsed.scheme}://{parsed.netloc}"
+        f"{protected_resource_metadata_path(resource_url)}"
+    )
+
+
+def protected_resource_metadata(public_url: str) -> dict[str, Any]:
+    resource_url = public_url.rstrip("/")
+    issuer = os.environ["CLERK_ISSUER"].rstrip("/")
+    return {
+        "resource": resource_url,
+        "authorization_servers": [issuer],
+        "scopes_supported": OAUTH_REQUIRED_SCOPES,
+        "bearer_methods_supported": ["header"],
+    }
+
+
+def mcp_auth_challenge(public_url: str) -> str:
+    scope = " ".join(OAUTH_REQUIRED_SCOPES)
+    metadata_url = protected_resource_metadata_url(public_url)
+    return (
+        f'Bearer resource_metadata="{metadata_url}", '
+        f'scope="{scope}", '
+        'error="invalid_token", '
+        'error_description="Sign in to Memuron to continue"'
+    )
+
+
+def _org_aliases() -> dict[str, str]:
+    raw = os.environ.get("MEMURON_CLERK_ORG_ALIASES", "").strip()
+    if not raw:
+        return {}
+    try:
+        payload = json.loads(raw)
+    except json.JSONDecodeError as exc:
+        raise RuntimeError("MEMURON_CLERK_ORG_ALIASES must be a JSON object") from exc
+    if not isinstance(payload, dict):
+        raise RuntimeError("MEMURON_CLERK_ORG_ALIASES must be a JSON object")
+    return {str(key): str(value) for key, value in payload.items()}
+
+
+def _preferred_clerk_org_id() -> str | None:
+    return os.environ.get("MEMURON_MCP_DEFAULT_CLERK_ORG_ID", "").strip() or None
+
+
+@dataclass
+class ClerkOAuthTokenVerifier:
+    """Verify Clerk OAuth access tokens and map them into Memuron tenancy."""
+
+    role_cache_seconds: int = 300
+    _jwt: JwtAuthProvider = field(init=False)
+    _organizations: dict[str, tuple[float, list[tuple[str, str]]]] = field(
+        default_factory=dict,
+        init=False,
+    )
+
+    def __post_init__(self) -> None:
+        configure_clerk_env()
+        self._jwt = JwtAuthProvider(
+            issuer=os.environ.get("CLERK_ISSUER"),
+            jwks_url=os.environ.get("CLERK_JWKS_URL"),
+            audience=os.environ.get("MEMURON_MCP_OAUTH_AUDIENCE") or None,
+            env_prefix="CLERK",
+        )
+
+    async def verify_token(self, token: str) -> AccessToken | None:
+        try:
+            verified = await self._jwt.authenticate_token(token)
+        except AuthenticationError:
+            return None
+        actor_id = verified.actor_id
+        if not actor_id:
+            return None
+        oauth_scopes = list(verified.scopes)
+        if "profile" not in oauth_scopes:
+            return None
+        organization = await self._organization_context(
+            str(actor_id),
+            str(verified.tenant_id) if verified.tenant_id else None,
+        )
+        if organization is None:
+            return None
+        clerk_org_id, role = organization
+        memuron_scopes = (
+            list(MEMURON_OWNER_SCOPES)
+            if role in {"org:admin", "admin", "owner"}
+            else list(MEMURON_MEMBER_SCOPES)
+        )
+        tenant_id = _org_aliases().get(str(clerk_org_id), str(clerk_org_id))
+        claims = dict(verified.claims)
+        claims.update(
+            {
+                "auth_scheme": "clerk_oauth",
+                "clerk_org_id": str(clerk_org_id),
+                "memuron_tenant_id": tenant_id,
+                "memuron_scopes": memuron_scopes,
+                "org_role": role,
+            }
+        )
+        return AccessToken(
+            token=token,
+            client_id=str(claims.get("azp") or claims.get("client_id") or "mcp-client"),
+            scopes=[*oauth_scopes, *[scope for scope in memuron_scopes if scope not in oauth_scopes]],
+            expires_at=int(claims["exp"]) if claims.get("exp") is not None else None,
+            subject=str(actor_id),
+            claims=claims,
+        )
+
+    async def _organization_context(
+        self,
+        user_id: str,
+        claimed_org_id: str | None,
+    ) -> tuple[str, str] | None:
+        memberships = await self._organization_memberships(user_id)
+        aliases = _org_aliases()
+        if claimed_org_id:
+            for org_id, role in memberships:
+                if org_id == claimed_org_id:
+                    return org_id, role
+            return None
+
+        configured = [
+            (org_id, role) for org_id, role in memberships if org_id in aliases
+        ]
+        if len(configured) == 1:
+            return configured[0]
+        preferred = _preferred_clerk_org_id()
+        if preferred:
+            for org_id, role in configured or memberships:
+                if org_id == preferred:
+                    return org_id, role
+        if not aliases and len(memberships) == 1:
+            return memberships[0]
+        return None
+
+    async def _organization_memberships(self, user_id: str) -> list[tuple[str, str]]:
+        cached = self._organizations.get(user_id)
+        now = time.monotonic()
+        if cached and cached[0] > now:
+            return cached[1]
+        secret = os.environ.get("CLERK_SECRET_KEY", "").strip()
+        if not secret:
+            return []
+        async with httpx.AsyncClient(timeout=10) as client:
+            response = await client.get(
+                f"https://api.clerk.com/v1/users/{user_id}/organization_memberships",
+                params={"limit": 100},
+                headers={"Authorization": f"Bearer {secret}"},
+            )
+            response.raise_for_status()
+        memberships = []
+        for membership in response.json().get("data", []):
+            org_id = (membership.get("organization") or {}).get("id")
+            if org_id:
+                memberships.append(
+                    (str(org_id), str(membership.get("role") or "org:member"))
+                )
+        self._organizations[user_id] = (
+            now + self.role_cache_seconds,
+            memberships,
+        )
+        return memberships
+
+
+def current_mcp_auth() -> AuthContext:
+    access_token = get_access_token()
+    return _auth_context_from_access_token(access_token)
+
+
+async def current_mcp_request_auth(
+    mcp_context: Any,
+    verifier: ClerkOAuthTokenVerifier,
+) -> AuthContext:
+    token = _bearer_token_from_mcp_context(mcp_context)
+    if token is None:
+        raise AuthenticationError("Missing OAuth bearer token")
+    access_token = await verifier.verify_token(token)
+    return _auth_context_from_access_token(access_token)
+
+
+def _auth_context_from_access_token(access_token: AccessToken | None) -> AuthContext:
+    if access_token is None or access_token.subject is None:
+        raise AuthenticationError("Missing authenticated MCP user")
+    claims = dict(access_token.claims or {})
+    tenant_id = claims.get("memuron_tenant_id")
+    scopes = claims.get("memuron_scopes")
+    if not tenant_id or not isinstance(scopes, list):
+        raise AuthenticationError("MCP token is missing Memuron organization context")
+    return AuthContext(
+        actor_id=access_token.subject,
+        tenant_id=str(tenant_id),
+        scopes=[str(scope) for scope in scopes],
+        claims=claims,
+    )
+
+
+def _bearer_token_from_mcp_context(mcp_context: Any) -> str | None:
+    try:
+        request_context = getattr(mcp_context, "request_context", None)
+    except ValueError:
+        return None
+    request = getattr(request_context, "request", None)
+    headers = getattr(request, "headers", None)
+    if headers is None:
+        return None
+    value = headers.get("authorization") or headers.get("Authorization")
+    if not isinstance(value, str):
+        return None
+    scheme, _, token = value.partition(" ")
+    if scheme.lower() != "bearer" or not token.strip():
+        return None
+    return token.strip()
+
+
+def create_remote_mcp_server(application: Any, public_url: str) -> Any:
+    resource_url = public_url.rstrip("/")
+    public_origin = urlparse(resource_url)
+    public_host = public_origin.netloc
+    allowed_origins = (
+        [f"{public_origin.scheme}://{public_host}"]
+        if public_origin.scheme and public_host
+        else []
+    )
+    verifier = ClerkOAuthTokenVerifier()
+
+    async def auth_resolver(mcp_context: Any) -> AuthContext:
+        return await current_mcp_request_auth(mcp_context, verifier)
+
+    return create_mcp_server(
+        application,
+        auth_resolver=auth_resolver,
+        transport_security=TransportSecuritySettings(
+            enable_dns_rebinding_protection=True,
+            allowed_hosts=[public_host],
+            allowed_origins=allowed_origins,
+        ),
+        instructions=MCP_INSTRUCTIONS,
+        stateless_http=True,
+        tool_security_schemes=MCP_TOOL_SECURITY_SCHEMES,
+        auth_challenge=mcp_auth_challenge(resource_url),
+        structured_output=False,
+    )

memuron/application/registry.py

@@ -0,0 +1,52 @@
+from artha_engine import ComponentRegistry, build_core_registry
+
+from memuron.domain.encoders import (
+    MemoryEncoder,
+    MemoryLinkEncoder,
+    MemoryPlacementEncoder,
+    normalize_memory_encoder_input,
+    normalize_memory_link_encoder_input,
+    normalize_memory_placement_encoder_input,
+)
+from memuron.graphfs.projection import FilesystemProjection
+from memuron.memory.projections import MemoryLinkProjection, MemoryPlacementProjection, MemoryProjection
+from memuron.domain.representations import MemoryArthaanu, MemoryLinkArthaanu, MemoryPlacementArthaanu
+
+
+def _memory_encoder_factory(_params, embedder=None, **_kwargs):
+    return MemoryEncoder(embedder=embedder)
+
+
+def _memory_link_encoder_factory(_params, embedder=None, **_kwargs):
+    return MemoryLinkEncoder(embedder=embedder)
+
+
+def _memory_placement_encoder_factory(_params, **_kwargs):
+    return MemoryPlacementEncoder()
+
+
+def build_registry() -> ComponentRegistry:
+    registry = build_core_registry()
+    registry.register_arthaanu_type("memory", MemoryArthaanu)
+    registry.register_arthaanu_type("memory_link", MemoryLinkArthaanu)
+    registry.register_arthaanu_type("memory_placement", MemoryPlacementArthaanu)
+    registry.register_encoder(
+        "memory",
+        _memory_encoder_factory,
+        normalize_input=normalize_memory_encoder_input,
+    )
+    registry.register_encoder(
+        "memory_link",
+        _memory_link_encoder_factory,
+        normalize_input=normalize_memory_link_encoder_input,
+    )
+    registry.register_encoder(
+        "memory_placement",
+        _memory_placement_encoder_factory,
+        normalize_input=normalize_memory_placement_encoder_input,
+    )
+    registry.register_projection("memuron_memories", lambda: MemoryProjection())
+    registry.register_projection("memuron_links", lambda: MemoryLinkProjection())
+    registry.register_projection("memuron_placements", lambda: MemoryPlacementProjection())
+    registry.register_projection("memuron_fs", lambda: FilesystemProjection())
+    return registry