recallos 4.1.0

RecallOS — Local-first AI memory operating system. No API key required.

RecallOS

Persistent AI memory that lives on your machine.

The highest-scoring local AI memory system ever benchmarked. Open source. Free forever.

96.6% LongMemEval R@5 Zero API calls

100% LongMemEval R@5 with Haiku rerank

+34% Retrieval boost from vault structure

$0 No subscription No cloud. Local only.

_{Reproducible — runners in benchmarks/. Full results.}

Quick Start · How It Works · Benchmarks · MCP Tools · Website

---

Every conversation you have with an AI — every decision, every debugging session, every architecture debate — disappears when the session ends. Six months of daily AI use produces 19.5 million tokens of reasoning. Gone.

RecallOS stores everything, makes it retrievable, and gives your AI a memory that compounds over time. No cloud. No API key. No subscription.

• The Data Vault — Organizes long-term AI memory into Domains, Nodes, Channels, Index Summaries, and Source Records. Structure alone improves retrieval by 34%.
• RecallScript — A 30× lossless compression dialect readable by any LLM. Load months of context in ~120 tokens. Works with Claude, GPT, Gemini, Llama, Mistral — any model that reads text.
• Local, open, adaptable — Runs entirely on your machine. Tested on conversations, adaptable to any datastore. That's why it's open source.

---

Quick Start

pip install recallos

# Set up your working world
recallos init ~/projects/myapp

# Ingest your data
recallos ingest ~/projects/myapp                            # projects — code, docs, notes
recallos ingest ~/chats/ --mode convos                     # convos — Claude, ChatGPT, Slack, Discord exports
recallos ingest ~/chats/ --mode convos --extract general   # classifies into decisions, milestones, problems
recallos ingest ~/projects/myapp --encode                  # store RecallScript-compressed versions

# Query anything you've ever discussed
recallos query "why did we switch to GraphQL"

# Health check
recallos status
recallos doctor

Three ingest modes: projects (code and docs), convos (conversation exports — Claude, ChatGPT, Slack, Discord, Obsidian), and general (auto-classifies into decisions, preferences, milestones, problems, and emotional context).

---

How You Actually Use It

After setup, you rarely run RecallOS manually. Your AI uses it for you.

With Claude, ChatGPT, Cursor (MCP-compatible tools)

claude mcp add recallos -- python -m recallos.mcp_gateway

Now your AI has RecallOS tools available through MCP:

"What did we decide about auth last month?"

Claude calls recallos_query automatically, gets verbatim results, and answers you.

With local models (Llama, Mistral, or any offline LLM)

# Load your world into the model's context
recallos bootstrap > context.txt

# Or query on demand
recallos query "auth decisions" > results.txt

Or use the Python API:

from recallos.retrieval_engine import search_memories
results = search_memories("auth decisions", vault_path="~/.recallos/vault")

Either way, your entire memory stack runs offline. ChromaDB on your machine, your model on your machine, zero cloud calls.

---

How It Works

The Data Vault

  ┌─────────────────────────────────────────────────────────────┐
  │  DOMAIN: Person                                            │
  │                                                            │
  │    ┌──────────┐  ─channel─  ┌──────────┐                   │
  │    │  Node A  │             │  Node B  │                   │
  │    └────┬─────┘             └──────────┘                   │
  │         │                                                  │
  │         ▼                                                  │
  │    ┌────────────────┐   ┌───────────────┐                  │
  │    │ Index Summary  │ ─▶│ Source Record │                  │
  │    └────────────────┘   └───────────────┘                  │
  └─────────┼──────────────────────────────────────────────────┘
            │
           link
            │
  ┌─────────┼──────────────────────────────────────────────────┐
  │  DOMAIN: Project                                           │
  │         │                                                  │
  │    ┌────┴─────┐  ─channel─  ┌──────────┐                   │
  │    │  Node A  │             │  Node C  │                   │
  │    └────┬─────┘             └──────────┘                   │
  │         │                                                  │
  │         ▼                                                  │
  │    ┌────────────────┐   ┌───────────────┐                  │
  │    │ Index Summary  │ ─▶│ Source Record │                  │
  │    └────────────────┘   └───────────────┘                  │
  └─────────────────────────────────────────────────────────────┘

