|
1 | 1 | --- |
2 | | -description: The memory layer for AI agents. Scales to 1B+ tokens. |
| 2 | +description: The local-first AI memory engine — a Rust crate that learns what matters and forgets the noise. |
3 | 3 | --- |
4 | 4 |
|
5 | | -# Introducing TinyCortex 🧠 |
| 5 | +# Introduction |
6 | 6 |
|
7 | | -Every AI memory system you've used does the same thing: store everything, retrieve by similarity, hope for the best. |
| 7 | +# TinyCortex 🧠 |
8 | 8 |
|
9 | | -The outcome: Your agent drowns in stale context. Responses degrade. Costs inflate. You end up writing custom pruning logic at 2am. |
| 9 | +**TinyCortex** is a local-first AI memory engine, shipped as the open-source Rust crate [`tinycortex`](https://crates.io/crates/tinycortex). It gives your agents a memory that works the way a brain does: it **intelligently forgets noise** so the model only reasons over what matters. |
10 | 10 |
|
11 | | -TinyCortex takes a fundamentally different approach. Inspired by how the human brain actually works, it **intelligently forgets noise** so your AI only reasons over what matters. Low-value memories decay naturally over time. Knowledge your users interact with gets reinforced and rises to the top. It doesn't require manual cleanup and there is no context window anxiety. |
| 11 | +Every AI memory system you have used does the same thing — store everything, retrieve by similarity, hope for the best. The outcome is an agent that drowns in stale context: responses degrade and costs inflate. TinyCortex takes the opposite approach. Low-value memories **decay** over time, while the knowledge your users recall and interact with is **reinforced** and rises to the top. There is no manual cleanup and no context-window anxiety. |
12 | 12 |
|
13 | | -The result: an AI memory system that processes over **1 billion tokens**, stays lean and focused, and gets smarter with every interaction. |
| 13 | +The engine ingests content, canonicalizes and chunks it, scores what is worth keeping, and **compresses** it into a hierarchical summary tree. Retrieval then serves a focused, explainable slice of long-term history — vector, keyword, graph, and tree search combined — instead of a noisy dump of everything ever stored. |
14 | 14 |
|
15 | | -For a deployment serving 100,000 users with ongoing conversation history: |
16 | | - |
17 | | -| Approach | Cost per user per year | |
18 | | -| ---------------------------------------------- | ---------------------- | |
19 | | -| Frontier model context (everything in-context) | \~$90,000 | |
20 | | -| Standard RAG pipeline | \~$2.40 | |
21 | | -| **TinyCortex** | **\~$0.72** | |
22 | | - |
23 | | -The 1,000:1 compression ratio means storage and compute costs grow slowly relative to conversation volume. TinyCortex indexes a conversation for $0.0004, compared to $0.0112 for Mem0 (28x lower). |
24 | | - |
25 | | -## Core Features |
26 | | - |
27 | | -### Intelligent Noise Filtering |
28 | | - |
29 | | -Memories that aren't accessed naturally decay over time. Frequently recalled knowledge becomes more durable. The system stays lean on its own without manual cleanup and intervention. |
30 | | - |
31 | | -<div align="center"><img src=".gitbook/assets/AppleEmailGraph.gif" alt="Memory Decay Simulation" width="700"></div> |
32 | | - |
33 | | -### Interaction-Aware |
| 15 | +{% hint style="info" %} |
| 16 | +This documentation covers the **open-source Rust crate**. The hosted TinyCortex platform (managed API, language SDKs) is a separate product in **closed alpha** — [reach out](mailto:founders@tinyhumans.ai) for access. Crate-only vs. hosted-only capabilities are called out throughout. |
| 17 | +{% endhint %} |
34 | 18 |
|
35 | | -Not all memories are equal. Views, reactions, replies, and content creation all signal what matters. Knowledge people engage with rises to the top; ignored information fades away. |
| 19 | +## Quickstart |
36 | 20 |
|
| 21 | +```bash |
| 22 | +cargo add tinycortex |
| 23 | +``` |
37 | 24 |
|
| 25 | +```rust |
| 26 | +use tinycortex::memory::{InMemoryMemoryStore, MemoryInput, MemoryQuery, MemoryStore}; |
38 | 27 |
|
39 | | -<div align="center"><img src=".gitbook/assets/BobMemoryDecayVideo.gif" alt="Interaction Graph" width="700"></div> |
| 28 | +#[tokio::main] |
| 29 | +async fn main() -> anyhow::Result<()> { |
| 30 | + let store = InMemoryMemoryStore::new(); |
40 | 31 |
|
41 | | -### Low Latency, Low Cost, High Quality |
| 32 | + store |
| 33 | + .insert(MemoryInput::new("preferences", "User prefers dark mode")) |
| 34 | + .await?; |
42 | 35 |
|
43 | | -No compromise on speed and quality when processing data with TinyCortex. Everything is processed at low cost and low latency while maintaining high benchmark scores |
| 36 | + let hits = store.search(MemoryQuery::text("theme preference")).await?; |
| 37 | + for hit in hits { |
| 38 | + println!("{:.3} {}", hit.score, hit.record.content); |
| 39 | + } |
| 40 | + Ok(()) |
| 41 | +} |
| 42 | +``` |
44 | 43 |
|
45 | | -| Metric | TinyCortex | Nearest Competitor | |
46 | | -| --------------- | ---------- | ------------------------- | |
47 | | -| Average latency | \~1.1s | \~3.6s (Mem0) | |
48 | | -| Query cost | \~$0.00095 | \~$0.00085 (Mem0) | |
49 | | -| Index cost | \~$0.0005 | \~$0.014 (Mem0, 28x more) | |
| 44 | +See **[Getting Started](getting-started.md)** for the full walkthrough, or jump to the **[Architecture Overview](architecture.md)** to understand how the engine fits together. |
50 | 45 |
|
51 | | -## Quick Start |
| 46 | +## Why TinyCortex |
52 | 47 |
|
53 | | -```bash |
54 | | -pip install tinyhumansai |
55 | | -``` |
| 48 | +* **Intelligent noise filtering** — memories that are not accessed decay; frequently recalled knowledge becomes durable. The store stays lean on its own. |
| 49 | +* **Interaction-aware** — views, replies, reactions, and authored content all signal what matters. |
| 50 | +* **Local-first & inspectable** — markdown files are the source of truth; SQLite, vectors, summary trees, and a git ledger are rebuildable derived indexes. |
| 51 | +* **Explainable retrieval** — every hit carries a score breakdown across graph, vector, keyword, and freshness signals. |
| 52 | +* **Provenance & safety** — every item carries source identity and a security `taint` (internal vs. external-sync). |
56 | 53 |
|
57 | | -```python |
58 | | -import tinyhumansai as api |
59 | | - |
60 | | -client = api.TinyHumanMemoryClient("YOUR_APIKEY_HERE") |
61 | | - |
62 | | -# Store a memory |
63 | | -client.ingest_memory({ |
64 | | - "key": "user-preference-theme", |
65 | | - "content": "User prefers dark mode", |
66 | | - "namespace": "preferences", |
67 | | - "metadata": {"source": "onboarding"}, |
68 | | -}) |
69 | | - |
70 | | -# Ask a question using stored memory |
71 | | -response = client.recall_with_llm( |
72 | | - prompt="What is the user's preference for theme?", |
73 | | - api_key="OPENAI_API_KEY" |
74 | | -) |
75 | | -print(response.text) # The user prefers dark mode |
76 | | -``` |
| 54 | +## Where to go next |
77 | 55 |
|
78 | | -That's it. Ingest memories, recall them with any LLM. TinyCortex handles the hard parts: deduplication, decay, graph-based retrieval, and noise pruning. |
| 56 | +| If you want to… | Read | |
| 57 | +| --------------- | ---- | |
| 58 | +| Install and run your first store | [Getting Started](getting-started.md) | |
| 59 | +| Understand the layered design | [Architecture Overview](architecture.md) | |
| 60 | +| Learn the vocabulary (namespaces, taint, decay, recall) | [Core Concepts](core-concepts.md) | |
| 61 | +| See how memories are compressed into a tree | [Memory Tree & Compression](memory-tree.md) | |
| 62 | +| Query memory | [Retrieval](retrieval.md) | |
| 63 | +| Read the generated API reference | [docs.rs/tinycortex](https://docs.rs/tinycortex) | |
79 | 64 |
|
80 | | -{% hint style="info" %} |
81 | | -TinyCortex is currently in **closed alpha**. To get access, [reach out to us](mailto:founders@tinyhumans.ai). |
82 | | -{% endhint %} |
| 65 | +[Discord](https://discord.tinyhumans.ai) • [Reddit](https://www.reddit.com/r/tinyhumansai/) • [X](https://x.com/tinyhumansai) • [crates.io](https://crates.io/crates/tinycortex) |
0 commit comments