What Rapu is — and what it isn't

Rapu is a personal memory and reasoning backend, exposed as MCP tools to whatever LLM you prefer. Before you plug your favorite LLM into it, read this. Some things will surprise you.

What Rapu actually is

Four layers, each useful on its own and each multiplied by the ones below:

1. Ingestion — anything you read, your brain reads

Drop a PDF, contract, deck, transcript, or paper into Rapu's folder. Forward your work email into the brain's address and every receipt, calendar invite, and conversation lands too. Each file is chunked, indexed, and embedded with vector representations into Postgres + pgvector. The brain doesn't just remember the filename — it understands what's inside, semantically, in the original language.

2. Extraction — structure surfaces automatically

Once content lands, the system extracts what matters: memories (facts you taught the brain in chat: "Otso is in P3B"), entities (the people, organizations, places, and projects mentioned across your content), and the relationships between those entities (Otso → attends → TES; Aleksi → works with → Kim). You don't tag anything by hand. The graph builds itself as new content arrives.

3. Apparatus — typed claims, calibration, argumentation

On top of the extracted layer sits the epistemic apparatus: atoms (typed claims — Fact / Position / Constraint / Decision / Hypothesis — with confidence, standpoint, decay class, provenance), projections (artifacts you render that cite specific atoms and freeze their state at render time), predictions (commitments that get scored later, with Brier-style probabilistic forecasting), argumentation edges (attacks and supports between atoms — including Dung grounded extension computation), and cross-brain consent (controlled read access between brains via brain_links).

4. MCP server — every LLM can use it

Rapu exposes ~30 tools as a standard MCP server. Any modern LLM client speaks MCP: Claude Code, Claude Desktop, Cursor, ChatGPT custom GPTs (via bridges), the Anthropic SDK, OpenAI agents, your in-house agent loop. Plug your favorite in once with the setup snippet and the LLM gets semantic search over your documents, access to your entity graph, write+read on your atoms, the ability to render projections, score predictions, walk causal chains, and simulate retractions — all with the same auth boundary.

It is not a chatbot. It is not a wrapper around ChatGPT. The chat UI at app.html is one convenience surface; the layered platform underneath is the actual product.

What happens when you connect an LLM

After you set up the connection (see Connect), your LLM client gets read + write access to your brain through the MCP tools. When you ask it something, this is the actual flow:

1. You type a question into your LLM client.
2. The LLM provider (Anthropic, OpenAI, whoever) receives your prompt + the list of available Rapu tools.
3. The LLM decides whether to call Rapu's tools. It might search your atoms, render a projection, score a prediction, walk an argumentation graph — or it might answer from its training data alone and never touch Rapu.
4. When it does call Rapu, those results flow back through the LLM provider and become part of the conversation context.
5. The LLM produces a reply, citing (or not) the atoms it pulled.

Privacy and data flow — the honest version

• Where atoms live: Rapu's Postgres database, hosted on Railway. Encrypted at rest by the platform; in transit via HTTPS.
• Who sees them: You. Any user you've granted brain_access to. The LLM you've connected (per query). The LLM provider (per query). Rapu's admin can technically read everything in the DB — same as any SaaS.
• Auth: Your rapu_usr_ API key. Treat it like a password.
• Cross-brain consent (brain_links): Grants read access from one brain to another. The target brain's user can see your shared atoms via their LLM. Revocable; revocation is immediate but audit history persists.
• What's not sent to the LLM: embeddings, internal scoring weights, your auth tokens. Only atom bodies + metadata when a tool returns them.

What you (still) have to do

The apparatus only reasons over what you put in. It's not magic.

• Atoms get written deliberately. Typing "remember X" into the chat creates a Rapu memory; an atom (with type, standpoint, decay class) is created when you or the LLM explicitly calls create_atom. The chat won't do that automatically yet.
• Predictions need scoring. A commissive projection auto-materializes a prediction row. But the prediction stays pending until you tell the system what actually happened. Calibration only kicks in after scoring.
• Argumentation only works if you declare edges. Atoms don't auto-detect "X attacks Y". You (or the LLM) have to call atom_relation_create when you see two claims that contest each other.
• Decay doesn't delete. A stale atom drops in ranking but stays in the DB. You decide whether to re-validate it, supersede it with a newer claim, or let it sit.

What this enables that ChatGPT alone can't

