TinyCortex 🧠 — Human-like AI Memory in Rust

Forgets the noise ◦ Local-first & inspectable ◦ Markdown as source of truth ◦ Built in Rust

Discord • Reddit • X • Docs

Benchmarks • Getting Started • Architecture • Read the paper

The human brain is a master at compression. It doesn't try to remember every passing detail; instead it aggressively prunes noise to keep a sharp, focused, easily accessible recall of what truly matters. Traditional AI memory systems do the opposite — they try to remember everything and retrieve whatever is similar. But similar doesn't mean important. The result? Your AI drowns in stale, irrelevant context that degrades every response.

TinyCortex takes the brain's approach: it intelligently forgets noise. A multi-signal admission gate drops low-value content at ingest, and retrieval applies exponential time-decay so stale memories fade from recall while fresh, high-signal knowledge ranks first. The result is a memory engine that stays lean and focused instead of drowning in stale context.

The hosted TinyCortex platform has been evaluated on RAGAS, TemporalBench, BABILong, and Vending-Bench — see Benchmarks below for the reported results and what you can reproduce from this repo.

What this repository is: the open-source Rust core of TinyCortex — the local-first memory engine — published on crates.io as tinycortex. It is a library: you embed it in your own agent, service, or app. The hosted TinyCortex platform is currently in closed alpha — reach out for access.

Every chunk passes a multi-signal admission gate at ingest — low-value content is dropped before it ever pollutes the store — and retrieval ranking applies exponential time-decay (7-day half-life by default) so stale memories fade from recall. The store stays lean on its own — no manual cleanup.

Not all memories are equal. Authored messages, replies, DMs, and mentions all signal what matters, and each carries its own weight in the admission score. Knowledge people engage with rises to the top; ignored information fades away.

Markdown files are the source of truth. SQLite chunk rows, summary trees, vectors, and a git-backed change ledger (opt-in via the git-diff Cargo feature) are derived indexes that accelerate reads and can be rebuilt from canonical content. Every item carries source provenance and a security taint (internal vs. external-sync).

Retrieval blends keyword relevance, vector similarity, graph proximity, and freshness into a single explainable score, so what comes back is a focused slice of long-term history rather than a noisy dump. Summary-tree hotness tracking promotes frequently written topics into their own trees. (The fully proactive "conscious recall" experience — surfacing memories without an explicit query — is part of the hosted TinyCortex platform, built on these primitives.)

TinyCortex is a Rust library. Add it to your project (the example below also uses tokio and anyhow, which are not pulled in by the crate itself):

cargo add tinycortex anyhow
cargo add tokio --features macros,rt-multi-thread

Store and recall a memory with the built-in in-memory backend:

use tinycortex::memory::{InMemoryMemoryStore, MemoryInput, MemoryQuery, MemoryStore};

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    let store = InMemoryMemoryStore::new();

    // Store a memory in the "preferences" namespace.
    store
        .insert(MemoryInput::new("preferences", "User prefers dark mode"))
        .await?;

    // Recall it with a keyword query.
    let hits = store.search(MemoryQuery::text("theme preference")).await?;
    for hit in hits {
        println!("{:.3}  {}", hit.score, hit.record.content);
    }
    Ok(())
}

The InMemoryMemoryStore is the simple reference backend. The full engine — content store, chunking, scoring, summary trees, vector/keyword/graph/hybrid retrieval, the diff ledger, and the async job queue — lives under the memory module. See the documentation for the architecture, concepts, and end-to-end ingest walkthroughs.

TinyCortex is a layered, local-first engine. Content flows through a single ingest pipeline and is served by deterministic retrieval primitives:

source payload
  → canonicalize        normalize chat / email / document into markdown
  → write raw markdown   immutable body files are the source of truth
  → chunk                atomic, deterministically-id'd units
  → score / extract / embed   decide what's worth remembering
  → enqueue tree jobs    append → seal → summarise (async queue)
  → retrieval indexes    vector · keyword · graph · summary tree

Full details live in the documentation.

Scope: the results below were measured for the hosted TinyCortex platform (tinycortex_v1) using an evaluation harness that is not part of this repository, so they are reported rather than locally reproducible. The benchmark that ships with this repo is the retrieval-effectiveness harness (recall@k, precision@k, MRR, nDCG@k over labeled datasets).

Standard RAG quality metrics via RAGAS. TinyCortex leads in Answer Relevancy (0.97) and Context Precision (0.75), outperforming FastGraphRAG, Gemini VDB, Mem0, and SuperMemory.

Accuracy across ordering, state-at-time, recency, interval, and sequence questions. TinyCortex hits 100% on recency — surfacing the most recent events thanks to its time-decay ranking.

An agent runs a simulated vending-machine business over 30 days. TinyCortex achieves the highest cumulative P&L (~$295 by day 30) — better memory leads to better long-horizon decisions.

See benchmarks/ for the full reported tables and for the in-repo retrieval-effectiveness harness you can run yourself (cd benchmarks/effectiveness && cargo run --bin effectiveness).

• Documentation (GitBook) — architecture, concepts, getting started, and FAQ
• docs.rs/tinycortex — generated API reference
• The paper — the research behind the memory model
• CONTRIBUTING.md — how to build, test, and contribute

TinyCortex is built in Rust (2021 edition). Clone the repo and:

cargo test     # run unit + integration tests
cargo doc      # build the API docs
cargo fmt      # format

Issues and PRs are welcome — see CONTRIBUTING.md.

Like contributing towards AGI 🧠? Give this repo a star and spread the love ❤️

Show some love and end up in the hall of fame.