Give the system a directory: ask who knows, then ask them

A memory system that only answers from its own store is a filing cabinet,
not a partner. The transactive rule the project is named for — not knowing
is fine when you know who does — needed a holder registry, a directory
query, and a referral that never leaks the text it may not read.

- schema v5 adds `holders` (person/agent/service, declared topics, contact).
  A holder with memories exists whether or not anybody registered them; the
  registry adds reachability, it does not grant existence.
- `who_knows` ranks holders by their own memories and is deliberately NOT
  filtered by visibility: "she knows" is the answer. The answer is filtered.
- `ask` searches the asker's visible scope first (hop 0), then walks the
  directory with a visited set and a hop budget. Three terminal states:
  answered, referred, no_holder_knows. Nobody knowing is a result, not an error.
- Confidence is ordinal, not calibrated: relative strength, coverage, and
  declared topics. Every hit carries the raw numbers and the basis lines that
  produced the score, so a ranking can be argued with.
- Faces: HTTP (/api/holders, /api/who_knows, /api/ask), CLI (holders,
  holder-set, holder-rm, who-knows, ask), MCP (who_knows, ask, list_holders).

Four bugs found by running the thing, not by reading it:
- FTS5 refuses bm25() inside MAX(); the aggregate uses FTS5's own `rank` column.
- A CJK question is longer than the sentence that answers it, so the whole-run
  phrase matched nothing. The query now ORs adjacent bigram phrases; adjacency
  is kept, equal length is not. Latin path untouched, baseline unaffected.
- The hop budget counted the asker as a hop, so max_hops=1 asked nobody.
- A second, stricter readability test in _answered() disagreed with the SQL
  visibility clause and hid a memory the asker was allowed to read. The SQL
  clause is the only authority now.

A method named `list` shadowed the builtin inside its own class and made
mypy reject the return annotation; renamed rather than cast around it.

Proof: 155 pytest, 12 Go tests, ruff and mypy clean on touched files, pyright
ledger unchanged at 62, and scripts/mcp_write_smoke.sh drives two principals
on one SQLite file — the husband asks through MCP, gets `referred` with his
wife's contact channel, and her private sentence appears nowhere in the reply.

backend/pyproject.toml

@@ -51,3 +51,7 @@ where = ["src"]
 line-length = 100
 target-version = "py312"
 
+[tool.ruff.lint]
+# Typer requires an option default to be a typer.Option call, which is what B008 forbids.
+ignore = ["B008"]
+

backend/src/ely_eye/api.py

@@ -11,6 +11,7 @@ from pydantic import BaseModel
 
 from . import __version__
 from .api_cartridges import register as register_cartridge_routes
