# TinyCortex Memory Engine: The Core Architecture Behind OpenHuman's Memory Tree and Obsidian Wiki

> Discover the TinyCortex memory engine, the core architecture behind OpenHuman's Memory Tree. It provides a persistent, version-controlled graph for Obsidian wiki sync, semantic search, and more.

- Repository: [Tiny Humans/openhuman](https://github.com/tinyhumansai/openhuman)
- Tags: architecture
- Published: 2026-08-27

---

**The TinyCortex memory engine serves as the authoritative source of truth for OpenHuman's Memory Tree, providing a persistent, version-controlled hierarchical graph that powers bidirectional synchronization with Obsidian wiki through incremental diffs and fast semantic search.**

OpenHuman stores user knowledge as a **Memory Tree**—a traversable graph of notes, concepts, and relationships that the AI uses for reasoning and content generation. The **TinyCortex** engine, implemented in the `tinyhumansai/openhuman` repository, operates as the low-level storage and retrieval layer beneath this structure, ensuring durability and consistency across the Rust core and frontend interfaces.

## How TinyCortex Powers the Memory Tree

The Memory Tree relies on TinyCortex for all fundamental operations. Unlike a simple document store, TinyCortex implements a **git-backed ledger** that versions every change to the hierarchical graph, enabling features like Memory Diff and seamless Obsidian integration.

### Persistent Hierarchical Data Model

At its core, TinyCortex manages a tree structure of nodes, edges, and timestamps. All memory-related domains—including `memory::tree`, `memory::source_scope`, and `memory::recall`—delegate their storage operations to this engine. According to the OpenHuman source code, the engine implementation resides in `vendor/tinymemory/crates/tinymemory-core/src/engine/*`, where it handles the concrete data structures that persist user knowledge between sessions.

### Bidirectional Obsidian Synchronization

TinyCortex exposes an API capable of reading and writing the tree while simultaneously emitting change events. The **Obsidian Wiki** integration subscribes to these events through [`src/openhuman/hosted/orchestration/obsidian_sync.rs`](https://github.com/tinyhumansai/openhuman/blob/main/src/openhuman/hosted/orchestration/obsidian_sync.rs), mirroring every node as a Markdown file complete with backlinks and front-matter. When users edit files directly in Obsidian, the sync layer converts these changes into fine-grained diffs and transmits them back to TinyCortex, which updates the in-process memory model instantly without requiring full re-serialization.

### Incremental Update Handling

Rather than rewriting entire graphs, TinyCortex supports atomic operations for add, move, and delete actions. This incremental approach is critical for performance when the Memory Tree grows large, as only changed subgraphs require processing. The `memory::diff` functionality leverages this capability to provide users with granular change tracking and rollback capabilities.

### Fast Search and Recall

The engine implements optimized lookup mechanisms across the tree, supporting queries by title, tags, and semantic embeddings. Core recall tools such as `memory::recall` and `memory::search` query TinyCortex directly through the API defined in [`src/openhuman/memory/api.rs`](https://github.com/tinyhumansai/openhuman/blob/main/src/openhuman/memory/api.rs), returning the most relevant nodes for LLM context windows. This ensures that retrieval latency remains constant regardless of tree depth or total node count.

### Durability Through Version Control

Every mutation to the Memory Tree is recorded in a **git-backed ledger**, providing complete audit trails and revert capabilities. This durability layer supports the Memory Diff feature and underpins the Obsidian export-import pipeline, ensuring that user knowledge remains protected against corruption or accidental deletion.

## Key Implementation Files

Understanding TinyCortex requires examining its integration points throughout the OpenHuman codebase:

- **[`src/openhuman/memory/api.rs`](https://github.com/tinyhumansai/openhuman/blob/main/src/openhuman/memory/api.rs)** — Re-exports the public TinyCortex contract (`tinymemory_api`) that higher-level modules consume.
- **[`src/openhuman/memory/tree/ops.rs`](https://github.com/tinyhumansai/openhuman/blob/main/src/openhuman/memory/tree/ops.rs)** — Contains RPC handlers that forward add, modify, and delete requests to the underlying TinyCortex engine.
- **[`src/openhuman/memory/tree/schemas.rs`](https://github.com/tinyhumansai/openhuman/blob/main/src/openhuman/memory/tree/schemas.rs)** — Defines the RPC endpoints and data structures used for tree operations.
- **[`src/openhuman/hosted/orchestration/obsidian_sync.rs`](https://github.com/tinyhumansai/openhuman/blob/main/src/openhuman/hosted/orchestration/obsidian_sync.rs)** — Implements the event listener that writes TinyCortex changes to Markdown files and processes incoming diffs from Obsidian.
- **`vendor/tinymemory/crates/tinymemory-core/src/engine/*`** — Houses the core engine implementation, including the tree data model, diff handling, and persistence logic.

## Working with the TinyCortex API

Developers interact with TinyCortex through the core RPC client, whether adding nodes from Rust backends or querying from TypeScript frontends.

### Adding Nodes to the Memory Tree

To create a new node in the hierarchy, use the `NodeBuilder` API followed by the `add_node` operation:

```rust
use openhuman::memory::tree::ops::*;
use openhuman::memory::api::NodeBuilder;

// Build a new node (title + optional content)
let node = NodeBuilder::new()
    .title("Project X Design")
    .content("Initial wireframes and design decisions.")
    .parent_id(None)      // top-level node
    .build()?;

// Submit the node to TinyCortex via the core RPC client
let result = add_node(node).await?;
println!("Created node id {}", result.id);

```

*Source*: [`src/openhuman/memory/tree/ops.rs`](https://github.com/tinyhumansai/openhuman/blob/main/src/openhuman/memory/tree/ops.rs)

### Querying from the Frontend

TypeScript clients can search the Memory Tree using the core RPC interface:

```typescript
import { coreRpcClient } from "./services/coreRpcClient";

// Search for notes containing "user onboarding"
const hits = await coreRpcClient.call(
  "memory_tree_search",
  { query: "user onboarding", limit: 5 }
);

hits.forEach(hit => console.log(`${hit.title} → ${hit.id}`));

```

*Source*: [`app/src/services/memoryService.ts`](https://github.com/tinyhumansai/openhuman/blob/main/app/src/services/memoryService.ts)

### Processing Obsidian Changes

The bidirectional sync converts file system events into TinyCortex diffs:

```rust
// In the Obsidian sync module
fn on_file_changed(path: &Path, content: &str) -> Result<()> {
    // Convert the file into a TinyCortex node diff
    let diff = tinycortex::diff::FileDiff::from_markdown(path, content);
    // Send the diff to the core
    core_rpc::send("memory_tree_apply_diff", diff)?;
    Ok(())
}

```

*Source*: [`src/openhuman/hosted/orchestration/obsidian_sync.rs`](https://github.com/tinyhumansai/openhuman/blob/main/src/openhuman/hosted/orchestration/obsidian_sync.rs)

## Summary

- **TinyCortex** functions as the authoritative storage engine for OpenHuman's Memory Tree, handling all persistent operations through a git-backed ledger.
- The engine supports **bidirectional synchronization** with Obsidian wiki, converting between graph nodes and Markdown files while preserving relationships.
- **Incremental diffs** enable real-time updates without re-serializing entire trees, optimizing performance for large knowledge bases.
- All memory operations route through [`src/openhuman/memory/api.rs`](https://github.com/tinyhumansai/openhuman/blob/main/src/openhuman/memory/api.rs), which exposes the `tinymemory_api` contract to higher-level Rust and TypeScript consumers.
- Durability is guaranteed through version-controlled storage that powers features like Memory Diff and complete history replay.

## Frequently Asked Questions

### How does TinyCortex differ from a standard database?

Unlike relational or document databases, TinyCortex is purpose-built for hierarchical knowledge graphs with built-in versioning. While traditional databases require external systems to track changes, TinyCortex integrates a **git-backed ledger** directly into the storage layer, providing native support for diffs, branching, and revert operations essential for AI memory management.

### What happens when Obsidian files conflict with the Memory Tree?

The sync implementation in [`obsidian_sync.rs`](https://github.com/tinyhumansai/openhuman/blob/main/obsidian_sync.rs) detects conflicts through timestamp comparison and event ordering. When discrepancies occur between the Obsidian vault and the in-memory tree, TinyCortex applies **last-write-wins semantics** with optional conflict markers, allowing users to resolve differences through the standard git workflow since all changes are versioned.

### How does the git-backed ledger work in TinyCortex?

Every mutation to the Memory Tree generates a commit in an embedded git repository managed by the engine. This occurs at the persistence layer in `vendor/tinymemory/crates/tinymemory-core/src/engine/*`, where tree operations are serialized as diffs and appended to the ledger. Users can inspect history through the `memory::diff` tools or by examining the underlying repository directly.

### Can I use TinyCortex independently of OpenHuman?

While TinyCortex is currently embedded within the OpenHuman monorepo under `vendor/tinymemory/`, it is architected as a standalone crate with its own API surface. The `tinymemory_api` contract exposed in [`src/openhuman/memory/api.rs`](https://github.com/tinyhumansai/openhuman/blob/main/src/openhuman/memory/api.rs) could theoretically power other Rust applications requiring versioned hierarchical storage, though current documentation focuses exclusively on the OpenHuman integration.