feat(memory): add the memory Cargo gate; carve out six inert surfaces; document what still blocks retiring tinycortex

AGENTS.md

@@ -783,6 +783,7 @@ Two columns because there are two sets (see above): **Contrib** is `[features] d
 | `voice` | OFF | ON | the `openhuman::voice` family (incl. `voice::audio_toolkit`) — STT/TTS providers, dictation server, always-on listening, podcast audio + email | `hound`, `lettre` |
 | `inference` | OFF | ON | the `cpal` audio-device stack: microphone capture for voice, plus `desktop::accessibility::permissions`' mic-permission probe. Implied by `voice`. Off ⇒ the probe reports `Unknown`. **The name is historical** — it used to gate the bundled whisper.cpp STT engine, which no longer exists (see the scope note below); do not rename it, it is forwarded by name from the shell manifest and asserted by `INFERENCE_COMPILED_IN` | `cpal` |
 | `web3` | OFF | ON | the `openhuman::web3` family (`web3`, `web3::wallet`, `web3::x402`) — crypto wallet (multi-chain sign/broadcast), swaps/bridges/dapp calls, x402 machine payments | `bitcoin`, `curve25519-dalek` |
+| `memory` | ON | ON | the `openhuman::memory` family — recall/ingest/tree/goals/sources/sync, its ~13 RPC namespaces, the ~30 memory agent tools, the `MemoryGuard` policy decorator, the driver binding, and **the TinyMemory module the binding loads**. Implied by `memory-git`. Off ⇒ the `memory*` controllers are unregistered, every memory agent tool is absent rather than degraded, the memory subscribers are not installed, and no memory `cdylib` is downloaded or `dlopen`ed. Recall inside a turn returns nothing — the behaviour `NullMemoryProvider` already produces at runtime | **none.** `tinymemory-api` is the contract and stays; every crate the family touches (`rusqlite`, `reqwest`, `serde`) has other parents. Surface-only, like `media` — do not "fix" the empty list |
 | `media` | ON | ON | `openhuman::media::generation` (the `media_generate_*` agent tools) + `openhuman::media::image` scaffold | none (surface-only) |
 | `documents` | OFF | ON | the `generate_document` / `generate_presentation` agent tools and PDF text extraction during multimodal ingest. **The synthesis is not in this build** — all three run in the `tinydocs` TinyBus module (see below), so this gate turns on the tools and the host policy around them: the artifact pipeline, the deadlines, image resolution under the security policy. The dependency is `tinydocs-bus`, the wire contract crate, and nothing else from that repository. Implies `modules`. Off ⇒ both tools absent from the tool list rather than degraded, and PDF ingest degrades a file to a reference instead of extracted text | **39 crates**, and they leave `Cargo.lock` entirely: `docx-rs`, `ppt-rs`, `pdf-extract` plus `lopdf`, `syntect`, `pulldown-cmark`, `xml-rs`, `quick-xml`, `zip 0.6`, `zstd`, `bzip2`, `encoding_rs`, `euclid`, `ttf-parser`, the CFF/Type1/CMap parsers, … Product profile 505 → 448 names |
 | `modules` | ON | ON | `openhuman::modules` — the dynamic module host: the loader that admits a compiled `cdylib` through tinybus's ABI descriptor, manifest, dependency and SHA-256 gates, the compiled-in registry of modules this build trusts, and the `modules` RPC namespace. Implied by `documents`. Off ⇒ `modules.*` is unknown-method and nothing can load a native module | none in the product profile (`ureq`, `flate2`, `tar`, `zip 2`, `tempfile`, `toml` are already there) — **but see the kernel-floor note**: this feature exists so `tinybus/modules` is not enabled on the dependency itself, which would put a `dlopen` loader into the kernel profile where `tinybus` is always-on |
@@ -1051,6 +1052,75 @@ The general shape of the warning still holds for *other* pairs: two crates with
 near-identical types are a real hazard, and a "free carve-out" is only free once
 the compiler says so. Probe before assuming, in either direction.
 
+#### The `memory` gate
+
+Facade + stub in the `voice` shape, with `skills`' type carve-out taken further
+than anywhere else in the tree — **six** carve-outs rather than one. That is the
+interesting part, and the part to copy.
+
+**`pub mod memory;` is always compiled.** The behavioural submodules are
+`#[cfg(feature = "memory")]` and `src/openhuman/memory/stub.rs` covers the
+disabled build. What stays compiled in **both** directions, with exactly one
+definition each and no stub twin:
+
+| Ungated | What | Why it is not behaviour |
+| --- | --- | --- |
+| `memory::api` | the `tinymemory-api` re-export | contract vocabulary in always-on agent-harness signatures |
+| `memory::host` | `MemoryHostConfig for Config` + the bus event sink | impls of API-crate traits on OpenHuman's own `Config`. ~20 always-compiled callers pass `&Config` where `dyn MemoryHostConfig` is expected; gating it makes `Config` stop satisfying a bound unrelated to the family |
+| `memory::ranking` | `hybrid_score`, `WeightProfile`, `cosine_similarity`, `mmr_select` | arithmetic over values the caller already holds. Both search tools fetch through the guard *first*, so routing this back over the bus buys a serialization hop and nothing else |
+| `memory::citation` | `MemoryCitation`, `CROSS_CHAT_HEADER` | inert serde type in the agent's `last_turn_citations` field and the web-chat delivery path |
+| `memory::namespaces` | `CONVERSATION_RAW_NAMESPACE`, `REFLECTIONS_NAMESPACE` | gated producer, always-compiled reader; a `&'static str` cannot fail without a driver |
+| `flows::namespace` | `flow_namespace`, `FLOW_MEMORY_NAMESPACE_PREFIX` | a `format!`; `flows_delete` and the run-digest subscriber need it with memory off |
+
+**The rule these six share, and the reason to prefer it over a stub:** a stub
+twin of an inert type is a *second definition*, free to drift, and the disabled
+build cannot catch drift in a type it also defines. Carve the type out ungated;
+stub only behaviour. `flow_namespace` carries a stated security invariant —
+"the only place in the codebase that may construct this namespace string" —
+and the move **kept** that true precisely because there is one definition, not
+two.
+
+**Stubs answer in two shapes, deliberately.** Registration sites want
+*absence*: the `all_*_registered_controllers` aggregators return empty vectors,
+so `core/all.rs` needs no `#[cfg]` for them, and `memory.*` becomes
+unknown-method rather than a known method that fails. Write paths return a
+build-fact error, because silently discarding a write is the one failure mode
+that looks like success.
+
+**Three mis-housings were retargeted, not stubbed** — the same move the
+`channels` gate made for its three `tinychannels` imports. The Composio
+provider catalogue, the conversation store `threads` uses, and the
+`rpc_models` request types were always-compiled code reaching the engine
+*through* a `memory::…` shim; they name `tinymemory_core` directly now. That
+removed ~37 always-on → gated edges with no stub at all. **Watch the trap:**
+those shims re-export the engine *and* define host code beside it, so a blanket
+path substitution also catches the host half —
+`register_conversation_persistence_subscriber` and
+`slack::all_slack_memory_registered_controllers` both went to the engine crate,
+where they do not exist. List what a shim adds beyond its glob before
+retargeting it.
+
+**CLI arms are kept, not deleted.** `openhuman memory` and `tree-summarizer`
+answer with the gate name; falling through to generic namespace resolution
+would say "unknown namespace: memory", which reads like a typo rather than a
+build fact. Same reasoning as the `mcp` and `tui` arms.
+
+**`CoreContext::current_memory_capabilities` answers CLOSED with the gate off**
+— the one place it does. The open default exists because a capability set is
+unknowable until a driver answers; with the family compiled out the state is
+not "unknown", it is "absent".
+
+**Sheds no third-party crate.** `tinymemory-api` is the contract and stays, and
+every crate the family touches (`rusqlite`, `reqwest`, `serde`) has other
+parents. Surface-only, like `media` — the `memory = []` list is intentional, do
+not "fix" it with `dep:` entries. Implied by `memory-git`.
+
+**Errors surface in waves.** Name resolution first, then trait bounds — the
+`MemoryHostConfig` wave only appeared once resolution was clean, so a run that
+looks nearly done can still be hiding a structural problem. Run
+`cargo check --no-default-features --features "media,skills,flows,mcp,channels,medulla,http-server,scheduler-gate,file-logging,modules"`
+(that is `default` minus `memory`) before pushing anything touching this surface.
+
 #### The `tui` gate
 
 The tabbed terminal UI (`openhuman`, or explicitly `openhuman tui` / alias `chat`) lives in `src/openhuman/tui/` and follows the **`mcp`/`voice` facade+stub** pattern: `pub mod tui;` is always compiled; the behavioural submodules (`app`, `render`, `state`, `terminal`, `runner`) are `#[cfg(feature = "tui")]`; and `#[cfg(not(feature = "tui"))] mod stub;` re-exposes the one symbol an always-compiled caller reaches — `run_from_cli` — with a build-fact error body (`"tui feature disabled at compile time … --features tui"`). Bare-command auto-launch requires terminal stdin/stdout and `HostKind::Cli`; Docker, CI, pipes, and `--no-tui` retain the non-TUI CLI path.

