diff --git a/docs/tinycortex-cutover-evaluation-2026-07-28.md b/docs/tinycortex-cutover-evaluation-2026-07-28.md new file mode 100644 index 000000000..016a97abd --- /dev/null +++ b/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. diff --git a/src/openhuman/memory_tools/mod.rs b/src/openhuman/memory_tools/mod.rs index 11ff3b528..ad68a3c32 100644 --- a/src/openhuman/memory_tools/mod.rs +++ b/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`. +//! - [`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`. //! - [`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}, +}; diff --git a/src/openhuman/memory_tools/store.rs b/src/openhuman/memory_tools/store.rs index 765bbf276..d52564996 100644 --- a/src/openhuman/memory_tools/store.rs +++ b/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) -> ToolMemoryStore { diff --git a/src/openhuman/memory_tools/types.rs b/src/openhuman/memory_tools/types.rs deleted file mode 100644 index 84e6280c2..000000000 --- a/src/openhuman/memory_tools/types.rs +++ /dev/null @@ -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, -};