+from .api_holders import register as register_holder_routes
 from .benchmarks import (
     benchmark_prediction_report,
     benchmark_registry_report,
@@ -246,6 +247,7 @@ def create_app() -> FastAPI:
             raise HTTPException(status_code=422, detail=str(exc)) from exc
 
     register_cartridge_routes(app, settings_dep)
+    register_holder_routes(app, settings_dep)
 
     @app.get("/api/adapters", response_model=list[AdapterStatus])
     def adapters(settings: Annotated[Settings, Depends(settings_dep)]) -> list[AdapterStatus]:

backend/src/ely_eye/api_holders.py

@@ -0,0 +1,118 @@
+"""Holder registry, who-knows, and referral routes: the directory side of the store.
+
+No `from __future__ import annotations` here: FastAPI reads these route signatures, and string
+annotations would be resolved against module globals, where the injected settings_dep exists
+only as a parameter of register().
+"""
+
+from collections.abc import Callable
+from typing import Annotated
+
+from fastapi import Depends, FastAPI, HTTPException
+
+from .config import Settings
+from .db import Database
+from .holder_store import HolderStore
+from .schemas import utc_now
+from .transactive import TransactiveService
+from .transactive_schemas import (
+    AskRequest,
+    Holder,
+    HolderUpsertRequest,
+    ReferralAnswer,
+    WhoKnowsReport,
+    WhoKnowsRequest,
+)
+
+
+def register(app: FastAPI, settings_dep: Callable[[], Settings]) -> None:
+    """Register the transactive routes. The server owns the timestamps, the caller does not."""
+
+    def store(settings: Settings) -> HolderStore:
+        return HolderStore(Database(settings))
+
+    @app.get("/api/holders", response_model=list[Holder])
+    def holders(settings: Annotated[Settings, Depends(settings_dep)]) -> list[Holder]:
+        return store(settings).list_holders()
+
+    @app.post("/api/holders/{holder_id}", response_model=Holder)
+    def put_holder(
+        holder_id: str,
+        request: HolderUpsertRequest,
+        settings: Annotated[Settings, Depends(settings_dep)],
+    ) -> Holder:
+        now = utc_now()
+        entry = Holder(
+            holder_id=holder_id,
+            created_at=now,
+            updated_at=now,
+            **request.model_dump(),
+        )
+        try:
+            return store(settings).upsert(entry)
+        except ValueError as exc:
+            raise HTTPException(status_code=422, detail=str(exc)) from exc
+
+    @app.get("/api/holders/{holder_id}", response_model=Holder)
+    def get_holder(
+        holder_id: str,
+        settings: Annotated[Settings, Depends(settings_dep)],
+    ) -> Holder:
+        entry = store(settings).get(holder_id)
+        if entry is None:
+            raise HTTPException(status_code=404, detail=f"no holder {holder_id!r} is registered")
+        return entry
+
+    @app.delete("/api/holders/{holder_id}", response_model=Holder)
+    def delete_holder(
+        holder_id: str,
+        settings: Annotated[Settings, Depends(settings_dep)],
+    ) -> Holder:
+        registry = store(settings)
+        entry = registry.get(holder_id)
+        if entry is None:
+            raise HTTPException(status_code=404, detail=f"no holder {holder_id!r} is registered")
+        try:
+            registry.delete(holder_id)
+        except ValueError as exc:
+            raise HTTPException(status_code=409, detail=str(exc)) from exc
+        return entry
+
+    @app.get("/api/holders/{holder_id}/knows", response_model=WhoKnowsReport)
+    def holder_knows(
+        holder_id: str,
+        query: str,
+        settings: Annotated[Settings, Depends(settings_dep)],
+    ) -> WhoKnowsReport:
+        """What this holder knows about, as a ranked directory answer."""
+        try:
+            return TransactiveService(settings).who_knows(query, as_holder=holder_id)
+        except ValueError as exc:
+            raise HTTPException(status_code=422, detail=str(exc)) from exc
+
+    @app.post("/api/who_knows", response_model=WhoKnowsReport)
+    def who_knows(
+        request: WhoKnowsRequest,
+        settings: Annotated[Settings, Depends(settings_dep)],
+    ) -> WhoKnowsReport:
+        try:
+            return TransactiveService(settings).who_knows(
+                request.query, as_holder=request.as_holder, limit=request.limit
+            )
+        except ValueError as exc:
+            raise HTTPException(status_code=422, detail=str(exc)) from exc
+
+    @app.post("/api/ask", response_model=ReferralAnswer)
+    def ask(
+        request: AskRequest,
+        settings: Annotated[Settings, Depends(settings_dep)],
+    ) -> ReferralAnswer:
+        try:
+            return TransactiveService(settings).ask(
+                request.question,
+                as_holder=request.as_holder,
+                max_hops=request.max_hops,
+                include_text=request.include_text,
+            )
+        except ValueError as exc:
+            raise HTTPException(status_code=422, detail=str(exc)) from exc

backend/src/ely_eye/cli.py

@@ -16,6 +16,7 @@ from .benchmarks import (
 )
 from .cartridge import CartridgeService
 from .cartridge_assets import CartridgeAssetService
+from .cli_transactive import register as register_transactive_commands
 from .config import get_settings
 from .db import Database
 from .embeddings import EmbeddingService
@@ -38,6 +39,9 @@ def json_dump(value: object) -> str:
     return json.dumps(value, ensure_ascii=False, indent=2)
 
 
+register_transactive_commands(app, lambda: get_settings())
+
+
 @app.command()
 def serve(host: str = "127.0.0.1", port: int = 8765) -> None:
     uvicorn.run(create_app(), host=host, port=port)
@@ -202,7 +206,7 @@ def unmount(cartridge_id: str) -> None:
 @app.command()
 def append(
     cartridge_id: str,
-    atom_id: list[str] = typer.Option(..., "--atom-id"),  # noqa: B008  # typer reads option defaults itself
+    atom_id: list[str] = typer.Option(..., "--atom-id"),
 ) -> None:
     """Add memories to an existing cartridge; the bundle and its DNA follow."""
     service = CartridgeService(get_settings())
@@ -352,7 +356,7 @@ def build_visual_training_data(
     prd_path: Path = Path("PRD.md"),
     output_path: Path | None = None,
     cartridge_id: str | None = None,
-    image_path: list[Path] | None = typer.Option(None, "--image-path"),  # noqa: B008  # typer reads option defaults itself
+    image_path: list[Path] | None = typer.Option(None, "--image-path"),
 ) -> None:
     path = TrainingService(get_settings()).build_visual_dataset(
         prd_path=prd_path,

backend/src/ely_eye/cli_transactive.py

@@ -0,0 +1,100 @@
+"""CLI face for the directory: register holders, ask who knows, ask and get referred.
+
+Registered onto the main Typer app so the command names stay flat (`ely-eye who-knows`), while
+the transactive surface stays in one file.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+
+import typer
+
+from .config import Settings
+from .db import Database
+from .holder_store import HolderStore
+from .schemas import utc_now
+from .transactive import TransactiveService
+from .transactive_schemas import Holder, HolderKind
+
+
+def register(app: typer.Typer, settings: Callable[[], Settings]) -> None:
+    """Add the holder and referral commands. The caller passes a settings thunk so one patch
+    in a test redirects every command, the same way the cartridge routes do."""
+
+    def store() -> HolderStore:
+        return HolderStore(Database(settings()))
+
+    def asker(as_holder: str) -> str:
+        """An empty --as-holder means the local principal, the same identity `remember` writes as."""
+        return as_holder or settings().default_holder
+
+    @app.command("holders")
+    def holders() -> None:
+        """List registered holders: the directory a referral walks."""
+        for entry in store().list_holders():
+            typer.echo(entry.model_dump_json(indent=2))
+
+    @app.command("holder-set")
+    def holder_set(
+        holder_id: str,
+        name: str = "",
+        kind: HolderKind = "person",
+        knows_about: list[str] = typer.Option(None, "--knows-about"),
+        contact: list[str] = typer.Option(None, "--contact", help="key=value, repeatable"),
+    ) -> None:
+        """Create or replace one holder entry."""
+        now = utc_now()
+        entry = Holder(
+            holder_id=holder_id,
+            name=name,
+            kind=kind,
+            knows_about=list(knows_about or []),
+            contact=_pairs(contact),
+            created_at=now,
+            updated_at=now,
+        )
+        typer.echo(store().upsert(entry).model_dump_json(indent=2))
+
+    @app.command("holder-rm")
+    def holder_rm(holder_id: str) -> None:
+        """Delete a holder. Refuses while that holder still owns memories."""
+        store().delete(holder_id)
+        typer.echo(f'{{"deleted": "{holder_id}"}}')
+
+    @app.command("who-knows")
+    def who_knows(query: str, as_holder: str = "", limit: int = 8) -> None:
+        """Rank the holders whose memories answer this query."""
+        report = TransactiveService(settings()).who_knows(
+            query, as_holder=asker(as_holder), limit=limit
+        )
+        typer.echo(report.model_dump_json(indent=2))
+
+    @app.command()
+    def ask(
+        question: str,
+        as_holder: str = "",
+        max_hops: int = 3,
+        include_text: bool = typer.Option(
+            False, "--include-text", help="show the memory text when the asker may already read it"
+        ),
+    ) -> None:
+        """Ask the store, then whoever knows. An unanswered question says nobody knows."""
+        answer = TransactiveService(settings()).ask(
+            question,
+            as_holder=asker(as_holder),
+            max_hops=max_hops,
+            include_text=include_text,
+        )
+        typer.echo(answer.model_dump_json(indent=2))
+
+
+def _pairs(values: list[str] | None) -> dict[str, str]:
+    """Turn repeatable key=value options into a contact map, naming any entry that is not one."""
+    contact: dict[str, str] = {}
+    for value in values or []:
+        key, separator, detail = value.partition("=")
+        if not separator or not key.strip():
+            raise ValueError(f"--contact needs key=value, got {value!r}")
+        contact[key.strip()] = detail
+    return contact

backend/src/ely_eye/db.py

@@ -188,12 +188,18 @@ class Database:
         until: datetime | None = None,
         min_trust: float | None = None,
         cartridge_ids: list[str] | None = None,
+        as_holder: str | None = None,
     ) -> FtsPage:
         """BM25 over the FTS index joined to memories that are open right now.
 
         Every filter is a `? IS NULL OR` predicate in one literal statement: the ranking never
         depends on string-built SQL, and the planner sees one shape. A memory with no event time
         cannot answer a time filter, so it drops out when one is asked for.
+
+        `as_holder` applies the sharing rule: a memory is readable by its owner, by anyone named
+        in its visible_to list, by everyone when it is public, and by anyone when nobody owns it.
+        A memory with no holder cannot be private to a holder that does not exist. Without an
+        asker the query runs over the whole library, which is what an operator debugging wants.
         """
         with self.connect() as connection:
             rows = connection.execute(
@@ -221,6 +227,13 @@ class Database:
                         WHERE ca.atom_id = f.atom_id
                           AND ca.cartridge_id IN (SELECT value FROM json_each(?))
                   ))
+                  AND (? IS NULL OR a.holder_id = ''
+                        OR json_extract(a.visibility_json, '$.scope') = 'everyone'
+                        OR a.holder_id = ?
+                        OR EXISTS (
+                              SELECT 1 FROM json_each(json_extract(a.visibility_json, '$.holders'))
+                              WHERE value = ?
+                        ))
                 ORDER BY score
                 LIMIT ? OFFSET ?
                 """,
@@ -242,6 +255,9 @@ class Database:
                     min_trust,
                     None if cartridge_ids is None else to_json(cartridge_ids),
                     None if cartridge_ids is None else to_json(cartridge_ids),
+                    as_holder,
+                    as_holder,
+                    as_holder,
                     limit + 1,
                     offset,
                 ),

backend/src/ely_eye/holder_store.py

@@ -0,0 +1,173 @@
+"""The holder registry and the directory query: who holds a memory, and who knows a topic.
+
+A transactive memory system stores the directory, not the content: "I do not know where the
+keys are, I know my wife knows, and I can find my wife." That requires a holder entity the
+store can answer questions about, and it requires the answer to be a pointer with a reason,
+never a guess.
+"""
+
+from __future__ import annotations
+
+import sqlite3
+from dataclasses import dataclass
+from datetime import datetime
+from typing import cast
+
+from .db import Database
+from .row_codec import from_json, to_json
+from .schemas import utc_now
+from .text_index import fts_query
+from .transactive_schemas import Holder, HolderKind
+
+
+@dataclass(frozen=True)
+class WhoKnowsCount:
+    """One holder's evidence for one query, straight from the index."""
+
+    holder_id: str
+    matched: int
+    top_score: float
+    latest_time: str | None
+
+
+class HolderStore:
+    """CRUD for registered holders plus the raw counts who_knows is built from."""
+
+    def __init__(self, database: Database) -> None:
+        self.database = database
+
+    def upsert(self, holder: Holder) -> Holder:
+        """Insert or replace a registry entry, keeping the original creation time."""
+        now = utc_now().isoformat()
+        with self.database.connect() as connection:
+            existing = connection.execute(
+                "SELECT created_at FROM holders WHERE holder_id = ?", (holder.holder_id,)
+            ).fetchone()
+            created_at = str(existing["created_at"]) if existing is not None else now
+            stored = holder.model_copy(update={"created_at": _moment(created_at), "updated_at": _moment(now)})
+            connection.execute(
+                """
+                INSERT INTO holders (holder_id, name, kind, knows_about_json, contact_json, created_at, updated_at)
+                VALUES (?, ?, ?, ?, ?, ?, ?)
+                ON CONFLICT(holder_id) DO UPDATE SET
+                    name = excluded.name,
+                    kind = excluded.kind,
+                    knows_about_json = excluded.knows_about_json,
+                    contact_json = excluded.contact_json,
+                    updated_at = excluded.updated_at
+                """,
+                (
+                    stored.holder_id,
+                    stored.name,
+                    stored.kind,
+                    to_json(stored.knows_about),
+                    to_json(stored.contact),
+                    stored.created_at.isoformat(),
+                    stored.updated_at.isoformat(),
+                ),
+            )
+        return stored
+
+    def get(self, holder_id: str) -> Holder | None:
+        with self.database.connect() as connection:
+            row = connection.execute("SELECT * FROM holders WHERE holder_id = ?", (holder_id,)).fetchone()
+        return None if row is None else _row_to_holder(row)
+
+    def list_holders(self) -> list[Holder]:
+        with self.database.connect() as connection:
+            rows = connection.execute("SELECT * FROM holders ORDER BY holder_id").fetchall()
+        return [_row_to_holder(row) for row in rows]
+
+    def delete(self, holder_id: str) -> None:
+        """Remove a registry entry. Refuses while that holder still owns memories: forgetting a
+        phone number must not silently orphan the memories it points to."""
+        holding = self.atom_count(holder_id)
+        if holding:
+            raise ValueError(
+                f"holder {holder_id!r} still holds {holding} memories; forget them before deleting the holder"
+            )
+        with self.database.connect() as connection:
+            connection.execute("DELETE FROM holders WHERE holder_id = ?", (holder_id,))
+
+    def atom_count(self, holder_id: str) -> int:
+        with self.database.connect() as connection:
+            row = connection.execute(
+                "SELECT COUNT(*) AS n FROM v_atoms_current WHERE holder_id = ?", (holder_id,)
+            ).fetchone()
+        return int(row["n"])
+
+    def known_holders(self) -> list[str]:
+        """Every holder with at least one open memory, registered or not.
+
+        A person who has memories is a holder whether or not anybody registered them; the
+        registry adds declared topics and contact details, it does not grant existence.
+        """
+        with self.database.connect() as connection:
+            rows = connection.execute(
+                "SELECT DISTINCT holder_id FROM v_atoms_current WHERE holder_id <> '' ORDER BY holder_id"
+            ).fetchall()
+        return [str(row["holder_id"]) for row in rows]
+
+    def who_knows_counts(self, query: str, limit: int) -> list[WhoKnowsCount]:
+        """Rank holders by how well their own memories answer the query.
+
+        The directory is deliberately unfiltered by visibility: the whole point of transactive
+        memory is knowing that someone knows, even when their memory is private to them.
+
+        `rank` is FTS5's own bm25 column, and it is the only way to aggregate the score: SQLite
+        refuses bm25() inside MAX(), and refuses it in a subquery or window over a match.
+        """
+        with self.database.connect() as connection:
+            rows = connection.execute(
+                """
+                SELECT a.holder_id,
+                       COUNT(*) AS matched,
+                       -MAX(rank) AS top_score,
+                       MAX(COALESCE(a.event_time, a.ingested_at)) AS latest_time
+                FROM atom_fts AS f
+                JOIN v_atoms_current AS a ON a.atom_id = f.atom_id
+                WHERE atom_fts MATCH ?
+                  AND a.holder_id <> ''
+                GROUP BY a.holder_id
+                ORDER BY top_score DESC, matched DESC
+                LIMIT ?
+                """,
+                (fts_query(query), limit),
+            ).fetchall()
+        return [
+            WhoKnowsCount(
+                holder_id=str(row["holder_id"]),
+                matched=int(row["matched"]),
+                top_score=float(row["top_score"]),
+                latest_time=None if row["latest_time"] is None else str(row["latest_time"]),
+            )
+            for row in rows
+        ]
+
+
+def _moment(value: str) -> datetime:
+    parsed = datetime.fromisoformat(value)
+    if parsed.tzinfo is None:
+        raise ValueError(f"holder timestamps need an explicit offset, stored {value!r}")
+    return parsed
+
+
+_HOLDER_KINDS: tuple[HolderKind, ...] = ("person", "agent", "service")
+
+
+def _kind(value: str) -> HolderKind:
+    if value not in _HOLDER_KINDS:
+        raise ValueError(f"stored holder kind {value!r} is not one of person, agent, service")
+    return cast(HolderKind, value)
+
+
+def _row_to_holder(row: sqlite3.Row) -> Holder:
+    return Holder(
+        holder_id=str(row["holder_id"]),
+        name=str(row["name"]),
+        kind=_kind(str(row["kind"])),
+        knows_about=from_json(row["knows_about_json"], []),
+        contact=from_json(row["contact_json"], {}),
+        created_at=_moment(str(row["created_at"])),
+        updated_at=_moment(str(row["updated_at"])),
+    )

backend/src/ely_eye/migrations.py

@@ -14,7 +14,7 @@ import sqlite3
 
 from .text_index import index_text
 
-SCHEMA_VERSION = 4
+SCHEMA_VERSION = 5
 
 ATOM_COLUMNS_V2 = """
     atom_id TEXT PRIMARY KEY,
@@ -82,6 +82,21 @@ _BASE_TABLES = """
         mounted_at TEXT NOT NULL
     );
 