Cargo.toml

@@ -757,7 +757,7 @@ proptest = "1"
 # (`modules`: Contrib=ON, Product=ON) and with `scripts/ci/product-features.txt`,
 # which already lists it. This does NOT move the kernel floor: that profile is
 # `--no-default-features --features flows` and never reads this list.
-default = ["media", "skills", "flows", "mcp", "channels", "medulla", "http-server", "scheduler-gate", "file-logging", "modules"]
+default = ["media", "memory", "skills", "flows", "mcp", "channels", "medulla", "http-server", "scheduler-gate", "file-logging", "modules"]
 # HTTP + Socket.IO server transport (#5048): the `/rpc` JSON-RPC endpoint and
 # its auth middleware/CORS layer (`core::jsonrpc`, `core::auth`), the `/v1`
 # OpenAI-compatible router (`inference::http`), the ad-hoc static-dir file
@@ -804,7 +804,7 @@ default = ["media", "skills", "flows", "mcp", "channels", "medulla", "http-serve
 # `None`; and the three `ops` entry points always-on code calls return a
 # build-fact error, so a post-sync snapshot or a subconscious diff is logged and
 # skipped rather than silently reported as "nothing changed".
-memory-git = ["tinycortex/git-diff", "tinycortex/wiki-git", "tinymemory-core/memory-git"]
+memory-git = ["memory", "tinycortex/git-diff", "tinycortex/wiki-git", "tinymemory-core/memory-git"]
 http-server = ["dep:axum", "dep:socketioxide"]
 # Local audio-device access: the `cpal` capture stack behind voice recording
 # and the accessibility microphone-permission probe. Default-ON. Slim /
@@ -1005,6 +1005,45 @@ contacts = ["tinymemory-core/contacts"]
 # controllers / stores / subscribers tagged `Media` (agent tools only), and
 # `openhuman::image` is currently unwired scaffold (added #2997).
 media = []
+
+# The `openhuman::memory` family: the recall/ingest/tree/goals/sources/sync
+# domains, their ~13 RPC namespaces, the ~30 memory agent tools, the guard, the
+# driver binding, and the TinyMemory module the binding loads. Default-ON,
+# product-ON — this is a core product surface, and the gate exists for the
+# embedding host that wants a workflow or tool runtime with no memory at all
+# (`DomainSet::kernel()` already models that at runtime; this is the
+# compile-time axis it composes with).
+#
+# FACADE + STUB, not a leaf gate. `pub mod memory;` is always compiled: ~230
+# production references across ~101 files outside the family reach into it, and
+# a handful of always-on callers (the agent harness, flows, channels, cron)
+# name concrete items rather than a registration aggregator. The behavioural
+# submodules are `#[cfg(feature = "memory")]` and
+# `src/openhuman/memory/stub.rs` re-exposes that surface with null / disabled
+# bodies. Same shape as `voice`, with `skills`' refinement: inert types stay
+# ungated so both builds share ONE definition.
+#
+# TYPE CARVE-OUT: `memory::api` (a re-export of `tinymemory-api`) and
+# `memory::ranking` are compiled in BOTH builds. The first is the contract
+# vocabulary — `MemoryEntry`, `RecallOpts`, `MemoryCategory` appear in
+# always-on agent-harness signatures — and the second is host-side arithmetic
+# with no driver behind it. Neither needs a stub twin, and a twin is exactly
+# what would be free to drift.
+#
+# What OFF means: the `memory*` controllers are unregistered (unknown-method
+# over `/rpc`, absent from `/schema`), every memory agent tool is ABSENT from
+# the tool list rather than degraded to an error, the memory subscribers are
+# not installed, and — the point of the gate for an embedder — the TinyMemory
+# module is neither pinned nor loaded, so no `cdylib` is downloaded or
+# `dlopen`ed. Recall inside an agent turn returns nothing, which is the
+# behaviour `NullMemoryProvider` already produces at runtime.
+#
+# Sheds no third-party crate on its own: `tinymemory-api` is the contract and
+# stays, and every crate the family touches (rusqlite, reqwest, serde) has
+# other parents. The gate buys the tool surface, the prompt bloat, the RPC
+# surface and the module download — not binary size. Do not "fix" the empty
+# list by adding `dep:` entries.
+memory = []
 # Flows domains: the `flows::` automation surface (saved tinyflows graphs —
 # create/run/schedule + the workflow_builder / flow_discovery agents), the
 # `tinyflows::` adapter seam, and the `rhai_workflows::` language-workflow tool.

app/src-tauri/Cargo.toml

@@ -163,6 +163,10 @@ uuid = { version = "1", features = ["v4"] }
 openhuman_core = { path = "../..", package = "openhuman", default-features = false, features = [
     "channels",
     "media",
+    # The memory family and the TinyMemory module it loads. Forwarded because
+    # the shell sets `default-features = false`, so a gate absent from this
+    # list is compiled out of the shipped app silently (#4901).
+    "memory",
     "inference",
     "voice",
     "web3",