[yw0nam]

Summary

The plugin prompt and the install docs named user_entity and namespace in one line each. They did not say what the values are, where to find them, or that a namespace must be registered first.

• connect-agent skill: a new step 2 picks the user entity (list_entities, or register_entity with consent) and the namespace. It states the two things a namespace changes: turns land in it, and session-start cards read facts from it alone. It also states what a namespace does not change: where save_memory writes, and the per-prompt search. Step 3 registers a new namespace with the minted key through POST /namespaces, entering the key at a silent prompt. Step 4 adds the namespace to each client's configuration. Step 5 adds the unregistered namespace refusal as a check.
• plugin.json: the User entity and Namespace option descriptions state what each value is and that an unregistered namespace is refused.
• Claude Code and Hermes READMEs: the same option rows, plus a pointer to the skill.

Related issues

Closes #382

Runtime evidence

The documented refusal, against the deployed server code (no row written):

$ docker exec -w /app memory_base_api uv run --no-sync python -c "... store.append({... 'namespace': 'not-registered-check' ...})"
ValueError -> unregistered namespace: not-registered-check
$ psql ... "select count(*) from memory.turns where session_id='doc-check'"
0

POST /turns maps this ValueError to 400 (turns/routes.py append_route).

Verification

• uv run pytest passes (tests/integrations: 158 passed; no source change)
• uv run ruff format --check . and uv run ruff check . pass — N/A, no Python change
• docker compose build mcp passes (Dockerfile / dependency changes) — N/A
• Runtime evidence attached above, or N/A justified

Checklist (core principles)

• Selective storage — notes stay distilled; verbatim text lives only in doc_rows and the turns lane
• Source-specific logic stays out of the source-agnostic core (ingest pipeline, retrieval, serving)
• No hardcoded endpoints/models — configuration lives in .env
• New/changed behavior ships a test in this PR (or skip-tests label justified) — docs only