Domains — a person, project, or topic. As many as you need. Nodes — specific topics within a Domain. Auth, billing, deploy — unlimited Nodes. Channels — structured memory pathways: channel_facts, channel_events, channel_discoveries, channel_preferences, channel_guidance. Links — cross-domain connections between matching Nodes. Index Summaries — compressed retrieval layers. Fast for AI to read. Source Records — the original verbatim files. Never summarized away.

Why Structure Matters

Tested on 22,000+ real conversation memories:

Search all summaries:        60.9%  R@10
Search within domain:        73.1%  (+12%)
Search domain + channel:     84.8%  (+24%)
Search domain + node:        94.8%  (+34%)

The Memory Stack

Layer	What	Size	When
L0	Identity Layer	~50 tokens	Always loaded
L1	Core Context Layer	~120 tokens (RecallScript)	Always loaded
L2	Node Recall Layer	On demand	When a topic comes up
L3	Deep Retrieval Layer	On demand	When explicitly asked

Your AI bootstraps with L0 + L1 (~170 tokens) and knows your world.

RecallScript Compression

30× lossless compression. Any LLM reads it. No decoder required.

English (~1000 tokens):

Priya manages the Driftwood team: Kai (backend, 3 years), Soren (frontend),
Maya (infrastructure), and Leo (junior, started last month). They're building
a SaaS analytics platform. Current sprint: auth migration to Clerk.
Kai recommended Clerk over Auth0 based on pricing and DX.

RecallScript (~120 tokens):

TEAM: PRI(lead) | KAI(backend,3yr) SOR(frontend) MAY(infra) LEO(junior,new)
PROJ: DRIFTWOOD(saas.analytics) | SPRINT: auth.migration→clerk
DECISION: KAI.rec:clerk>auth0(pricing+dx) | ★★★★

Contradiction Detection

Input:  "Soren finished the auth migration"
Output: 🔴 AUTH-MIGRATION: attribution conflict — Maya was assigned, not Soren

Input:  "Kai has been here 2 years"
Output: 🟡 KAI: wrong_tenure — records show 3 years (started 2023-04)

Facts checked against the Recall Graph. Ages and dates calculated dynamically.

---

Recall Graph

Temporal entity-relationship triples — like Graphiti, but SQLite instead of Neo4j. Local and free.

from recallos.recall_graph import RecallGraph

rg = RecallGraph()
rg.add_triple("Kai", "works_on", "Orion", valid_from="2025-06-01")
rg.query_entity("Kai")
rg.find_path("Kai", "Clerk")
rg.timeline("Orion")
rg.export_dot()    # Graphviz DOT string
rg.export_json()   # D3-ready adjacency JSON

Feature	RecallOS	Zep (Graphiti)
Storage	SQLite (local)	Neo4j (cloud)
Cost	Free	$25/mo+
Temporal validity	Yes	Yes
Self-hosted	Always	Enterprise only

---

Domain Agents

Specialist agents with their own memory. Each agent gets its own Domain and Agent Log in the Data Vault.

~/.recallos/agents/
  ├── reviewer.json       # code quality, patterns, bugs
  ├── architect.json      # design decisions, tradeoffs
  └── ops.json            # deploys, incidents, infra

Agent logs are file-backed (~/.recallos/agent_logs/<agent>/YYYY-MM-DD.jsonl) and indexed in ChromaDB for semantic search. Files rotate automatically after 30 days.

---

MCP Server

claude mcp add recallos -- python -m recallos.mcp_gateway

22 tools across 5 categories:

