curu-memory 0.2.0__py3-none-any.whl

curu_memory/__main__.py

@@ -0,0 +1,1032 @@
+"""The `curu-memory` command. It is the composition root: it selects the adapters.
+
+Only this module knows the transport of the MCP server (constitution, article V).
+Each message for a person goes to stderr, because stdout carries the MCP messages
+on stdio and the JSON output of `--json`.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import logging
+import sys
+from collections.abc import Callable
+from datetime import UTC, datetime
+from pathlib import Path
+from typing import TYPE_CHECKING, Any, NoReturn
+from urllib.parse import urlsplit
+
+from curu_memory.access import (
+    ANONYMOUS,
+    DEFAULT_GRANT_DAYS,
+    MAX_GRANT_DAYS,
+    ROLE_NAMES,
+    AccessRefused,
+    AccessStore,
+    Agent,
+    Grant,
+    Principal,
+    check_handle,
+    readable_spaces_of,
+    role_in,
+    role_of_agent,
+)
+from curu_memory.audit import CHANGED, REFUSED, AuditLog
+from curu_memory.auth import MIN_TOKEN_LENGTH
+from curu_memory.config import ConfigError, Settings
+from curu_memory.embedders import OpenAICompatibleEmbedder
+from curu_memory.errors import CuruMemoryError, IndexMissing, InvalidArgument
+from curu_memory.indexing import build_index
+from curu_memory.media import MAX_BYTES, read_query_media
+from curu_memory.ports import GLOBAL, Embedder, IndexLocked, parse_space, space_file_name
+from curu_memory.retrieval import DEFAULT_LIMIT, MAX_LIMIT, SearchResult, retriever_for
+from curu_memory.store_sqlite import SqliteEmbeddingCache, SqliteIndexStore
+
+if TYPE_CHECKING:
+    from mcp.server.mcpserver import MCPServer
+    from starlette.applications import Starlette
+
+# EX_CONFIG of sysexits.h: a configuration error. Exit 2 belongs to usage errors.
+EXIT_CONFIG = 78
+EXIT_PROBLEM = 1
+EXIT_USAGE = 2
+DEFAULT_HOST = "127.0.0.1"
+#: Ports in the 6000 series, away from the common 8000 and 8001 (the owner, 2026-11-01).
+DEFAULT_PORT = 6474
+DEFAULT_BROWSE_PORT = 6475
+LOOPBACK = {"127.0.0.1", "::1", "localhost"}
+MAKE_TOKEN = "python -c 'import secrets; print(secrets.token_urlsafe(32))'"
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="curu-memory",
+        description=(
+            "Index OKF (Open Knowledge Format) concept files, and search them from the command "
+            "line or through MCP (the Model Context Protocol)."
+        ),
+    )
+    commands = parser.add_subparsers(dest="command", required=True, metavar="COMMAND")
+
+    index = commands.add_parser(
+        "index",
+        help="Build the index of the knowledge from the concept files.",
+        description=(
+            "Build the index of the knowledge from the concept files. "
+            "The command reports each skipped file, each warning and each broken link."
+        ),
+    )
+    index.add_argument(
+        "--concepts",
+        type=Path,
+        metavar="DIR",
+        help=(
+            "The directory of the concept files. "
+            "When you give this option, the command ignores CURU_MEMORY_CONCEPTS_DIR."
+        ),
+    )
+    index.add_argument(
+        "--space",
+        type=_space,
+        default=GLOBAL,
+        metavar="SPACE",
+        help=(
+            "The space of the concepts: global, team/<slug> or personal/<handle>. "
+            "A slug or a handle has 1 to 40 characters from a to z, 0 to 9 and -. "
+            "Each space has its own index. The default is global."
+        ),
+    )
+    index.add_argument("--json", action="store_true", help="Print the report as JSON.")
+
+    search = commands.add_parser(
+        "search",
+        help="Search the index and print the matching concepts.",
+        description=(
+            "Search the index and print the matching concepts, best first. "
+            "Give a question in words, or an image, an audio clip or a video with --media. "
+            "The command gives the same results as the search_knowledge tool, "
+            "or as the search_knowledge_by_media tool for media."
+        ),
+    )
+    search.add_argument("question", nargs="?", help="The question, in words.")
+    search.add_argument(
+        "--media",
+        type=Path,
+        metavar="FILE",
+        help=(
+            "Search with this image, audio clip or video in place of a question. "
+            "Give a PNG, JPEG, WebP, WAV, FLAC, MP3, Ogg, MP4, MOV, WebM or MKV file "
+            "of 10 MB or less. "
+            "It needs an embedder."
+        ),
+    )
+    search.add_argument(
+        "--limit",
+        type=_limit,
+        default=DEFAULT_LIMIT,
+        help=f"The maximum number of results, from 1 to {MAX_LIMIT}. The default is 10.",
+    )
+    search.add_argument(
+        "--type",
+        action="append",
+        default=[],
+        dest="types",
+        metavar="TYPE",
+        help="Return only concepts of this OKF type. Repeat the option for more types.",
+    )
+    search.add_argument(
+        "--tag",
+        action="append",
+        default=[],
+        dest="tags",
+        metavar="TAG",
+        help=(
+            "Return only concepts with this tag. "
+            "Repeat the option, and each concept must have all the tags."
+        ),
+    )
+    search.add_argument(
+        "--json", action="store_true", help="Print the same JSON object as the tool result."
+    )
+
+    serve = commands.add_parser(
+        "serve",
+        help="Serve the MCP tools on stdio or on streamable HTTP.",
+        description=(
+            "Serve the MCP tools on stdio or on streamable HTTP. "
+            "HTTP needs CURU_MEMORY_OIDC_ISSUER, or a token in CURU_MEMORY_HTTP_TOKEN."
+        ),
+    )
+    serve.add_argument(
+        "--transport",
+        choices=["stdio", "http"],
+        default="stdio",
+        help=(
+            "The MCP transport. Use stdio when the MCP client starts curu-memory. "
+            "Use http for remote clients."
+        ),
+    )
+    serve.add_argument(
+        "--host",
+        default=DEFAULT_HOST,
+        help=(
+            f"The address that the HTTP server listens on. The default is {DEFAULT_HOST}. "
+            "Use 0.0.0.0 for all network interfaces."
+        ),
+    )
+    serve.add_argument(
+        "--port",
+        type=_port,
+        default=DEFAULT_PORT,
+        help=f"The port of the HTTP server, from 1 to 65535. The default is {DEFAULT_PORT}.",
+    )
+    serve.add_argument(
+        "--grant",
+        type=int,
+        metavar="ID",
+        help=(
+            "On stdio, act as the agent of this grant and read only its space. "
+            "The limit is voluntary: a process can leave the option out."
+        ),
+    )
+
+    browse = commands.add_parser(
+        "browse",
+        help="Serve a read-only web browser of the knowledge.",
+        description=(
+            "Serve a read-only web browser of the knowledge. A person can search the "
+            "knowledge and follow the links of a concept. On an address that other computers "
+            "can reach, the browser needs the token in CURU_MEMORY_HTTP_TOKEN."
+        ),
+    )
+    browse.add_argument(
+        "--host",
+        default=DEFAULT_HOST,
+        help=(
+            f"The address that the browser listens on. The default is {DEFAULT_HOST}. "
+            "An address other than 127.0.0.1, ::1 or localhost needs the token "
+            "in CURU_MEMORY_HTTP_TOKEN."
+        ),
+    )
+    browse.add_argument(
+        "--port",
+        type=_port,
+        default=DEFAULT_BROWSE_PORT,
+        help=f"The port of the browser, from 1 to 65535. The default is {DEFAULT_BROWSE_PORT}.",
+    )
+    _access_parser(commands)
+    return parser
+
+
+def _access_parser(commands: argparse._SubParsersAction) -> None:
+    access = commands.add_parser(
+        "access",
+        help="Register persons, teams and agents, give and revoke grants, and show who reads.",
+        description=(
+            "Register persons, teams and agents, give and revoke grants, and show who reads "
+            "which space. The command changes "
+            "access.sqlite in the data directory, and writes each change to audit.jsonl."
+        ),
+    )
+    parts = access.add_subparsers(dest="part", required=True, metavar="PART")
+
+    person = parts.add_parser(
+        "person",
+        help="Add, link or remove a person.",
+        description=(
+            "Add, link or remove a person. "
+            "The first person is an instance owner: admin on global and on each team space."
+        ),
+    )
+    person_actions = person.add_subparsers(dest="action", required=True, metavar="ACTION")
+    add = person_actions.add_parser(
+        "add",
+        help="Register a person.",
+        description=("Register a person. The person reads global and their own personal space."),
+    )
+    add.add_argument("handle", type=_handle, help=HANDLE_HELP)
+    add.add_argument(
+        "--owner",
+        action="store_true",
+        help="Make the person an instance owner: admin on global and on each team space.",
+    )
+    _subject_options(add, required=False)
+    link = person_actions.add_parser(
+        "link",
+        help="Link a person to the subject of their OIDC tokens.",
+        description=(
+            "Link a person to the issuer and the subject (sub) of their OIDC tokens. "
+            "The link replaces an old link of the person."
+        ),
+    )
+    link.add_argument("handle", type=_handle, help=HANDLE_HELP)
+    _subject_options(link, required=True)
+    remove = person_actions.add_parser(
+        "remove",
+        help="Remove a person.",
+        description=(
+            "Remove a person and their team memberships. "
+            "The command refuses to remove the last instance owner."
+        ),
+    )
+    remove.add_argument("handle", type=_handle, help=HANDLE_HELP)
+
+    team = parts.add_parser(
+        "team",
+        help="Add or remove a team.",
+        description=(
+            "Add or remove a team. Each member of a team has the role write on its team space."
+        ),
+    )
+    team_actions = team.add_subparsers(dest="action", required=True, metavar="ACTION")
+    for name, text in (
+        ("add", "Register a team."),
+        ("remove", "Remove a team and its memberships. The persons stay."),
+    ):
+        action = team_actions.add_parser(name, help=text, description=text)
+        action.add_argument("slug", type=_slug, help=SLUG_HELP)
+
+    member = parts.add_parser(
+        "member",
+        help="Add or remove a team member.",
+        description=("Add a registered person to a team, or remove the person from the team."),
+    )
+    member_actions = member.add_subparsers(dest="action", required=True, metavar="ACTION")
+    for name, text in (
+        ("add", "Add a person to a team."),
+        ("remove", "Remove a person from a team."),
+    ):
+        action = member_actions.add_parser(name, help=text, description=text)
+        action.add_argument("slug", type=_slug, help=SLUG_HELP)
+        action.add_argument("handle", type=_handle, help=HANDLE_HELP)
+
+    agent = parts.add_parser(
+        "agent",
+        help="Add or remove an agent that acts for a person.",
+        description=(
+            "Add or remove an agent that acts for a person. An Authentik service account is "
+            "found by its subject (sub), and a rauthy client by its client identifier."
+        ),
+    )
+    agent_actions = agent.add_subparsers(dest="action", required=True, metavar="ACTION")
+    agent_add = agent_actions.add_parser(
+        "add",
+        help="Register an agent.",
+        description="Register an agent. It reads nothing until it has a grant.",
+    )
+    agent_add.add_argument("name", type=_agent_name, help=AGENT_HELP)
+    agent_add.add_argument(
+        "--person",
+        type=_handle,
+        required=True,
+        metavar="HANDLE",
+        help="The person that the agent acts for.",
+    )
+    agent_add.add_argument(
+        "--issuer",
+        type=_issuer_url,
+        required=True,
+        metavar="URL",
+        help="The issuer URL of the OIDC provider. Give the same text as CURU_MEMORY_OIDC_ISSUER.",
+    )
+    identity = agent_add.add_mutually_exclusive_group(required=True)
+    identity.add_argument(
+        "--subject", metavar="SUB", help="The subject identifier (sub) in the tokens of the agent."
+    )
+    identity.add_argument(
+        "--client",
+        metavar="ID",
+        help=(
+            "The client identifier of the agent, for a token with no sub or with this "
+            "identifier as sub."
+        ),
+    )
+    agent_remove = agent_actions.add_parser(
+        "remove",
+        help="Remove an agent and its grants.",
+        description="Remove an agent and its grants.",
+    )
+    agent_remove.add_argument("name", type=_agent_name, help=AGENT_HELP)
+
+    grant = parts.add_parser(
+        "grant",
+        help="Give an agent a role in one space.",
+        description=(
+            "Give an agent a role in one space for some days. The grant cannot give more "
+            "than the person of the agent has, now or later."
+        ),
+    )
+    grant.add_argument("agent", type=_agent_name, help=AGENT_HELP)
+    grant.add_argument(
+        "--space",
+        type=_space,
+        required=True,
+        metavar="SPACE",
+        help="The space: global, team/<slug> or personal/<handle>.",
+    )
+    grant.add_argument(
+        "--role",
+        choices=sorted(ROLE_NAMES.values()),
+        required=True,
+        help="The role in the space: read, write or admin.",
+    )
+    grant.add_argument(
+        "--days",
+        type=_days,
+        default=DEFAULT_GRANT_DAYS,
+        metavar="N",
+        help=(
+            f"The number of days of the grant, from 1 to {MAX_GRANT_DAYS}. "
+            f"The default is {DEFAULT_GRANT_DAYS}."
+        ),
+    )
+
+    revoke = parts.add_parser(
+        "revoke", help="End a grant.", description="End a grant from the next request."
+    )
+    revoke.add_argument("id", type=int, metavar="ID", help="The identifier of the grant.")
+
+    show = parts.add_parser(
+        "show",
+        help="Show the persons, the teams, the roles, and the agents with their live grants.",
+        description=(
+            "Show the persons, the teams, the members and the role of each person in each space. "
+            "It also lists each agent and its live grants."
+        ),
+    )
+    show.add_argument("--json", action="store_true", help="Print the access as one JSON object.")
+
+
+def _port(value: str) -> int:
+    try:
+        port = int(value)
+    except ValueError:
+        port = 0
+    if not 1 <= port <= 65535:
+        raise argparse.ArgumentTypeError(f"must be a whole number from 1 to 65535, not {value!r}")
+    return port
+
+
+def _limit(value: str) -> int:
+    try:
+        limit = int(value)
+    except ValueError:
+        limit = 0
+    if not 1 <= limit <= MAX_LIMIT:
+        raise argparse.ArgumentTypeError(
+            f"must be a whole number from 1 to {MAX_LIMIT}, not {value!r}"
+        )
+    return limit
+
+
+def _subject_options(parser: argparse.ArgumentParser, *, required: bool) -> None:
+    parser.add_argument(
+        "--issuer",
+        type=_issuer_url,
+        required=required,
+        metavar="URL",
+        help=(
+            "The issuer URL of the OIDC provider. Give the same text as CURU_MEMORY_OIDC_ISSUER."
+        ),
+    )
+    parser.add_argument(
+        "--subject",
+        required=required,
+        metavar="SUB",
+        help="The subject identifier (sub) in the tokens of the person. Give it with --issuer.",
+    )
+
+
+def _issuer_url(value: str) -> str:
+    parts = urlsplit(value)
+    if parts.scheme not in ("http", "https") or not parts.hostname:
+        raise argparse.ArgumentTypeError(f"the issuer must be an http or https URL, not {value!r}")
+    return value
+
+
+HANDLE_HELP = (
+    "The short name of the person: 1 to 40 characters from a to z, 0 to 9 and -, first a letter."
+)
+SLUG_HELP = (
+    "The short name of the team: 1 to 40 characters from a to z, 0 to 9 and -, first a letter."
+)
+
+
+def _handle(value: str) -> str:
+    try:
+        return check_handle(value)
+    except ValueError as error:
+        raise argparse.ArgumentTypeError(str(error)) from None
+
+
+def _slug(value: str) -> str:
+    try:
+        return check_handle(value, "slug")
+    except ValueError as error:
+        raise argparse.ArgumentTypeError(str(error)) from None
+
+
+AGENT_HELP = "The name of the agent: 1 to 40 characters from a to z, 0 to 9 and -, first a letter."
+
+
+def _agent_name(value: str) -> str:
+    try:
+        return check_handle(value, "agent name")
+    except ValueError as error:
+        raise argparse.ArgumentTypeError(str(error)) from None
+
+
+def _days(value: str) -> int:
+    try:
+        days = int(value)
+    except ValueError:
+        days = 0
+    if not 1 <= days <= MAX_GRANT_DAYS:
+        raise argparse.ArgumentTypeError(
+            f"must be a whole number from 1 to {MAX_GRANT_DAYS}, not {value!r}"
+        )
+    return days
+
+
+def _space(value: str) -> str:
+    try:
+        return parse_space(value)
+    except ValueError as error:
+        raise argparse.ArgumentTypeError(str(error)) from None
+
+
+def main(argv: list[str] | None = None) -> NoReturn:
+    args = build_parser().parse_args(argv)
+    try:
+        settings = Settings.from_env()
+    except ConfigError as error:
+        _stop(str(error))
+    if args.command == "access":
+        sys.exit(_access(settings, args))
+    if args.command == "index":
+        sys.exit(_index(settings, args))
+    # The other commands read as the person of CURU_MEMORY_PRINCIPAL (ADR-016).
+    _check_principal(settings)
+    if args.command == "search":
+        sys.exit(_search(settings, args))
+    if args.command == "serve":
+        _serve(settings, args)
+        sys.exit(0)
+    if args.command == "browse":
+        _browse(settings, args)
+        sys.exit(0)
+    sys.exit(EXIT_USAGE)
+
+
+def make_embedder(settings: Settings) -> Embedder | None:
+    """The embedder of the settings, or None for a search of words only."""
+    if settings.embedder_url is None or settings.embedder_model is None:
+        return None
+    return OpenAICompatibleEmbedder(
+        settings.embedder_url,
+        settings.embedder_model,
+        token=settings.embedder_token,
+        timeout=settings.embedder_timeout,
+    )
+
+
+def _index(settings: Settings, args: argparse.Namespace) -> int:
+    concepts = args.concepts or settings.concepts_dir
+    if concepts is None:
+        _stop("Give the concept directory with --concepts or CURU_MEMORY_CONCEPTS_DIR.")
+    if not concepts.is_dir():
+        _stop(f"The concept directory {concepts} does not exist.")
+    store = SqliteIndexStore(settings.data_dir)
+    embedder = make_embedder(settings)
+    cache = SqliteEmbeddingCache(settings.data_dir / "embedding-cache.sqlite") if embedder else None
+    try:
+        report = build_index(
+            concepts,
+            store,
+            embedder,
+            cache=cache,
+            tier_space=args.space,
+            prompts=settings.prompts(),
+        )
+    except CuruMemoryError as error:
+        print(f"curu-memory: {error.message}", file=sys.stderr)
+        return EXIT_PROBLEM
+    except IndexLocked as error:
+        print(f"curu-memory: {error}", file=sys.stderr)
+        return EXIT_PROBLEM
+    finally:
+        if cache is not None:
+            cache.close()
+    index_path = store.path(args.space)
+    if args.json:
+        print(json.dumps({**report.to_dict(), "index": str(index_path)}, indent=2))
+    else:
+        print(report.render())
+        print(f"\nindex: {index_path}")
+    return EXIT_PROBLEM if report.skipped else 0
+
+
+def principal_of(settings: Settings) -> Principal:
+    return Principal.person(settings.principal) if settings.principal else ANONYMOUS
+
+
+def _check_principal(settings: Settings) -> None:
+    if settings.principal and AccessStore(settings.data_dir).person(settings.principal) is None:
+        _stop(
+            f"CURU_MEMORY_PRINCIPAL names {settings.principal!r}, but no person has that "
+            f"handle. Register the person with: curu-memory access person add "
+            f"{settings.principal}"
+        )
+
+
+def readable_for(settings: Settings) -> Callable[[], tuple[str, ...]]:
+    """The readable spaces of the principal, read again at each request (FR-013)."""
+    principal = principal_of(settings)
+    access = AccessStore(settings.data_dir)
+    index = SqliteIndexStore(settings.data_dir)
+    return lambda: readable_spaces_of(principal, access, index)
+
+
+def server_for(
+    settings: Settings,
+    inbound_token: str | None = None,
+    *,
+    stdio: bool = False,
+    resource: str | None = None,
+    grant: int | None = None,
+) -> MCPServer:
+    """The MCP server of `serve`, with the readable spaces of the principal.
+
+    With `CURU_MEMORY_OIDC_ISSUER` and HTTP, the person of each request comes from its
+    token (spec 012). Else the person is `CURU_MEMORY_PRINCIPAL`.
+    """
+    from curu_memory.server import build_server
+
+    if settings.oidc_issuer and not stdio:
+        return _oidc_server(settings, resource)
+    if grant is not None:
+        return _grant_server(settings, grant)
+    return build_server(
+        settings,
+        make_embedder(settings),
+        inbound_token,
+        readable=readable_for(settings),
+        audit=AuditLog(settings.data_dir),
+        principal=principal_of(settings).label,
+    )
+
+
+def _oidc_server(settings: Settings, resource: str | None) -> MCPServer:
+    from mcp.server.auth.settings import AuthSettings
+
+    from curu_memory.oidc import BasicExchange, OidcVerifier, principal_of_request
+    from curu_memory.server import build_server, use_basic_exchange
+
+    assert settings.oidc_issuer is not None
+    resource = settings.oidc_resource or resource or f"http://{DEFAULT_HOST}:{DEFAULT_PORT}/mcp"
+    access = AccessStore(settings.data_dir)
+    index = SqliteIndexStore(settings.data_dir)
+    audit = AuditLog(settings.data_dir)
+
+    verifier = OidcVerifier(
+        issuer=settings.oidc_issuer,
+        audience=settings.oidc_audience or resource,
+        token_types=settings.oidc_token_types,
+        access=access,
+        audit=audit,
+    )
+    server = build_server(
+        settings,
+        make_embedder(settings),
+        readable=lambda: _person_spaces(principal_of_request(), access, index),
+        audit=audit,
+        principal=lambda: principal_of_request().label,
+        acts_for=lambda: principal_of_request().acts_for,
+        token_verifier=verifier,
+        # curu-memory checks `aud` itself, from the audience setting (ADR-017).
+        auth=AuthSettings(
+            issuer_url=settings.oidc_issuer,
+            resource_server_url=resource,
+            validate_token_resource=False,
+        ),
+    )
+    if settings.oidc_basic_client_id:
+        # ADR-018: an agent may send its app password; it gets the same token checks.
+        exchange = BasicExchange(
+            client_id=settings.oidc_basic_client_id, keys=verifier.keys, audit=audit
+        )
+        use_basic_exchange(server, exchange)
+    return server
+
+
+def live_grant(settings: Settings, grant_id: int) -> tuple[Grant, Agent] | None:
+    """The grant and its agent, when the grant is live. Else None."""
+    access = AccessStore(settings.data_dir)
+    found = next((g for g in access.grants() if g.id == grant_id), None)
+    agent = access.agent(found.agent) if found is not None else None
+    if found is None or agent is None or not found.live(datetime.now(UTC)):
+        return None
+    return found, agent
+
+
+def _grant_server(settings: Settings, grant_id: int) -> MCPServer:
+    """A stdio server that acts as the agent of one grant (ADR-018). The limit is voluntary."""
+    from curu_memory.server import build_server
+
+    access = AccessStore(settings.data_dir)
+
+    def spaces() -> tuple[str, ...]:
+        found = live_grant(settings, grant_id)
+        if found is None:
+            return ()
+        grant, agent = found
+        # Only the space of this grant, and only while the person still has a role.
+        return (grant.space,) if role_of_agent(agent, grant.space, access) else ()
+
+    found = live_grant(settings, grant_id)
+    label = f"agent:{found[1].name}" if found else "anonymous"
+    acts_for = found[1].person if found else None
+    return build_server(
+        settings,
+        make_embedder(settings),
+        readable=spaces,
+        audit=AuditLog(settings.data_dir),
+        principal=label,
+        acts_for=lambda: acts_for,
+    )
+
+
+def _person_spaces(
+    principal: Principal, access: AccessStore, index: SqliteIndexStore
+) -> tuple[str, ...]:
+    # A request with no person reads nothing: in OIDC mode, each request has a token.
+    return readable_spaces_of(principal, access, index) if principal.handle else ()
+
+
+def browser_for(settings: Settings, token: str | None = None) -> Starlette:
+    """The browser app of `browse`, with the readable spaces of the principal."""
+    from curu_memory.browser import build_browser
+
+    return build_browser(
+        settings,
+        make_embedder(settings),
+        token,
+        readable=readable_for(settings),
+        audit=AuditLog(settings.data_dir),
+        principal=principal_of(settings).label,
+    )
+
+
+def _access(settings: Settings, args: argparse.Namespace) -> int:
+    pair = (getattr(args, "issuer", None) is None) != (getattr(args, "subject", None) is None)
+    if args.part == "person" and pair:
+        print("curu-memory: Give --issuer and --subject together.", file=sys.stderr)
+        return EXIT_USAGE
+    access = AccessStore(settings.data_dir)
+    try:
+        message = _change_access(access, args)
+    except AccessRefused as error:
+        print(f"curu-memory: {error}", file=sys.stderr)
+        return EXIT_PROBLEM
+    if message is not None:
+        text, space, subject = message
+        if args.part in ("grant", "revoke"):
+            action = "grant.add" if args.part == "grant" else "grant.revoke"
+        else:
+            action = f"{args.part}.{args.action}"
+        AuditLog(settings.data_dir).write("operator", action, space, CHANGED, text, subject=subject)
+        print(text)
+        return 0
+    view = access_view(access, SqliteIndexStore(settings.data_dir))
+    print(json.dumps(view, indent=2) if args.json else render_access(view))
+    return 0
+
+
+def _change_access(
+    access: AccessStore, args: argparse.Namespace
+) -> tuple[str, str | None, str | None] | None:
+    """Make one change. Give its message, its space and its subject. None for `show`."""
+    if args.part == "person" and args.action == "add":
+        person = access.add_person(
+            args.handle, owner=args.owner, issuer=args.issuer, subject=args.subject
+        )
+        text = f"added the person {person.handle}" + (" (owner)" if person.owner else "")
+        return text, None, args.handle
+    if args.part == "person" and args.action == "link":
+        access.link_person(args.handle, args.issuer, args.subject)
+        return f"linked the person {args.handle} to a subject of {args.issuer}", None, args.handle
+    if args.part == "person":
+        access.remove_person(args.handle)
+        # A new person with the same handle would read the old index (review of spec 011).
+        text = (
+            f"removed the person {args.handle} and its agents. The space "
+            f"personal/{args.handle} keeps its index. Delete "
+            f"{space_file_name('personal/' + args.handle)} in the data directory, else a new "
+            "person with this handle reads it."
+        )
+        return text, None, args.handle
+    if args.part == "team" and args.action == "add":
+        access.add_team(args.slug)
+        return f"added the team {args.slug}", f"team/{args.slug}", args.slug
+    if args.part == "team":
+        access.remove_team(args.slug)
+        text = (
+            f"removed the team {args.slug} and its memberships. The space team/{args.slug} "
+            f"keeps its index. Delete {space_file_name('team/' + args.slug)} in the data "
+            "directory, else a new team with this slug reads it."
+        )
+        return text, f"team/{args.slug}", args.slug
+    if args.part == "member" and args.action == "add":
+        access.add_member(args.slug, args.handle)
+        text = f"added {args.handle} to the team {args.slug}"
+        return text, f"team/{args.slug}", f"{args.slug}:{args.handle}"
+    if args.part == "member":
+        access.remove_member(args.slug, args.handle)
+        text = f"removed {args.handle} from the team {args.slug}"
+        return text, f"team/{args.slug}", f"{args.slug}:{args.handle}"
+    if args.part == "agent" and args.action == "add":
+        agent = access.add_agent(
+            args.name,
+            person=args.person,
+            issuer=args.issuer,
+            subject=args.subject,
+            client_id=args.client,
+        )
+        return f"added the agent {agent.name} for {agent.person}", None, agent.name
+    if args.part == "agent":
+        access.remove_agent(args.name)
+        return f"removed the agent {args.name} and its grants", None, args.name
+    if args.part == "grant":
+        role = {name: value for value, name in ROLE_NAMES.items()}[args.role]
+        granted = access.add_grant(args.agent, space=args.space, role=role, days=args.days)
+        text = (
+            f"granted {args.role} on {granted.space} to {granted.agent} until "
+            f"{granted.ends:%Y-%m-%d %H:%M} UTC (grant {granted.id})"
+        )
+        return text, granted.space, granted.agent
+    if args.part == "revoke":
+        revoked = access.revoke_grant(args.id)
+        return f"revoked the grant {revoked.id} of {revoked.agent}", revoked.space, revoked.agent
+    return None
+
+
+def access_view(access: AccessStore, index: SqliteIndexStore) -> dict[str, Any]:
+    """The persons, the teams, the role of each person in each space, and the agents."""
+    now = datetime.now(UTC)
+    persons = access.persons()
+    teams = access.teams()
+    spaces = sorted(
+        {GLOBAL, *index.spaces(), *(f"team/{s}" for s in teams)}
+        | {f"personal/{p.handle}" for p in persons}
+    )
+    roles: dict[str, dict[str, str]] = {}
+    for person in persons:
+        mine = access.teams_of(person.handle)
+        found = {space: role_in(person, space, mine) for space in spaces}
+        roles[person.handle] = {s: ROLE_NAMES[r] for s, r in found.items() if r is not None}
+    return {
+        "persons": [
+            {"handle": p.handle, "owner": p.owner, "issuer": p.issuer, "subject": p.subject}
+            for p in persons
+        ],
+        "teams": [{"slug": slug, "members": list(access.members(slug))} for slug in teams],
+        "roles": roles,
+        "agents": [
+            {
+                "name": agent.name,
+                "person": agent.person,
+                "issuer": agent.issuer,
+                "subject": agent.subject,
+                "client_id": agent.client_id,
+                "grants": [
+                    {
+                        "id": g.id,
+                        "space": g.space,
+                        "role": ROLE_NAMES[g.role],
+                        "ends": g.ends.isoformat(),
+                    }
+                    for g in access.grants(agent=agent.name)
+                    if g.live(now)
+                ],
+            }
+            for agent in access.agents()
+        ],
+    }
+
+
+def render_access(view: dict[str, Any]) -> str:
+    lines = ["persons:"]
+    for person in view["persons"]:
+        lines.append(f"  {person['handle']}" + (" (owner)" if person["owner"] else ""))
+    lines.append("teams:")
+    for team in view["teams"]:
+        lines.append(f"  {team['slug']}: {', '.join(team['members']) or 'no members'}")
+    lines.append("roles:")
+    for handle, roles in view["roles"].items():
+        for space, role in roles.items():
+            lines.append(f"  {handle} {space}: {role}")
+    lines.append("agents:")
+    for agent in view["agents"]:
+        if not agent["grants"]:
+            lines.append(f"  {agent['name']} (for {agent['person']}): no live grant")
+        for grant in agent["grants"]:
+            ends = grant["ends"][:16].replace("T", " ")
+            lines.append(
+                f"  {agent['name']} (for {agent['person']}): {grant['space']} "
+                f"{grant['role']} until {ends} UTC (grant {grant['id']})"
+            )
+    return "\n".join(lines)
+
+
+def _search(settings: Settings, args: argparse.Namespace) -> int:
+    store = SqliteIndexStore(settings.data_dir)
+    retriever = retriever_for(settings, store, make_embedder(settings))
+    spaces = readable_for(settings)()
+    if not spaces:
+        AuditLog(settings.data_dir).write(
+            principal_of(settings).label, "search", None, REFUSED, "no role in any space"
+        )
+        print("curu-memory: The principal can read no space.", file=sys.stderr)
+        return EXIT_PROBLEM
+    if (args.question is None) == (args.media is None):
+        print("curu-memory: Give a question or --media, but not both.", file=sys.stderr)
+        return EXIT_USAGE
+    try:
+        if args.media is not None:
+            question = read_query_media(_read_media_file(args.media))
+            result = retriever.search_media(
+                question, args.limit, args.types, args.tags, spaces=spaces
+            )
+        else:
+            result = retriever.search(
+                args.question, args.limit, args.types, args.tags, spaces=spaces
+            )
+    except IndexMissing as error:
+        print(f"curu-memory: {error.message}", file=sys.stderr)
+        return EXIT_PROBLEM
+    except InvalidArgument as error:
+        print(f"curu-memory: {error.message}", file=sys.stderr)
+        return EXIT_USAGE
+    if args.json:
+        print(result.model_dump_json(indent=2))
+    else:
+        print(render_search(result))
+    return 0
+
+
+def _read_media_file(path: Path) -> bytes:
+    """The bytes of a media file, read only up to the size limit plus one byte."""
+    try:
+        with path.open("rb") as file:
+            return file.read(MAX_BYTES + 1)
+    except OSError as error:
+        reason = error.strerror or type(error).__name__
+        raise InvalidArgument("media", f"The media file cannot be read: {reason}.") from None
+
+
+def _serve(settings: Settings, args: argparse.Namespace) -> None:
+    # Imported here, so that index and search do not load the MCP server.
+
+    logging.basicConfig(stream=sys.stderr, level=logging.WARNING)
+    if args.grant is not None and args.transport != "stdio":
+        # A grant limits one local process. On HTTP, the token of each request decides.
+        print(
+            "curu-memory: --grant works only with --transport stdio. On HTTP, give the "
+            "agent a token of the issuer, and the grants of that agent apply.",
+            file=sys.stderr,
+        )
+        sys.exit(EXIT_USAGE)
+    if args.transport == "stdio":
+        if args.grant is not None and live_grant(settings, args.grant) is None:
+            _stop(f"The grant {args.grant} is not live. It does not exist, ended or was revoked.")
+        server_for(settings, stdio=True, grant=args.grant).run("stdio")
+        return
+    if settings.oidc_issuer:
+        if settings.http_token:
+            # The static token is the basic mode only with no OIDC provider (the owner).
+            print(
+                "curu-memory: CURU_MEMORY_OIDC_ISSUER is set, so serve ignores "
+                "CURU_MEMORY_HTTP_TOKEN. Each request needs a token of the issuer. "
+                "The browser still uses CURU_MEMORY_HTTP_TOKEN.",
+                file=sys.stderr,
+            )
+        _serve_http(server_for(settings, resource=f"http://{args.host}:{args.port}/mcp"), args)
+        return
+    token = settings.http_token
+    if token is None or len(token) < MIN_TOKEN_LENGTH:
+        _stop(
+            f"HTTP needs a token of {MIN_TOKEN_LENGTH} characters or more in "
+            f"CURU_MEMORY_HTTP_TOKEN. Make one with: {MAKE_TOKEN}"
+        )
+    logging.getLogger("uvicorn.access").addFilter(drop_query_string)
+
+    _serve_http(server_for(settings, inbound_token=token), args)
+
+
+def _serve_http(server: MCPServer, args: argparse.Namespace) -> None:
+    import uvicorn
+
+    from curu_memory.server import http_app
+
+    logging.getLogger("uvicorn.access").addFilter(drop_query_string)
+    # "info" keeps one access-log line for each request, as the SDK runner did.
+    uvicorn.run(http_app(server, args.host), host=args.host, port=args.port, log_level="info")
+
+
+def _browse(settings: Settings, args: argparse.Namespace) -> None:
+    import uvicorn
+
+    token = None
+    if args.host not in LOOPBACK:
+        token = settings.http_token
+        if token is None or len(token) < MIN_TOKEN_LENGTH:
+            _stop(
+                f"The browser on {args.host} needs a token of {MIN_TOKEN_LENGTH} characters "
+                f"or more in CURU_MEMORY_HTTP_TOKEN. Make one with: {MAKE_TOKEN}"
+            )
+    logging.getLogger("uvicorn.access").addFilter(drop_query_string)
+    app = browser_for(settings, token=token)
+    print(f"curu-memory: the browser is at http://{args.host}:{args.port}/", file=sys.stderr)
+    uvicorn.run(app, host=args.host, port=args.port, log_level="warning")
+
+
+def drop_query_string(record: logging.LogRecord) -> bool:
+    """Remove the query string from an access-log line (constitution, article IV).
+
+    A client can put the token in the query string by mistake. curu-memory refuses
+    that request, but uvicorn would still log the full path with the token.
+    """
+    args = record.args
+    if isinstance(args, tuple) and len(args) >= 3 and isinstance(args[2], str):
+        record.args = (*args[:2], args[2].split("?", 1)[0], *args[3:])
+    return True
+
+
+def render_search(result: SearchResult) -> str:
+    lines: list[str] = []
+    for number, hit in enumerate(result.results, start=1):
+        lines.append(f"{number}. {hit.id}: {hit.title} ({hit.type}), score {hit.score:.4f}")
+        lines.append(f"   {hit.description}")
+        lines.append(f"   space: {hit.space}")
+        if hit.matched_unit:
+            lines.append(f"   matched: {hit.matched_unit} ({hit.matched_kind})")
+        if hit.tags:
+            lines.append(f"   tags: {', '.join(hit.tags)}")
+        for source in hit.sources:
+            label = source.get("title") or source.get("id") or "source"
+            resource = source.get("resource")
+            lines.append(f"   source: {label}" + (f" ({resource})" if resource else ""))
+    lines.append(f"mode: {result.mode}")
+    if result.notice:
+        lines.append(f"notice: {result.notice}")
+    return "\n".join(lines)
+
+
+def _stop(message: str) -> NoReturn:
+    print(f"curu-memory: {message}", file=sys.stderr)
+    sys.exit(EXIT_CONFIG)
+
+
+if __name__ == "__main__":
+    main()