feat(memory-primitive): Phase 1 — doctor framework + entrypoint integration

Adds the memory contract + doctor primitive per ADR-036, with no
provider adapters yet (Phase 2 adds hindsight on top of this).

Python package (lib/python/agentic_memory/):
- contract.py: MemoryContract dataclass + namespace validation +
  sanitization
- doctor.py: 8 Check classes covering env_contract, namespace shape,
  provider known, adapter exists, config_json valid, backend DNS,
  backend /health, and delegated provider_specific. CLI surface
  (--json, --verbose, --fix, --provider/namespace/url overrides).
  Exit 0 or 1 — no warning tier.
- tests/: 53 unit tests covering every check, every contract field,
  the CLI surface, and the runner. All passing under stdlib pytest.
- pyproject.toml declares console_scripts entry agentic-memory-doctor.

Workspace integration:
- providers/workspaces/claude-cli/memory/doctor: bash entry that
  exec's the Python module via /opt/venv's python.
- entrypoint.sh: new sections 5.6 (adapter init) and 5.7 (doctor
  preflight). Both no-op when AGENTIC_MEMORY_PROVIDER is unset.
  When the provider IS set: 5.6 sources /opt/agentic/memory/<p>/
  init.sh; 5.7 runs the doctor with --json appended to
  /var/agentic/memory-doctor/<YYYY-MM-DD>.jsonl, hard-fails the
  container on non-zero exit.
- Dockerfile: COPY memory/ /opt/agentic/memory/, create the audit
  dir at /var/agentic/memory-doctor/, set permissions on init.sh
  and doctor.sh files for all providers.