Group these in two tiers. The first tier is what any LLM you connect gets for free, the moment the connection is made. The second is the apparatus on top.

From the foundational layer — your LLM, but with persistent grounded memory

• Cross-conversation memory with provenance. A claim made in March is still recallable in September with the original document, email, or chat exchange attached.
• Semantic search over your real corpus. The LLM doesn't search filenames — it searches the chunked, vector-embedded content of everything you've ingested. "What did the LP say about ESG in the April letter?" finds the answer even if the word "ESG" never appeared in your question.
• Entity-resolved answers. When the LLM mentions Otso or your CFO, those map to specific entity rows with all their attributes and relationships. No more "which Mike?" — the brain knows.
• Relationship-aware reasoning. Ask "who's connected to the climate-tech fund?" and the LLM walks the entity graph: people who emailed about it, organizations referenced, projects linked. Real knowledge-graph traversal.
• Multi-modal ingest. PDFs, contracts, decks, emails, transcripts, social-import data — all in the same searchable surface.

From the apparatus layer — reasoning over time, not just retrieval

• Calibration tracking. See which of your commitments came true, with Brier scores per probability bin. Over time, "your confidence-4 atoms predict outcomes at 73%" — actually measurable.
• Forward causal chains. Before retracting a claim, see what depends on it.
• Argumentation graphs. Declare attack/support edges between atoms. The system computes the maximally-defensible subset (Dung grounded extension).
• Counterfactual simulation. "If I retract this hypothesis, which of my conclusions flip?"
• Cross-brain consensus. Across the brains you read from, where do they agree vs disagree on a topic?
• Decay as a query-time function. Older claims surface lower in ranked search without being deleted.
• Render-time snapshots. A projection from six months ago still cites the atoms it was rendered with, frozen at that state, even if those atoms have since evolved.

What this is NOT, and what it does NOT do

• The LLM is not "trained on" your brain. Atoms are passed as context per query. Change atom #5 today, every query tomorrow sees the new version.
• "Calibration" measures track record, not correctness. A Brier score of 0.04 means your stated probabilities matched outcomes — it doesn't mean your atoms are true.
• "Grounded extension" doesn't validate truth. It returns the maximally internally-consistent subset of your claims given your declared attack edges. A grounded extension can be entirely defensible internally and wholly wrong about the world.
• Decay weight is not a "truth probability". A claim at 32% decay weight isn't 32% true; it just hasn't been refreshed in a while.
• The LLM doesn't have to use Rapu. It chooses per query whether the tools are relevant. If you want grounded answers, prompt accordingly ("use my brain"). If you don't, your LLM still works fine — just without your memory.
• Rapu doesn't make decisions. It surfaces tradeoffs, dependencies, and calibration evidence. The judgment stays with you.
• The apparatus doesn't auto-detect contradictions. detect_conflicts surfaces semantically-similar atoms that might contradict. You decide if they actually do.

Honest limitations

• Your LLM is the bottleneck. Rapu surfaces are only as useful as the LLM's willingness to call them. Some LLMs are tool-eager, some aren't.
• Empty brains are mostly silent. Until you have ~20 scored predictions, the calibration math is too thin to mean much. Until you have ~10 declared argument edges, the grounded extension is mostly "everything is accepted".
• Multi-brain features need multiple brains. Cross-brain consensus and consent are only valuable if you're part of a team or portfolio. Solo users get less of the differentiated value.
• Real-time it isn't. Triggers fire on writes; queries are on-demand. The "calm garden" surfaces poll every 60 seconds, not instantly.
• Audit log retention has limits. We keep history; we don't keep it forever. Check your plan for specifics.

Where simpler tools still win

Rapu is overkill for a lot of use cases. If you want one of these, use something else:

• A folder of markdown notes. Portable, offline, git-native, opens in any editor. aju is one such option and the framework Rapu's apparatus ports from.
• A flashcard system. Anki is purpose-built for spaced repetition.
• A wiki. If your need is "linked notes I can edit" — use Notion, Obsidian, Logseq.
• A vector store. If you just want semantic search over docs, a plain pgvector or Qdrant setup is simpler.

Rapu's bet is that calibration loops, multi-brain consent, argumentation graphs, and structured-claim provenance are worth the extra weight when you're trying to think well over months and years. If they're not for your use case, that's an honest signal.