# TinyCortex Features in OpenHuman: Complete AI Memory Architecture Guide

> Explore TinyCortex features in OpenHuman for AI memory. Discover long-term memory, semantic search, and knowledge-graph capabilities driven by text chunking, vector embeddings, and hybrid retrieval.

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

---

**TinyCortex is the embedded cognitive core that powers OpenHuman’s long-term memory, semantic search, and knowledge-graph capabilities through automatic text chunking, vector embeddings, and hybrid retrieval.**

TinyCortex serves as the persistent memory layer for the tinyhumansai/openhuman platform, enabling AI agents to retain and recall information across conversations. Written in Rust and located under `src/openhuman/memory/`, this subsystem combines SQLite-backed storage with vector similarity search to deliver sub-second retrieval of relevant context.

## Core Architecture Layers

TinyCortex is built around three tightly integrated architectural layers that handle the complete lifecycle of memory from ingestion to retrieval.

### Chunking and Persistence Layer

The first layer handles text segmentation and storage. Located in [`src/openhuman/memory/chunk.rs`](https://github.com/tinyhumansai/openhuman/blob/main/src/openhuman/memory/chunk.rs), this component splits incoming documents into searchable units using the `Chunk` and `ChunkStore` types.

The `ChunkProvider` trait defines how text is divided and persisted to SQLite. Each chunk maintains metadata about its source, creation time, and schema version, enabling the **Versioned Index** feature that supports safe migrations of the underlying storage format.

### Embedding Generation Layer

Before storage, each chunk is converted into a dense vector representation. The `EmbeddingEngine` and `EmbeddingProvider` traits in [`src/openhuman/memory/embedding.rs`](https://github.com/tinyhumansai/openhuman/blob/main/src/openhuman/memory/embedding.rs) abstract the vectorization process, supporting multiple backends including OpenAI, Azure OpenAI, and locally hosted models.

Configuration occurs through [`src/openhuman/config/schema/memory.rs`](https://github.com/tinyhumansai/openhuman/blob/main/src/openhuman/config/schema/memory.rs), where developers specify the provider without modifying Cortex code. This **Configurable Embedding Back-end** design allows swapping from cloud to local inference by updating the TOML configuration file.

### Semantic Retrieval Layer

The top layer executes nearest-neighbor queries over stored vectors. Implemented in [`src/openhuman/memory/cortex.rs`](https://github.com/tinyhumansai/openhuman/blob/main/src/openhuman/memory/cortex.rs), the `Cortex` struct provides the primary API for similarity search through methods like `Cortex::search()`.

The `RecallOpts` struct enables **Scoped Recall**, allowing callers to filter results by workspace, thread ID, date ranges, or user-defined tags before executing the vector similarity calculation.

## Key TinyCortex Features

The architecture exposes six high-level capabilities that power OpenHuman's memory system:

1. **Automatic Ingestion** – When documents, conversations, or web pages enter the system, TinyCortex automatically creates chunks, generates embeddings, and updates the index without manual intervention.

2. **Hybrid Search** – Queries combine traditional lexical matching (`LIKE` clauses in SQLite) with approximate nearest neighbor (ANN) vector similarity to maximize retrieval accuracy.

3. **Scoped Recall** – The `RecallOpts` parameter allows restricting searches to specific contexts, such as particular conversation threads or time windows, preventing information leakage between workspaces.

4. **Memory-aware Tooling** – Agent tools including `memory_search`, `memory_fetch`, and `memory_summarize` defined in [`src/openhuman/tools/ops.rs`](https://github.com/tinyhumansai/openhuman/blob/main/src/openhuman/tools/ops.rs) consume the Cortex API, enabling LLMs to reference past interactions through the JSON-RPC namespace `openhuman.memory_*`.

5. **Configurable Embedding Back-ends** – The embedding engine is selected from global configuration settings, supporting hot-swapping between OpenAI's `text-embedding-ada-002`, Azure deployments, or local models without code changes.

6. **Versioned Index** – Each chunk records the schema version at creation time, ensuring that storage format migrations preserve existing data integrity.

## Working with TinyCortex

Developers interact with TinyCortex through both the Rust core API and JSON-RPC endpoints consumed by the React/Tauri frontend.

### Ingesting Text into Memory

To add content to the Cortex index, use the `ChunkProvider` trait methods:

```rust
// 1️⃣ Add a piece of text to Cortex (e.g. from a new document)
use openhuman::memory::{ChunkProvider, RecallOpts};

let text = "The Open Human platform integrates AI agents with user data.";
let chunk_id = ChunkProvider::ingest(text).await?;   // creates chunk, embeds, stores

```

This operation automatically handles chunking, embedding generation via the configured `EmbeddingEngine`, and persistence to the `ChunkStore`.

### Performing Semantic Search

Retrieve relevant context using the `Cortex::search()` method with `RecallOpts`:

```rust
// 2️⃣ Perform a semantic search
let opts = RecallOpts {
    query: "How does Open Human store data?".into(),
    limit: 5,
    ..Default::default()
};
let results = Cortex::search(opts).await?;          // returns top‑N matching chunks

for r in results {
    println!("⚡ {} – {}", r.score, r.chunk.text);
}

```

The search executes vector similarity calculations while respecting any scope restrictions defined in the options.

### Frontend Integration

The React frontend communicates with TinyCortex through RPC calls:

```tsx
// 3️⃣ Front‑end: invoke the memory search RPC from React
import { coreRpcClient } from '@/services/coreRpcClient';

async function semanticSearch(query: string) {
  const resp = await coreRpcClient.call('memory_search', {
    query,
    limit: 10,
  });
  return resp.results; // [{ score, chunk: { id, text, source } }, …]
}

```

This architecture ensures heavy computational work (vector math and SQLite I/O) remains in the Rust core process while the UI sends high-level commands.

### Configuration

Define embedding providers in the TOML configuration:

```toml

# 4️⃣ Configure the embedding model (shown in the TOML config)

[embedding]
provider = "openai"          # alternatives: "azure", "local"

model    = "text-embedding-ada-002"

```

Valid providers include `"openai"`, `"azure"`, and `"local"`, with the selection propagating to the `EmbeddingProvider` implementation in [`src/openhuman/memory/embedding.rs`](https://github.com/tinyhumansai/openhuman/blob/main/src/openhuman/memory/embedding.rs).

## Source Code Reference

The following files define the complete TinyCortex implementation:

- [`src/openhuman/memory/chunk.rs`](https://github.com/tinyhumansai/openhuman/blob/main/src/openhuman/memory/chunk.rs) – Chunk definition and SQLite persistence
- [`src/openhuman/memory/embedding.rs`](https://github.com/tinyhumansai/openhuman/blob/main/src/openhuman/memory/embedding.rs) – Embedding engine abstraction and provider implementations
- [`src/openhuman/memory/cortex.rs`](https://github.com/tinyhumansai/openhuman/blob/main/src/openhuman/memory/cortex.rs) – Core Cortex API for indexing and similarity search
- [`src/openhuman/memory/ops.rs`](https://github.com/tinyhumansai/openhuman/blob/main/src/openhuman/memory/ops.rs) – High-level operations for agent tools
- [`src/openhuman/config/schema/memory.rs`](https://github.com/tinyhumansai/openhuman/blob/main/src/openhuman/config/schema/memory.rs) – Configuration schema for embedding backends
- [`src/openhuman/tools/ops.rs`](https://github.com/tinyhumansai/openhuman/blob/main/src/openhuman/tools/ops.rs) – Registration of memory-related agent tools

## Summary

TinyCortex provides OpenHuman with production-grade vector memory capabilities:

- **Three-layer architecture** separates chunking, embedding, and retrieval concerns across [`chunk.rs`](https://github.com/tinyhumansai/openhuman/blob/main/chunk.rs), [`embedding.rs`](https://github.com/tinyhumansai/openhuman/blob/main/embedding.rs), and [`cortex.rs`](https://github.com/tinyhumansai/openhuman/blob/main/cortex.rs)
- **Hybrid search** combines lexical and vector similarity for optimal recall
- **Flexible deployment** supports cloud and local embedding models through configuration
- **Agent integration** exposes memory functions via JSON-RPC and Rust APIs
- **Versioned storage** ensures data integrity across schema migrations

## Frequently Asked Questions

### What is TinyCortex in OpenHuman?

TinyCortex is the embedded cognitive core that powers long-term memory and semantic search in the OpenHuman platform. According to the tinyhumansai/openhuman source code, it is implemented as a Rust module under `src/openhuman/memory/` and provides vector-based retrieval capabilities that allow AI agents to remember and reference past interactions.

### How does TinyCortex store vector embeddings?

TinyCortex stores embeddings in a SQLite-backed `ChunkStore` defined in [`src/openhuman/memory/chunk.rs`](https://github.com/tinyhumansai/openhuman/blob/main/src/openhuman/memory/chunk.rs). The system uses the `EmbeddingEngine` trait to generate vectors, which are then indexed alongside text chunks for efficient nearest-neighbor queries. The architecture supports approximate nearest neighbor (ANN) search combined with traditional SQL filtering.

### Can TinyCortex use local embedding models instead of OpenAI?

Yes, TinyCortex supports configurable embedding backends through the `EmbeddingProvider` trait. By modifying the `[embedding]` section in the configuration file located at [`src/openhuman/config/schema/memory.rs`](https://github.com/tinyhumansai/openhuman/blob/main/src/openhuman/config/schema/memory.rs), users can switch between OpenAI, Azure, or local model providers without changing any Cortex retrieval code.

### How do AI agents access memory through TinyCortex?

AI agents access TinyCortex through specialized tools defined in [`src/openhuman/tools/ops.rs`](https://github.com/tinyhumansai/openhuman/blob/main/src/openhuman/tools/ops.rs), including `memory_search`, `memory_fetch`, and `memory_summarize`. These tools call the JSON-RPC namespace `openhuman.memory_*`, which routes requests to the `Cortex::search()` method and returns relevant chunks to the LLM context window.