Your staff. Your companion. Your virtual friend.
A local AI companion with a memory of its own.
Contents
Two parts
01 · Overview
The problem · The product · What makes it different · One brain, many surfaces · What it does for you · What we are looking for
02 · Technical
The challenge · Read, understand, remember, recall · Measured results · Tech stack · Architecture · What we learned
01 · Part one
Overview
The vision: what TerranSoul is, and why it matters now.
The problem
Today's AI still isn't yours
It forgets you
Most assistants lose everything the moment you close the tab — no memory, no continuity.
It lives in the cloud
Your data leaves your device every time you use it.
It's behind a paywall
Powerful AI is locked behind a monthly subscription.
The product
A companion that lives on your computer
Not a chatbot in a tab. TerranSoul is an on-device presence with persistent memory — it remembers across sessions and picks up right where you left off.
The demo
See it work
TerranSoul running locally — reading, remembering and recalling.
What makes it different
Memory does the learning
Frozen model
The language model never changes. The memory around it gets smarter instead.
Data, not weights
Every memory is auditable, reversible and portable — you can inspect it and move it.
A substrate, not a rival
Built to plug into tools like Claude Code and OpenClaw — complementary, not competing.
Your own machine
Local models, no subscription, no cloud dependency.
One brain, many surfaces
One memory, served everywhere
The same memory, knowledge graph and code intelligence, served to every client over MCP.
Desktop app
Discord · Telegram · Slack · WhatsApp
Claude Code · Copilot
Cursor · Codex
What it does for you
A companion that works with you
Companionship that remembers
An always-present companion for people living alone, or anyone who finds technology hard.
Levels the playing field
Free, local AI help — not gated behind a subscription only big budgets can afford.
A teammate for your other tools
Shares its memory with Claude Code, Copilot, Cursor and Codex, so they stop re-learning your context.
Private by design
Runs on your own machine — your data never leaves your device.
02 · Part two
Technical
Under the hood: how the memory actually works.
The challenge
A document isn't knowledge — yet
Hand the app a PDF or a scan and it sees pixels and characters, not meaning. Turning that into memory it can recall later is the hard part.
- Read it
- Understand it
- Connect it
- Recall it
The hard part isn't storing text. It's turning text into something the app can recognise again when you ask a question worded completely differently.
The big picture
The journey of a memory
1 · Read
Parse documents and conversations into raw text.
2 · Understand
Split into passages, embed each into a 768-dimension meaning space.
3 · Remember
Store across three decaying tiers, link related facts in a knowledge graph.
4 · Recall
Blend six retrieval signals and rerank before answering.
Step 1 · Read
Reading anything — even a photo
Optical character recognition
An on-device engine looks at the image and reads the letters back out as text.
Multilingual by design
Including Vietnamese — accented characters that trip up most off-the-shelf readers.
Spotlight: Vietnamese
“Tôi học tiếng Việt.” Those marks above the letters carry meaning. Drop one and the word changes — or the reader crashes.
Step 4 · Recall
Finding the right answer
The brain no longer just keyword-matches. It blends six signals, fuses them with reciprocal rank fusion, sharpens cold queries with HyDE, and reranks with a cross-encoder before anything reaches the model.
Vector similarity
Keyword match (BM25)
Knowledge-graph links
Recency
Importance
Decay
Architecture
How the brain is built
- Clients — desktop chat, coding agents, chat bots
- MCP gateway — single source of truth, routes every request
- Hybrid RAG — vector + lexical + graph + freshness, fused and reranked
- Memory — three decaying tiers + typed knowledge graph
- Storage — SQLite WAL + vector index
A self-improvement loop runs alongside: write → manage → read, on every turn.
Tech stack
What it's built with
- Frontend
- Vue 3.5 · TypeScript · Vite · Pinia
- 3D avatar
- Three.js · @pixiv/three-vrm 3.5
- Desktop shell
- Tauri 2.11
- Backend
- Rust
- Data & memory
- SQLite (WAL) · FTS5 · HNSW / IVF-PQ index
- AI / models
- Ollama · local Gemma models · cloud fallback
On-device first — private by default, no cloud required.
What we learned
Lessons from building the brain
Memory can beat weights
On some benchmarks, a small frozen model with good memory outscores much larger fine-tuned ones.
Never lose what you learn
Consolidation runs with a faithfulness check and a rollback, so memories shrink safely instead of vanishing.
One brain beats five
Sharing memory over MCP means every tool stops re-learning the same context from scratch.
Design for real input
The hardest bugs still come from messy real-world data, not the demo.
Update
What's changed since this deck
The original deck pitched a document-reading assistant. The current build is a lot bigger.
Solo app → shared brain
The same memory now serves Claude Code, Copilot, Cursor, Codex and peer TerranSoul instances over one protocol (MCP).
Embeddings → hybrid recall
Answers now fuse vector search, keywords, recency and graph links, then get reranked before anything reaches the model.
Chat window → chat platforms
First-party Discord, Telegram, Slack and WhatsApp bots route through the exact same brain as the desktop app.
Pitch → benchmarked
The team now publishes head-to-head recall and answer-quality numbers against other systems.
The guide
Ask the site anything
A guide sits on every page and answers from what this site actually publishes — the same memory idea TerranSoul is built on, pointed at our own pages. It cites the page each answer came from, so you can check it.
Retrieval, not improvisation
It answers from published passages and says it does not know when nothing matches. Ask it for a throughput figure and it declines, because we have not published one.
It knows the graph
The memory graph, the deck, the Tesseres pipeline and the team pages are all indexed — so "where do I find…" is a question it can actually answer.
Open it from the button in the corner of any page.