refactor(memory): finish TinyCortex tool-memory cutover (#5237)

docs/tinycortex-cutover-evaluation-2026-07-28.md

@@ -0,0 +1,68 @@
+# TinyCortex Memory Cutover Evaluation (2026-07-28)
+
+## Decision
+
+The memory engine cutover is complete. TinyCortex is the implementation
+authority for chunks, content and vector primitives, trees, retrieval, scoring,
+queue jobs, ingest, source readers, sync pipelines, diffs, goals, graph
+primitives, conversations, and tool memory.
+
+The remaining `src/openhuman/memory*` modules must not be moved wholesale. They
+are product adapters or compatibility paths, not a second memory engine:
+
+- RPC schemas and controller registration
+- agent tools and `SecurityPolicy` enforcement
+- source-scope and redaction policy
+- credentials, scheduling, and event-bus bridges
+- the host-owned namespace/document store
+- wiki-git and Obsidian product surfaces
+- process lifecycle and the global memory singleton
+
+Moving those concerns into TinyCortex would reverse the established dependency
+boundary by teaching the reusable engine about OpenHuman RPC, policy, secrets,
+and runtime composition.
+
+## Audit result
+
+The audit covered `src/openhuman/memory/`, every `memory_*` domain, the
+`src/openhuman/tinycortex/` seam, and `vendor/tinycortex/src/memory/`.
+
+| Host area | Disposition |
+| --- | --- |
+| `memory_store::{chunks,content,vectors,kv,entities,trees,safety}` | TinyCortex-backed compatibility and host glue |
+| `memory_tree::{tree,retrieval,score}` | TinyCortex-backed compatibility plus RPC, CLI, health, and bus glue |
+| `memory_queue` | TinyCortex queue, driven by the host worker lifecycle |
+| `memory_sync` | TinyCortex sync engine plus host credentials, schedules, projections, RPC, and events |
+| `memory_diff`, `memory_goals`, `memory_conversations` | TinyCortex engine types/operations plus host tools, RPC, or bus glue |
+| `memory_sources` | Host source registry and RPC over TinyCortex readers |
+| `memory_tools` | TinyCortex tool-memory store/types plus host prompt hooks and agent tools |
+| `memory_store::namespace_store` | Host-owned; intentionally outside TinyCortex |
+| `memory`, `tinycortex` | Product orchestration and the engine adapter seam; retained |
+
+No second store, retrieval engine, queue engine, or sync-provider engine remains
+on the live host path. The large host line counts are dominated by retained
+product surfaces and their tests; line count alone is not evidence of engine
+duplication.
+
+## Cleanup executed
+
+The unused `memory_tools::types` facade file was removed. `memory_tools` now
+re-exports the crate-owned types and store directly at its existing domain-level
+API. Its private `store` module retains only the host constructor so `mod.rs`
+remains export-focused; prompt integration, the capture hook, and agent tools
+also stay host-owned.
+
+Other small re-export modules remain where they preserve heavily used import
+paths such as `memory_queue::types`, `memory_sources::types`,
+`memory_tree::retrieval::types`, and `memory_store::trees::types`. Removing
+those files would create broad source churn without changing runtime ownership.
+
+## Guardrails
+
+- New generic memory behavior belongs in `vendor/tinycortex`.
+- OpenHuman may add adapters, policy, RPC, tools, lifecycle, and product
+  projections, but must not fork TinyCortex engine logic.
+- Persisted format parity tests in `openhuman::tinycortex::parity` remain the
+  cutover guard for existing workspaces.
+- `MemoryTaint`, redaction, and source-scope behavior remain security-sensitive
+  review points.

src/openhuman/memory_tools/mod.rs

@@ -14,14 +14,14 @@
 //! distinct from `global`, `skill-{id}`, `tool_effectiveness`, and the
 //! learning namespaces so list/clear operations can reason about it
 //! without ambiguity. Build the namespace string via
-//! [`types::tool_memory_namespace`] — never hard-code the format.
+//! [`tool_memory_namespace`] — never hard-code the format.
 //!
 //! ## Components
 //!
-//! - [`types`]   — [`ToolMemoryRule`], [`ToolMemoryPriority`],
-//!   [`ToolMemorySource`].
-//! - [`store`]   — [`ToolMemoryStore`], the put/list/delete/prompt API
-//!   built on top of an `Arc<dyn Memory>`.
+//! - [`tinycortex::memory::tool_memory::types`] owns [`ToolMemoryRule`],
+//!   [`ToolMemoryPriority`], and [`ToolMemorySource`].
+//! - [`tinycortex::memory::tool_memory::store`] owns [`ToolMemoryStore`], the
+//!   put/list/delete/prompt API built on top of an `Arc<dyn Memory>`.
 //! - [`capture`] — [`ToolMemoryCaptureHook`], the post-turn
 //!   [`PostTurnHook`] that records user edicts and repeated tool
 //!   failures.
@@ -35,13 +35,15 @@
 
 pub mod capture;
 pub mod prompt;
-pub mod store;
+mod store;
 #[cfg(test)]
 pub mod test_helpers;
 pub mod tools;
-pub mod types;
 
 pub use capture::ToolMemoryCaptureHook;
 pub use prompt::{render_tool_memory_rules, ToolMemoryRulesSection, TOOL_MEMORY_HEADING};
-pub use store::{tool_memory_store, ToolMemoryStore, TOOL_MEMORY_PROMPT_CAP};
-pub use types::{tool_memory_namespace, ToolMemoryPriority, ToolMemoryRule, ToolMemorySource};
+pub use store::tool_memory_store;
+pub use tinycortex::memory::tool_memory::{
+    store::{ToolMemoryStore, TOOL_MEMORY_PROMPT_CAP},
+    types::{tool_memory_namespace, ToolMemoryPriority, ToolMemoryRule, ToolMemorySource},
+};

src/openhuman/memory_tools/store.rs

@@ -2,7 +2,7 @@ use std::sync::Arc;
 
 use crate::openhuman::memory::Memory;
 
-pub use tinycortex::memory::tool_memory::store::{ToolMemoryStore, TOOL_MEMORY_PROMPT_CAP};
+use tinycortex::memory::tool_memory::store::ToolMemoryStore;
 
 /// Build the crate-owned store over OpenHuman's shared memory object.
 pub fn tool_memory_store(memory: Arc<dyn Memory>) -> ToolMemoryStore {

src/openhuman/memory_tools/types.rs

@@ -1,9 +0,0 @@
-//! Domain types for the tool-scoped memory layer — thin host re-export of
-//! `tinycortex::memory::tool_memory::types`.
-//!
-//! This module preserves the public `memory_tools::types::*` import path while
-//! TinyCortex remains the single implementation and wire-format authority.
-
-pub use tinycortex::memory::tool_memory::types::{
-    tool_memory_namespace, ToolMemoryPriority, ToolMemoryRule, ToolMemorySource,
-};