+    -- The directory of who may hold or answer a memory. A transactive system answers
+    -- "who knows this?" before it answers "what is this?", and it cannot do that without
+    -- an entity to point at. Contact details are free-form on purpose: the transport is
+    -- whoever wired this store together, not the schema.
+    CREATE TABLE IF NOT EXISTS holders (
+        holder_id TEXT PRIMARY KEY,
+        name TEXT NOT NULL DEFAULT '',
+        kind TEXT NOT NULL DEFAULT 'person'
+            CHECK (kind IN ('person', 'agent', 'service')),
+        knows_about_json TEXT NOT NULL DEFAULT '[]',
+        contact_json TEXT NOT NULL DEFAULT '{}',
+        created_at TEXT NOT NULL,
+        updated_at TEXT NOT NULL
+    );
+
     CREATE TABLE IF NOT EXISTS cache_events (
         id INTEGER PRIMARY KEY AUTOINCREMENT,
         ts TEXT NOT NULL,

backend/src/ely_eye/schemas.py

@@ -157,10 +157,12 @@ class SearchFilters(BaseModel):
     """Who may answer, in what setting, and how fresh the memory has to be.
 
     A memory with no event time cannot satisfy since/until, so it drops out when a time bound is
-    asked for rather than passing as unknown.
+    asked for rather than passing as unknown. `holder` restricts the answer to one holder's
+    memories; `as_holder` is the identity asking, and applies the sharing rule instead.
     """
 
     holder: str | None = None
+    as_holder: str | None = None
     scenario: str | None = None
     source_id: str | None = None
     modality: Modality | None = None

backend/src/ely_eye/text_index.py

@@ -42,7 +42,7 @@ def fts_query(query: str) -> str:
     terms = _bare(query).split()
     if not terms:
         raise ValueError(f"search needs at least one searchable word, got {query!r}")
-    return " ".join(_phrase(term) if _is_cjk(term) else f"{_quote(term)}*" for term in terms)
+    return " ".join(_cjk_phrase(term) if _is_cjk(term) else f"{_quote(term)}*" for term in terms)
 
 
 def _bare(text: str) -> str:
@@ -59,5 +59,17 @@ def _phrase(run: str) -> str:
     return '"' + " ".join(run) + '"'
 
 
+def _cjk_phrase(run: str) -> str:
+    """A CJK run stays adjacent, and a long question also reaches the pairs inside it.
+
+    The whole run as one phrase is the precise reading, and it is what a two-character word
+    needs. A question is usually longer than the sentence that answers it: 钥匙在哪里 will not
+    appear inside 我们的钥匙放在玄关抽屉里. Offering every adjacent pair as an alternative keeps
+    adjacency — 钥 and 匙 still have to touch — without demanding equal length.
+    """
+    phrases = list(dict.fromkeys([_phrase(run)] + [_phrase(run[start : start + 2]) for start in range(len(run) - 1)]))
+    return phrases[0] if len(phrases) == 1 else "(" + " OR ".join(phrases) + ")"
+
+
 def _quote(term: str) -> str:
     return '"' + term.replace('"', '""') + '"'

backend/src/ely_eye/transactive.py

@@ -0,0 +1,223 @@
+"""Ask the store who knows something, then ask them.
+
+The transactive rule this service implements: not knowing is fine when the directory knows
+where to send you. Three things follow, and each one is a failure mode if left implicit.
+
+- The directory is public, the content is not. `who_knows` counts every holder's matching
+  memories, including memories the asker may not read, because "she knows" is the answer.
+- A referral never invents an answer. If the asker may not read the holder's memories, the
+  result is a pointer plus contact details, and the text stays where it is.
+- Referral must terminate. Every hop records whom it asked, and the chain stops at the hop
+  limit or when every candidate has been asked once.
+"""
+
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Literal
+
+from .config import Settings, get_settings
+from .db import Database
+from .holder_store import HolderStore, WhoKnowsCount
+from .retrieval import RetrievalService
+from .schemas import SearchFilters
+from .text_index import index_text
+from .transactive_schemas import (
+    ReferralAnswer,
+    WhoKnowsHit,
+    WhoKnowsReport,
+)
+
+NO_HOLDER_KNOWS: Literal["no_holder_knows"] = "no_holder_knows"
+LIBRARY = "library"
+WHO_KNOWS_LIMIT = 8
+MAX_HOPS_LIMIT = 10
+
+# Confidence is ordinal: it orders candidates, it does not estimate a probability. The weights
+# say what the evidence is worth relative to itself, and every hit carries the raw numbers too.
+CONFIDENCE_SATURATE = 3
+WEIGHT_STRENGTH = 0.60
+WEIGHT_COVERAGE = 0.25
+WEIGHT_DECLARED = 0.15
+
+
+class TransactiveService:
+    """who_knows and ask, built on the holder registry and the same retrieval as search."""
+
+    def __init__(self, settings: Settings | None = None, database: Database | None = None) -> None:
+        self.settings = settings or get_settings()
+        self.db = database or Database(self.settings)
+        self.holders = HolderStore(self.db)
+        self.retrieval = RetrievalService(self.settings, self.db)
+
+    def who_knows(
+        self, query: str, *, as_holder: str | None = None, limit: int = WHO_KNOWS_LIMIT
+    ) -> WhoKnowsReport:
+        """Rank the holders whose own memories answer this query.
+
+        An empty result is the honest answer, not a fallback: nobody holds this, so the caller
+        should say so instead of paraphrasing something unrelated.
+        """
+        if not query.strip():
+            raise ValueError("who_knows needs a query")
+        if limit <= 0:
+            raise ValueError(f"who_knows needs a positive limit, got {limit}")
+        counts = self.holders.who_knows_counts(query, limit)
+        if not counts:
+            return WhoKnowsReport(query=query, as_holder=as_holder, status=NO_HOLDER_KNOWS, hits=[])
+        registered = {holder.holder_id: holder for holder in self.holders.list_holders()}
+        best = max(count.top_score for count in counts)
+        return WhoKnowsReport(
+            query=query,
+            as_holder=as_holder,
+            status="found",
+            hits=[
+                self._hit(count, best, registered.get(count.holder_id), query)
+                for count in counts
+            ],
+        )
+
+    def ask(
+        self,
+        question: str,
+        *,
+        as_holder: str | None = None,
+        max_hops: int = 3,
+        include_text: bool = False,
+    ) -> ReferralAnswer:
+        """Answer a question by asking the asker first, then the directory's best candidates.
+
+        `answered_by` is the asker when their own memory answered, `library` when an unowned
+        artifact did, and the holder whose memory answered otherwise. `referred` means somebody
+        knows but their memory is not readable by the asker.
+
+        `max_hops` counts the holders asked besides the asker: the asker's own memory is hop 0,
+        so max_hops=1 still asks the best candidate.
+        """
+        if not question.strip():
+            raise ValueError("ask needs a question")
+        if not 1 <= max_hops <= MAX_HOPS_LIMIT:
+            raise ValueError(f"ask needs max_hops between 1 and {MAX_HOPS_LIMIT}, got {max_hops}")
+
+        own = self._search(question, as_holder=as_holder, holder=None)
+        if own:
+            return self._answered(
+                question, as_holder, asked=[as_holder or LIBRARY], hops=0, hits=own, include_text=include_text
+            )
+
+        asked: list[str] = [as_holder or LIBRARY]
+        for hit in self.who_knows(question, as_holder=as_holder).hits:
+            if hit.holder_id in asked:
+                continue
+            if len(asked) - 1 >= max_hops:
+                break
+            asked.append(hit.holder_id)
+            readable = self._search(question, as_holder=as_holder, holder=hit.holder_id)
+            if readable:
+                return self._answered(
+                    question,
+                    as_holder,
+                    asked=asked,
+                    hops=len(asked) - 1,
+                    hits=readable,
+                    include_text=include_text,
+                )
+            return self._pointer(question, as_holder, asked, hit)
+        return ReferralAnswer(
+            question=question,
+            as_holder=as_holder,
+            status=NO_HOLDER_KNOWS,
+            asked=asked,
+            hops=len(asked) - 1,
+            basis=["no holder has a memory that answers this"],
+        )
+
+    def _search(self, query: str, *, as_holder: str | None, holder: str | None):
+        result = self.retrieval.search(
+            query,
+            top_k=5,
+            filters=SearchFilters(holder=holder, as_holder=as_holder),
+        )
+        return result.hits
+
+    def _answered(self, question, as_holder, *, asked, hops, hits, include_text) -> ReferralAnswer:
+        """The hits already passed the visibility clause in SQL, so they may be shown."""
+        top = hits[0]
+        owner = top.atom.holder_id or LIBRARY
+        return ReferralAnswer(
+            question=question,
+            as_holder=as_holder,
+            status="answered",
+            answered_by=owner,
+            asked=asked,
+            hops=hops,
+            atom_ids=[hit.atom.atom_id for hit in hits],
+            answer=top.atom.text if include_text else None,
+            basis=[
+                f"{len(hits)} memories readable by {as_holder or 'anyone'}",
+                f"best match scores {top.final_score:.2f}",
+                f"held by {owner}",
+            ],
+        )
+
+    def _pointer(self, question, as_holder, asked, hit: WhoKnowsHit) -> ReferralAnswer:
+        """The candidate knows but the asker cannot read it: return the contact, not the text."""
+        contact = hit.contact
+        return ReferralAnswer(
+            question=question,
+            as_holder=as_holder,
+            status="referred",
+            answered_by=hit.holder_id,
+            asked=asked,
+            hops=len(asked) - 1,
+            basis=[
+                f"{hit.holder_id} holds {hit.matched} matching memories the asker may not read",
+                f"best match scores {hit.top_score:.2f}",
+                f"reachable via {contact}" if contact else "no contact details registered",
+            ],
+        )
+
+    def _hit(self, count: WhoKnowsCount, best: float, holder, query: str) -> WhoKnowsHit:
+        declared = _declared_topics(holder.knows_about if holder else [], query)
+        strength = count.top_score / best if best > 0 else 0.0
+        coverage = min(1.0, count.matched / CONFIDENCE_SATURATE)
+        confidence = (
+            WEIGHT_STRENGTH * strength + WEIGHT_COVERAGE * coverage + WEIGHT_DECLARED * (1.0 if declared else 0.0)
+        )
+        basis = [
+            f"holds {count.matched} matching memories",
+            f"best match scores {count.top_score:.2f}",
+        ]
+        if count.latest_time:
+            basis.append(f"most recent memory is from {count.latest_time}")
+        if declared:
+            basis.append(f"declared topics: {', '.join(declared)}")
+        contact = dict(holder.contact) if holder else {}
+        if contact:
+            basis.append(f"reachable via {contact}")
+        return WhoKnowsHit(
+            holder_id=count.holder_id,
+            name=holder.name if holder else "",
+            confidence=round(confidence, 3),
+            matched=count.matched,
+            top_score=round(count.top_score, 3),
+            latest_time=None if count.latest_time is None else _as_moment(count.latest_time),
+            basis=basis,
+            contact=contact,
+        )
+
+
+def _as_moment(value: str) -> datetime:
+    """A stored timestamp that will not parse is a corrupt row, not a missing one."""
+    try:
+        return datetime.fromisoformat(value)
+    except ValueError as error:
+        raise ValueError(f"stored timestamp {value!r} is unreadable: {error}") from error
+
+
+def _declared_topics(topics: list[str], query: str) -> list[str]:
+    """Declared topics that share a searchable token with the query, using the index's own split."""
+    query_tokens = set(index_text(query).split())
+    if not query_tokens:
+        return []
+    return [topic for topic in topics if query_tokens & set(index_text(topic).split())]

backend/src/ely_eye/transactive_schemas.py

@@ -0,0 +1,115 @@
+"""Models for the directory side of memory: who exists, who knows what, and who answered.
+
+Confidence here is ordinal, not calibrated: it orders candidates by the evidence in front of
+us. Every model that carries a score also carries the raw evidence behind it, so a caller can
+disagree with the number without re-running the query.
+"""
+
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Literal
+
+from pydantic import BaseModel, Field, field_validator
+
+HolderKind = Literal["person", "agent", "service"]
+"""The registry's own vocabulary; migrations.py enforces the same set in the database."""
+
+
+class Holder(BaseModel):
+    """A registered person, agent, or service that can hold or answer memories."""
+
+    holder_id: str
+    name: str = ""
+    kind: HolderKind = "person"
+    knows_about: list[str] = Field(default_factory=list)
+    contact: dict[str, str] = Field(default_factory=dict)
+    created_at: datetime
+    updated_at: datetime
+
+    @field_validator("holder_id")
+    @classmethod
+    def _holder_id_is_usable(cls, value: str) -> str:
+        if not value.strip():
+            raise ValueError("holder_id cannot be blank; a directory entry has to name somebody")
+        return value.strip()
+
+
+class HolderUpsertRequest(BaseModel):
+    """What a caller may set about a holder. The id comes from the path, never the body."""
+
+    name: str = ""
+    kind: HolderKind = "person"
+    knows_about: list[str] = Field(default_factory=list)
+    contact: dict[str, str] = Field(default_factory=dict)
+
+
+class WhoKnowsHit(BaseModel):
+    """One candidate holder, the evidence for them, and how to reach them."""
+
+    holder_id: str
+    name: str = ""
+    confidence: float
+    matched: int
+    top_score: float
+    latest_time: datetime | None = None
+    basis: list[str] = Field(default_factory=list)
+    contact: dict[str, str] = Field(default_factory=dict)
+
+
+class WhoKnowsReport(BaseModel):
+    """The directory's answer to a question. `no_holder_knows` is a result, not a failure."""
+
+    query: str
+    as_holder: str | None = None
+    status: Literal["found", "no_holder_knows"]
+    hits: list[WhoKnowsHit] = Field(default_factory=list)
+
+
+class WhoKnowsRequest(BaseModel):
+    """Ask the directory who holds an answer."""
+
+    query: str
+    as_holder: str | None = None
+    limit: int = Field(default=8, gt=0)
+
+    @field_validator("query")
+    @classmethod
+    def _query_is_usable(cls, value: str) -> str:
+        if not value.strip():
+            raise ValueError("who_knows needs a query")
+        return value.strip()
+
+
+class AskRequest(BaseModel):
+    """Ask a question on behalf of one holder, allowing a bounded chain of referrals."""
+
+    question: str
+    as_holder: str | None = None
+    max_hops: int = 3
+    include_text: bool = False
+
+    @field_validator("question")
+    @classmethod
+    def _question_is_usable(cls, value: str) -> str:
+        if not value.strip():
+            raise ValueError("ask needs a question")
+        return value.strip()
+
+
+class ReferralAnswer(BaseModel):
+    """Who answered, who was asked along the way, and what may be shown.
+
+    `referred` means the directory found someone who knows but the asker may not read their
+    memory: the answer is the pointer and the contact, never the text.
+    """
+
+    question: str
+    as_holder: str | None = None
+    status: Literal["answered", "referred", "no_holder_knows"]
+    answered_by: str | None = None
+    asked: list[str] = Field(default_factory=list)
+    hops: int = 0
+    atom_ids: list[str] = Field(default_factory=list)
+    answer: str | None = None
+    basis: list[str] = Field(default_factory=list)

backend/tests/test_transactive.py

@@ -0,0 +1,249 @@
+"""The transactive test: I do not know where the keys are, I know my wife knows, I find my wife."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+import pytest
+from fastapi.testclient import TestClient
+from pydantic import ValidationError
+from typer.testing import CliRunner
+
+import ely_eye.api as api_module
+import ely_eye.cli as cli_module
+from ely_eye.cli import app
+from ely_eye.config import Settings
+from ely_eye.db import Database
+from ely_eye.ingestion import IngestionService
+from ely_eye.memory import MemoryService
+from ely_eye.migrations import SCHEMA_VERSION
+from ely_eye.schemas import MemoryOrigin, Visibility, utc_now
+from ely_eye.transactive import LIBRARY, NO_HOLDER_KNOWS, TransactiveService
+from ely_eye.transactive_schemas import Holder
+
+HOME_KEYS = "我们的钥匙放在玄关抽屉里"
+WORK_KEYS = "备用钥匙在办公室第二个抽屉里"
+QUERY = "钥匙"
+
+
+class Store:
+    """One SQLite file, the writer and the directory that read it."""
+
+    def __init__(self, settings: Settings) -> None:
+        self.settings = settings
+        self.memory = MemoryService(settings=settings)
+        self.db = self.memory.db
+        self.transactive = TransactiveService(settings=settings, database=self.db)
+
+    def wife_remembers(self, text: str, visibility: Visibility | None = None) -> str:
+        atom = self.memory.remember(
+            text, holder_id="wife", origin=MemoryOrigin.self_, scenario="home", visibility=visibility
+        )
+        return atom.atom_id
+
+    def husband_remembers(self, text: str) -> str:
+        atom = self.memory.remember(text, holder_id="husband", origin=MemoryOrigin.self_, scenario="home")
+        return atom.atom_id
+
+    def register(self, holder_id: str, **fields: Any) -> Holder:
+        moment = utc_now()
+        return self.transactive.holders.upsert(
+            Holder(holder_id=holder_id, created_at=moment, updated_at=moment, **fields)
+        )
+
+
+@pytest.fixture
+def store(tmp_path: Path) -> Store:
+    return Store(Settings(home=tmp_path / "home", default_holder="husband"))
+
+
+def test_the_directory_names_the_holder_and_says_why(store: Store) -> None:
+    store.wife_remembers(HOME_KEYS)
+    report = store.transactive.who_knows(QUERY, as_holder="husband")
+    assert report.status == "found"
+    assert report.hits[0].holder_id == "wife"
+    assert report.hits[0].confidence > 0.0
+    assert any("matching memories" in line for line in report.hits[0].basis)
+
+
+def test_the_directory_counts_a_memory_the_asker_cannot_read(store: Store) -> None:
+    """The whole point: knowing that she knows does not require reading her memory."""
+    store.wife_remembers(HOME_KEYS)
+    assert store.transactive.who_knows(QUERY, as_holder="husband").hits[0].matched == 1
+    assert store.transactive._search(QUERY, as_holder="husband", holder="wife") == []
+
+
+def test_a_private_memory_is_referred_and_not_leaked(store: Store) -> None:
+    store.register("wife", name="小美", contact={"channel": "signal", "address": "+86-555"})
+    store.wife_remembers(HOME_KEYS)
+    answer = store.transactive.ask("钥匙在哪里", as_holder="husband")
+    assert answer.status == "referred"
+    assert answer.answered_by == "wife"
+    assert answer.hops == 1
+    assert answer.asked == ["husband", "wife"]
+    assert answer.answer is None
+    assert answer.atom_ids == []
+    assert any("may not read" in line for line in answer.basis)
+    assert any("signal" in line for line in answer.basis)
+
+
+def test_the_askers_own_memory_answers_without_a_referral(store: Store) -> None:
+    store.wife_remembers(HOME_KEYS)
+    store.husband_remembers("我的工牌挂在显示器边上")
+    answer = store.transactive.ask("工牌", as_holder="husband")
+    assert answer.status == "answered"
+    assert answer.answered_by == "husband"
+    assert answer.hops == 0
+    assert answer.asked == ["husband"]
+    assert answer.answer is None
+
+
+def test_text_shown_only_when_the_asker_may_already_read_it(store: Store) -> None:
+    store.husband_remembers("我的工牌挂在显示器边上")
+    with_text = store.transactive.ask("工牌", as_holder="husband", include_text=True)
+    assert with_text.answer == "我的工牌挂在显示器边上"
+
+    store.register("wife")
+    store.wife_remembers(HOME_KEYS)
+    referred = store.transactive.ask("钥匙在哪里", as_holder="husband", include_text=True)
+    assert referred.status == "referred"
+    assert referred.answer is None
+
+
+def test_a_shared_memory_is_readable_without_a_referral(store: Store) -> None:
+    """A memory the asker may already read answers at hop 0: no referral, the text is shown."""
+    store.register("wife")
+    store.wife_remembers(HOME_KEYS, visibility=Visibility(scope="visible_to", holders=["husband"]))
+    answer = store.transactive.ask("钥匙在哪里", as_holder="husband", include_text=True)
+    assert answer.status == "answered"
+    assert answer.answered_by == "wife"
+    assert answer.hops == 0
+    assert answer.answer == HOME_KEYS
+
+
+def test_an_unowned_artifact_answers_as_the_library(store: Store) -> None:
+    notebook = store.settings.home / "notebook.txt"
+    notebook.write_text("the garage door code is written on the fuse box", encoding="utf-8")
+    IngestionService(store.settings).ingest_path(notebook)
+    answer = store.transactive.ask("garage door code", as_holder="wife", include_text=True)
+    assert answer.status == "answered"
+    assert answer.answered_by == LIBRARY
+    assert "fuse box" in (answer.answer or "")
+
+
+def test_nobody_knows_is_a_result_and_not_a_fabrication(store: Store) -> None:
+    store.wife_remembers(HOME_KEYS)
+    report = store.transactive.who_knows("潜水镜", as_holder="husband")
+    assert report.status == NO_HOLDER_KNOWS
+    assert report.hits == []
+
+    answer = store.transactive.ask("潜水镜在哪里", as_holder="husband")
+    assert answer.status == NO_HOLDER_KNOWS
+    assert answer.answered_by is None
+    assert answer.answer is None
+    assert answer.basis == ["no holder has a memory that answers this"]
+
+
+def test_the_referral_walks_once_and_never_asks_the_same_holder_twice(store: Store) -> None:
+    store.register("wife")
+    store.register("daughter")
+    store.wife_remembers(HOME_KEYS)
+    store.memory.remember(WORK_KEYS, holder_id="daughter", origin=MemoryOrigin.self_, scenario="work")
+    answer = store.transactive.ask("钥匙在哪里", as_holder="husband", max_hops=1)
+    assert answer.status in ("referred", "answered")
+    assert len(answer.asked) == 2
+    assert len(set(answer.asked)) == len(answer.asked)
+    assert answer.asked[0] == "husband"
+
+
+def test_the_hop_limit_is_enforced(store: Store) -> None:
+    for bad in (0, 11):
+        with pytest.raises(ValueError, match="max_hops between 1 and 10"):
+            store.transactive.ask(QUERY, as_holder="husband", max_hops=bad)
+
+
+def test_declared_topics_raise_the_confidence_and_say_so(store: Store) -> None:
+    store.wife_remembers(HOME_KEYS)
+    before = store.transactive.who_knows(QUERY, as_holder="husband").hits[0]
+    store.register("wife", knows_about=["家里的钥匙"])
+    after = store.transactive.who_knows(QUERY, as_holder="husband").hits[0]
+    assert after.confidence > before.confidence
+    assert any("declared topics" in line for line in after.basis)
+
+
+def test_the_registry_refuses_to_delete_a_holder_who_still_holds(store: Store) -> None:
+    store.register("wife")
+    atom_id = store.wife_remembers(HOME_KEYS)
+    with pytest.raises(ValueError, match="still holds 1 memories"):
+        store.transactive.holders.delete("wife")
+    store.memory.forget(atom_id=atom_id)
+    store.transactive.holders.delete("wife")
+    assert store.transactive.holders.list_holders() == []
+
+
+def test_an_unknown_holder_kind_is_refused_at_the_door() -> None:
+    with pytest.raises(ValidationError, match="'person', 'agent' or 'service'"):
+        Holder.model_validate({"holder_id": "ghost", "kind": "ghost", "created_at": utc_now(), "updated_at": utc_now()})
+
+
+def test_a_blank_holder_id_is_refused() -> None:
+    with pytest.raises(ValidationError, match="directory entry has to name somebody"):
+        Holder.model_validate({"holder_id": "  ", "created_at": utc_now(), "updated_at": utc_now()})
+
+
+def test_a_store_without_holders_gains_the_table_on_reopen(tmp_path: Path) -> None:
+    settings = Settings(home=tmp_path / "home", default_holder="husband")
+    database = Database(settings)
+    with database.connect() as connection:
+        connection.execute("DROP TABLE holders")
+        connection.execute("PRAGMA user_version = 4")
+    reopened = Database(settings)
+    with reopened.connect() as connection:
+        assert connection.execute("PRAGMA user_version").fetchone()[0] == SCHEMA_VERSION
+        assert connection.execute("SELECT COUNT(*) AS n FROM holders").fetchone()["n"] == 0
+
+
+def test_the_http_surface_serves_the_directory(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
+    settings = Settings(home=tmp_path / "home", default_holder="husband")
+    monkeypatch.setattr(api_module, "get_settings", lambda: settings)
+    client = TestClient(api_module.create_app())
+
+    store = Store(settings)
+    store.wife_remembers(HOME_KEYS)
+
+    created = client.post(
+        "/api/holders/wife",
+        json={"name": "小美", "knows_about": ["家里的钥匙"], "contact": {"channel": "signal"}},
+    )
+    assert created.status_code == 200
+    assert created.json()["holder_id"] == "wife"
+    assert client.get("/api/holders").json()[0]["name"] == "小美"
+    assert client.get("/api/holders/nobody").status_code == 404
+
+    knows = client.get("/api/holders/wife/knows", params={"query": QUERY}).json()
+    assert knows["status"] == "found" and knows["hits"][0]["holder_id"] == "wife"
+
+    asked = client.post("/api/ask", json={"question": "钥匙在哪里", "as_holder": "husband"}).json()
+    assert asked["status"] == "referred" and asked["answered_by"] == "wife"
+
+    who = client.post("/api/who_knows", json={"query": "钥匙", "as_holder": "husband"}).json()
+    assert who["hits"][0]["basis"]
+
+    blocked = client.delete("/api/holders/wife")
+    assert blocked.status_code == 409 and "still holds" in blocked.json()["detail"]
+
+
+def test_the_cli_asks_and_reports_the_referral(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
+    settings = Settings(home=tmp_path / "home", default_holder="husband")
+    monkeypatch.setattr(cli_module, "get_settings", lambda: settings)
+    runner = CliRunner()
+    Store(settings).wife_remembers(HOME_KEYS)
+
+    assert runner.invoke(app, ["holder-set", "wife", "--name", "小美", "--contact", "channel=signal"]).exit_code == 0
+    who = runner.invoke(app, ["who-knows", QUERY])
+    assert who.exit_code == 0 and '"holder_id": "wife"' in who.stdout
+    asked = runner.invoke(app, ["ask", "钥匙在哪里"])
+    assert asked.exit_code == 0 and '"status": "referred"' in asked.stdout
+    assert runner.invoke(app, ["holders"]).stdout.count("wife") >= 1
+    assert runner.invoke(app, ["holder-set", "wife", "--contact", "not-a-pair"]).exit_code != 0