TinyCortex Features in OpenHuman: Complete AI Memory Architecture Guide

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, 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 abstract the vectorization process, supporting multiple backends including OpenAI, Azure OpenAI, and locally hosted models.

Configuration occurs through 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, 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 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:

// 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:

// 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:

// 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:

# 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.

Source Code Reference

The following files define the complete TinyCortex implementation:

• src/openhuman/memory/chunk.rs – Chunk definition and SQLite persistence
• src/openhuman/memory/embedding.rs – Embedding engine abstraction and provider implementations
• src/openhuman/memory/cortex.rs – Core Cortex API for indexing and similarity search
• src/openhuman/memory/ops.rs – High-level operations for agent tools
• src/openhuman/config/schema/memory.rs – Configuration schema for embedding backends
• 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, embedding.rs, and 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. 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, 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, 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}