Build system:
- scripts/build-provider.py: adds stage_memory() function and
  agentic_memory to required_packages. Both wheels now built and
  staged into the image at /tmp/packages/*.whl for uv pip install.

Verified via `uv run scripts/build-provider.py claude-cli --stage-only`:
both wheels build cleanly, memory/ adapter directory copied to
build context, no errors.

Phase 2 (hindsight adapter) adds providers/workspaces/claude-cli/
memory/hindsight/{init.sh,doctor.sh}. Phase 3 wires this into
agentic-domain-runner.

Author: NeuralEmpowerment

lib/python/agentic_memory/README.md

@@ -0,0 +1,58 @@
+# agentic-memory
+
+Memory primitive contract + doctor for `agentic-workspace-claude-cli`.
+Implements [ADR-036](../../../docs/adrs/036-memory-primitive-and-doctor.md)
+and the matching [design spec](../../../docs/superpowers/specs/2026-05-13-memory-primitive-and-doctor-design.md).
+
+## Contract
+
+Three required env vars from the host:
+
+- `AGENTIC_MEMORY_PROVIDER` — provider name (`hindsight`, `lossless-claw`, `none`, …)
+- `AGENTIC_MEMORY_NAMESPACE` — host-supplied scope identifier
+- `AGENTIC_MEMORY_URL` — base URL of provider backend, reachable from container
+
+Three optional:
+
+- `AGENTIC_MEMORY_NAMESPACE_KIND` — `task` | `domain` | `workflow` | `user` | `session` | `project` | `custom`
+- `AGENTIC_MEMORY_AUTH` — provider-specific token
+- `AGENTIC_MEMORY_CONFIG_JSON` — adapter-specific config (JSON, escape hatch)
+
+Setting `AGENTIC_MEMORY_PROVIDER` is the user's opt-in to memory; opting in is
+opting into hard-fail on misconfiguration. There is no soft-fail mode.
+
+## Doctor
+
+CLI at `/opt/agentic/memory/doctor` (also available as `agentic-memory-doctor`
+on the Python path).
+
+```sh
+agentic-memory-doctor                 # full preflight; pretty output, exit 0 or 1
+agentic-memory-doctor --json          # JSON to stdout, pretty to stderr
+agentic-memory-doctor --fix --apply   # auto-correct client-side issues
+agentic-memory-doctor --verbose       # extra diagnostics
+agentic-memory-doctor --provider hindsight   # override provider for testing
+```
+
+Exit codes:
+
+- `0` — all checks pass
+- `1` — one or more checks failed
+
+## Standard checks
+
+1. `env_contract` — required env vars set
+2. `namespace_well_formed` — namespace matches `[a-zA-Z0-9._:-]+`
+3. `provider_known` — provider exists under `/opt/agentic/memory/`
+4. `adapter_exists` — `<provider>/init.sh` is an executable file
+5. `config_json_valid` — `AGENTIC_MEMORY_CONFIG_JSON` parses (when set)
+6. `backend_dns` — `AGENTIC_MEMORY_URL` hostname resolves
+7. `backend_health` — `GET <url>/health` returns 200
+8. `provider_specific` — delegated to `<provider>/doctor.sh`
+
+## Audit log
+
+When the doctor is invoked from the workspace entrypoint (section 5.7), the
+JSON output is appended to `/var/agentic/memory-doctor/YYYY-MM-DD.jsonl`. The
+orchestrator is expected to bind-mount this directory from the host so logs
+survive container teardown.

lib/python/agentic_memory/agentic_memory/__init__.py

@@ -0,0 +1,10 @@
+"""agentic-memory: memory primitive contract + doctor for agentic-primitives workspaces.
+
+See ADR-036 and 2026-05-13-memory-primitive-and-doctor-design.md.
+
+This module is intentionally lazy — submodules are imported on demand to
+avoid the `RuntimeWarning: found in sys.modules` issue when running
+`python -m agentic_memory.doctor`.
+"""
+
+__version__ = "0.1.0"

lib/python/agentic_memory/agentic_memory/contract.py

@@ -0,0 +1,115 @@
+"""Memory contract — env-var parsing and validation.
+
+The memory contract is six env vars (three required, three optional). This
+module parses them into a `MemoryContract` dataclass and validates the
+namespace shape.
+
+See spec: docs/superpowers/specs/2026-05-13-memory-primitive-and-doctor-design.md
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import re
+from dataclasses import dataclass, field
+from enum import Enum
+
+
+NAMESPACE_PATTERN = re.compile(r"^[a-zA-Z0-9._:-]+$")
+"""Allowed characters in AGENTIC_MEMORY_NAMESPACE — letters, digits, dot,
+underscore, colon, hyphen. No spaces, no slashes, no shell metacharacters."""
+
+
+class NamespaceKind(str, Enum):
+    """Semantic hint about what an AGENTIC_MEMORY_NAMESPACE represents.
+
+    Adapters MAY use this to influence bank-id prefixing, log labels, etc.
+    Adapters MUST NOT change isolation semantics based on this value —
+    namespace isolation is always per `AGENTIC_MEMORY_NAMESPACE` regardless
+    of kind.
+    """
+
+    TASK = "task"
+    DOMAIN = "domain"
+    WORKFLOW = "workflow"
+    USER = "user"
+    SESSION = "session"
+    PROJECT = "project"
+    CUSTOM = "custom"
+
+    @classmethod
+    def parse(cls, value: str | None) -> "NamespaceKind":
+        if not value:
+            return cls.TASK
+        try:
+            return cls(value.lower())
+        except ValueError:
+            return cls.CUSTOM
+
+
+@dataclass(frozen=True)
+class MemoryContract:
+    """Parsed AGENTIC_MEMORY_* env vars.
+
+    Use `MemoryContract.from_env()` to construct. The contract is intentionally
+    immutable — once parsed, it's a value object that can be passed around.
+    Adapters that need to mutate downstream state should produce new env vars
+    in the process's environment, not rewrite this object.
+    """
+
+    provider: str
+    namespace: str
+    url: str | None
+    namespace_kind: NamespaceKind = NamespaceKind.TASK
+    auth: str | None = None
+    config_json: str | None = None
+    config_dict: dict | None = field(default=None, compare=False)
+
+    @classmethod
+    def from_env(cls, env: dict[str, str] | None = None) -> "MemoryContract | None":
+        """Parse contract from env vars. Returns None if AGENTIC_MEMORY_PROVIDER
+        is unset or set to 'none' — i.e. the contract has not been opted into.
+
+        Does NOT validate completeness — that's the doctor's job. This just
+        produces the parsed value; missing required vars surface as empty
+        strings / None and the doctor reports them.
+        """
+        e = env if env is not None else os.environ
+
+        provider = e.get("AGENTIC_MEMORY_PROVIDER", "").strip()
+        if not provider or provider.lower() == "none":
+            return None
+
+        config_json = e.get("AGENTIC_MEMORY_CONFIG_JSON")
+        config_dict: dict | None = None
+        if config_json:
+            try:
+                parsed = json.loads(config_json)
+                if isinstance(parsed, dict):
+                    config_dict = parsed
+            except (json.JSONDecodeError, TypeError):
+                config_dict = None  # doctor's `config_json_valid` check will catch this
+
+        return cls(
+            provider=provider,
+            namespace=e.get("AGENTIC_MEMORY_NAMESPACE", "").strip(),
+            url=e.get("AGENTIC_MEMORY_URL", "").strip() or None,
+            namespace_kind=NamespaceKind.parse(e.get("AGENTIC_MEMORY_NAMESPACE_KIND")),
+            auth=e.get("AGENTIC_MEMORY_AUTH") or None,
+            config_json=config_json,
+            config_dict=config_dict,
+        )
+
+
+def is_namespace_well_formed(namespace: str) -> bool:
+    """True if the namespace string contains only allowed characters and is
+    non-empty. See NAMESPACE_PATTERN."""
+    return bool(namespace) and bool(NAMESPACE_PATTERN.match(namespace))
+
+
+def sanitize_namespace(namespace: str) -> str:
+    """Replace any disallowed characters with hyphens, collapse runs, strip
+    leading/trailing hyphens. Returns 'unnamed' if the result is empty."""
+    cleaned = re.sub(r"[^a-zA-Z0-9._:-]+", "-", namespace).strip("-")
+    return cleaned or "unnamed"