Forgets the noise ◦ Local-first & inspectable ◦ Markdown as source of truth ◦ Built in Rust
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. Retrieval provides semantic, keyword, graph, summary-tree, and freshness-scoring building blocks so hosts can choose an explicit ranking policy instead of treating every stored item as equally useful.
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, so low-value content is dropped before it pollutes the store. The retrieval module exposes exponential freshness decay (7-day half-life by default) as a composable signal; built-in tree queries use semantic similarity or recency unless the host applies the hybrid composer.
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).
TinyCortex exposes keyword relevance, vector similarity, graph proximity, freshness, and an explainable hybrid-score composer. These are policy primitives rather than a hidden global ranking rule: hosts can apply the supplied WeightProfile, while the built-in source/topic/global queries use their documented semantic or recency ordering. 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-threadStore 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("dark mode")).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, and vector/keyword/graph retrieval primitives — lives under the memory module. Optional surfaces require Cargo features:
| Feature | Enables |
|---|---|
tokio |
Always-on queue worker and scheduler loops |
git-diff |
Git-backed snapshots, checkpoints, and read markers |
sync |
Composio and workspace synchronization pipelines |
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
| Layer | What it does |
|---|---|
| Storage primitives | Markdown content store, SQLite chunks, summary trees, vector DB, KV, entity index |
| Ingest | Canonicalize → chunk → score → embed → tree |
| Retrieval | Vector, keyword, graph, tree drill-down, and composable hybrid-score primitives |
Diff (git-diff) |
Git-backed source snapshots, checkpoints, and read-markers for change awareness |
| Entities & Graph | Entity markdown files + a co-occurrence graph derived from the entity index |
| Goals / Tool Memory | Compact long-term goal list and durable tool-scoped rules |
| Conversations / Archivist | Transcript storage and conversion of turns into summary-tree leaves |
| Queue | Durable jobs; optional tokio feature adds always-on worker/scheduler loops |
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, then run
./scripts/setup.sh once and ./scripts/test.sh for the full local CI suite.
The underlying commands are:
cargo test # run unit + integration tests
cargo doc # build the API docs
cargo fmt # formatIssues 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.