Category	Tools
Data Vault (read)	recallos_status, recallos_list_domains, recallos_list_nodes, recallos_get_topology, recallos_query, recallos_check_duplicate, recallos_get_recallscript_spec
Records (write)	recallos_add_record, recallos_delete_record
Recall Graph	recallos_graph_query, recallos_graph_add, recallos_graph_invalidate, recallos_graph_timeline, recallos_graph_stats, recallos_graph_path
Link Navigation	recallos_traverse_links, recallos_find_links, recallos_topology_stats
Agent Logs	recallos_log_write, recallos_log_read, recallos_log_search

The AI learns RecallScript and the memory protocol automatically from recallos_status.

---

Benchmarks

Benchmark	Mode	Score	API Calls
LongMemEval R@5	Raw (ChromaDB only)	96.6%	Zero
LongMemEval R@5	Hybrid + Haiku rerank	100% (500/500)	~500
LoCoMo R@10	Raw, session level	60.3%	Zero
Data Vault structure	Domain+Node filtering	+34% R@10	Zero

vs Published Systems

System	LongMemEval R@5	API Required	Cost
RecallOS (hybrid)	100%	Optional	Free
Supermemory ASMR	~99%	Yes	—
RecallOS (raw)	96.6%	None	Free
Mastra	94.87%	Yes (GPT)	API costs
Mem0	~85%	Yes	$19–249/mo
Zep	~85%	Yes	$25/mo+

---

All Commands

recallos init <dir>                                  # guided onboarding
recallos migrate [--dry-run] [--force]               # migrate from ~/.mempalace/
recallos ingest <dir>                                # ingest project files
recallos ingest <dir> --mode convos                  # ingest conversations
recallos ingest <dir> --encode                       # also store RecallScript versions
recallos split <dir>                                 # split concatenated transcripts
recallos query "query"                               # semantic search
recallos query "query" --domain myapp                # scoped to a domain
recallos bootstrap                                   # load L0 + L1 context
recallos encode [--domain myapp]                     # RecallScript encode records
recallos status                                      # vault overview
recallos doctor [--verbose]                          # full health report

All commands accept --vault <path> to override the default vault location.

---

Project Structure

recallos/
├── README.md                     ← you are here
├── recallos/                     ← core package
│   ├── cli.py                    ← CLI entry point
│   ├── mcp_gateway.py            ← MCP gateway (22 tools)
│   ├── recall_graph.py           ← temporal entity graph
│   ├── vault_graph.py            ← node navigation graph
│   ├── recallscript.py           ← RecallScript compression
│   ├── ingest_engine.py          ← project file ingest
│   ├── conversation_ingest.py    ← conversation ingest
│   ├── retrieval_engine.py       ← semantic retrieval
│   ├── bootstrap.py              ← guided setup
│   ├── migration.py              ← migrate ~/.mempalace/ data
│   ├── diagnostics.py            ← vault health checks
│   ├── agent_log.py              ← file-backed agent logs
│   └── ...
├── site/                         ← landing page (recallos.com)
├── benchmarks/                   ← reproducible benchmark runners
├── hooks/                        ← Claude Code auto-save hooks
├── examples/                     ← usage examples
├── tests/                        ← test suite
├── 01_all_md_files/              ← supplementary documentation
│   ├── CHANGELOG.md
│   ├── CONTRIBUTING.md
│   ├── REBUILD_PLAN.md
│   ├── ReCallOS.features.readme.md
│   ├── ReCallOS.user-benefits.readme.md
│   └── ...
└── pyproject.toml                ← package config

---

Requirements

• Python 3.9+
• chromadb>=0.4.0
• pyyaml>=6.0

No API key. No internet after install. Everything local.

pip install recallos

---

Documentation

Document	Description
Feature List	Complete technical reference — every capability, flag, API method, and config option
User Guide	Plain-English guide — what RecallOS does for you, use cases, getting started
Contributing	Setup, PR guidelines, code style, good first issues
Changelog	Full development history across all build phases
Rebuild Plan	Architecture decisions and naming conventions
Web Roadmap	CLI → web service development plan

---

Contributing

PRs welcome. See CONTRIBUTING.md for setup and guidelines.

License

MIT — see LICENSE.