Stoa

The personal context layer for everything you learn.

Private by design and local-first: drop in anything, and stoa builds an ever-evolving wiki + knowledge graph you own.

Under the hood it's a real knowledge graph: stoa pulls the entities, relationships, and cited claims out of your documents and reconciles them into a self-consistent ontology, then answers with hybrid retrieval (semantic, keyword, and a graph walk) that surfaces the connected facts across your sources.

Quickstart · What is stoa? · Architecture · How it works · Export · Compare · Integrations · FAQ · Use cases

---

What is stoa?

Most of what you learn never gets synthesized. It sits in scattered PDFs, transcripts, notes, and threads you'll never re-read. stoa turns that pile into one connected, cited picture you can question, so your past reading compounds.

Drop in your files and stoa compiles them into a maintained knowledge graph and a cited wiki you can talk to, always showing its work. It builds the picture once and keeps it current as you add more, instead of re-reading your files on every question. It does the synthesis you'd otherwise do by hand: it recognizes "Acme" and "Acme Corp" are the same company, retires outdated facts (with history), and cross-links everything.

Your knowledge stays yours. A brain is a folder of plain files you own, and you choose where the AI runs, per brain. Nothing leaves your box without a loud, explicit choice. Keep a brain on your machine, on a server you host, or managed by us; share it with the people and agents you trust; and ask across several brains at once.

Why it's called stoa

The Στοά (stoá) was the porch in ancient Athens where the Stoic philosophers, the founders of propositional logic, met to think out loud, taking big ideas apart into small, clear claims and making sure it all held together. stoa does the same with your knowledge, run for you.

The engine builds on Andrej Karpathy's "LLM wiki": an LLM compiles your sources into a living wiki once and keeps it current, rather than re-deriving the same context on every query. stoa keeps that idea and adds to it:

• a real knowledge graph beneath the wiki: entities, relationships, and cited claims, not just prose;
• open standards so your brain stays portable: the wiki in Google's Open Knowledge Format (OKF), the graph as W3C JSON-LD (RDF), and everything in plain Markdown and files you own;
• sharing: invite people and agents, and mix local, remote, and managed brains in one question;
• tailored to your own documents, with no schema to author up front.

---

Architecture

stoa is one engine and one database.

• Engine. A Python service (FastAPI). It runs the pipeline that reads your files and the retrieval that answers your questions.
• Database. Ordinary Postgres with pgvector. Your files, the wiki, and the knowledge graph all live in it. The graph is a real entity-and-claim model inside Postgres, so there is no separate graph database, vector store, or search cluster to operate.
• Web UI. A React app the engine serves directly. Create brains, add documents, read the wiki, chat.
• MCP server. Built in, so any AI tool can reach a brain over the Model Context Protocol.

Files on disk are the source of truth. Postgres is a rebuildable index over them: delete it and rebuild from the folder, with no re-reading of your documents.

---

Quickstart

Two choices and you're running: where stoa runs, and which models power it.

Self-host from $0 fully local. We publish guidance and one-command quickstarts for two reference deployments — a light box for one person, and a production setup for teams.

Where it runs

Run it	Where	Data residency	Account / sign-up
Local — everything stays on your machine	your own computer (docker compose up)	your disk	No
Self-host — reachable anywhere (Lite or Production)	a server you run	your server / cloud account	No
Managed — we run it for you	always-on: 99.99% uptime, 11-nines durability	our infrastructure (opt-in, per brain)	Yes

Which models

You bring the models. Every path above works with any provider, and you can mix and match per brain.

Option	What it means	Inference traffic
Fully local	Run models with Ollama. No key, no cloud.	stays on your machine
Your own model provider	OpenAI, Anthropic, Google, or Amazon Bedrock (anything LiteLLM supports).	goes to the provider you chose, with your key
Managed inference (add-on)	Optional: we run the inference inside a no-human-access, confidential-computing enclave.	our private enclave: no one, not even us, can see it

The managed edition comes in two flavors:

• Bring your own provider (the default). Your prompts go straight to the provider you chose, never through us.
• Managed inference (add-on). We run fully-private, no-human-access inference for you.

Run it locally

Install Docker, point stoa at one model key (or a local model, free), and bring the whole stack up with one command. No account required to start, and nothing comes to us: your files, your keys, your machine.

1. Install Docker — the only hard prerequisite.
2. Point it at one model provider. Copy .env.example to .env and set a provider. For a fully local, no-key run, that's the whole config:

   STOA_LLM_PROVIDER=ollama
   

   stoa reaches Ollama on your host automatically; set STOA_OLLAMA_BASE_URL only to point elsewhere.
3. docker compose up — brings up Postgres and the stoa engine (web UI + API + MCP server), on one port.
4. Open http://localhost:8000 — create a brain, drop in a document, ask a question.

Every provider (Ollama, OpenAI, Anthropic, Amazon Bedrock, and more) is covered in the configuration reference.

Host it yourself

The same image runs everywhere; only the configuration differs. Costs below are measured on live AWS and exclude model usage.

Tier	What's included	Cost (idle)	Guide
Generic VPS	the Lite recipe on any small Docker host	$5–20/mo	deploy →
Lite (AWS)	one small box + automatic HTTPS, no load balancer	~$32/mo on-demand (≈$20–25 committed)	deploy →
Production	Fargate + Aurora Serverless v2 + load balancer	~$115–121/mo idle (up to ~$250 under load)	deploy →

One-command infra-as-code and the full itemized breakdown live in the deploy guide.

Or let us host it

Rather not run any of it? Managed hosting costs a fraction of self-hosting and removes the ops entirely.

Switching to managed is opt-in and additive. Your self-hosted and local brains stay exactly where they are, on your disk and your servers; nothing is uploaded, migrated, or mirrored to us unless you explicitly choose to host a specific brain with us. What it adds, when you do, is zero-ops hosting: always-on, synced across your devices, reachable by your tools anytime. By default, no data is ever hosted by us: you decide, per brain, what (if anything) to hand over, and you can move it back out anytime.

Join the waitlist for first access, special pricing, and early features.

---

How it works

The engine

You bring the raw material; stoa does the thinking work. Every stage runs automatically, and nothing is saved until you, as a human, approve it.

Stage	What happens	Why it matters
Ingest	Converts any file to clean text, strips boilerplate (headers, footers, reply-chains), and writes a short description of each source.	No tagging or folders, and you get a readable markdown copy of every source, not just an index.
Understand	Extracts the smallest claims and the entities they're about (people, projects, dates), each linked to the exact passage it came from.	Even complex questions get precise, sourced answers.
Reconcile	Resolves entities across documents ("Acme", "Acme Corp" become one), fits each new claim against the existing graph, supersedes stale facts, and surfaces contradictions.	Your knowledge stays coherent and current instead of piling up duplicates and stale facts.
A living graph	Maintains an entity-and-claim graph in Postgres; the cited wiki pages are projected from it and rewrite themselves as you add more.	The whole picture re-coheres on its own, with nothing to curate by hand.
Retrieve	Runs hybrid retrieval (semantic + keyword), walks the graph with personalized PageRank, optionally reranks, then writes an answer cited to your sources.	It surfaces connected facts a flat search misses, and says so when a source is thin.

Brains

A brain is stoa's core primitive: a self-contained unit of knowledge with its own documents, graph, wiki, model settings, and access rules. You can keep as many as you like, put each wherever you want, and query across them together.

Lives	on your machine (local), on a server you host (remote / self-hosted), or managed by us
Holds	the originals, processed markdown, the cited wiki, and the knowledge graph, as plain files you own
Runs on	its owner's model provider: your own key, a local model, or managed inference
Reached from	this app, or Claude / ChatGPT / your editor / the terminal, over MCP

Sharing a brain

A brain is private by default. As its owner you invite people as viewers (read and ask) or editors (also add documents), and everyone queries the same reconciled brain, in sync. A shared link never grants access on its own, and you stay in control of who can read, who can add, and what agents may write. Collaborators reach a shared brain from their own tools over MCP too, not just the app.

Because a brain can be local, remote, or managed, you can mix them: keep a private brain on your laptop, host a team brain on a server, and ask one question across both at once. Every answer labels which brain each source came from.

Who pays, and where data flows

A brain always runs on its owner's model provider. Query your own brain and it uses your key or your local model. Query a brain someone shared with you and the owner's setup does the work; you just ask. Your prompts and documents go only to the model provider the brain is pointed at, never to a stoa server.

The wiki

The wiki is the human-facing side of the very graph your agents query. stoa projects the knowledge graph into a browsable, cited wiki (one page per entity: a person, project, concept, event, or organization) and rewrites those pages as you add sources.

Every page is built to be trusted:

• A citation on every claim. Each fact carries a [n] that opens the exact passage in the exact source it came from; hover to preview it, click to jump.
• Change history, tracked per person. Nothing is overwritten silently: when a fact is superseded, stoa records what replaced it, which source introduced the change, and (on a shared brain) who made it.
• Structured facts + related concepts. Alongside the prose, each page lists its key claims and links to the entities it connects to, colored by type.
• Two views, one graph. Read it as pages, or flip to the graph to explore how everything connects: drag a node, click a neighbor to re-center, search to jump.

Because the wiki is a projection of the graph, it stays coherent on its own: add a source and the affected pages re-cohere, with nothing to curate by hand.

---

Export your brain

Your knowledge is yours, in open formats, and you can take it any time.

Only a brain's owner can export it. The Export menu hands you a file on your device, in three forms:

Export	What you get	Format
Everything	the full portable bundle: your files, the wiki, and the knowledge graph	a .zip
Knowledge graph	just the graph, as a W3C standards view	JSON-LD (RDF)
OKF bundle	the wiki as a conformant Open Knowledge Format archive that opens in Obsidian and any Markdown editor	a .zip

The exact bundle layout is documented in docs/brain-bundle-format.md.

---

How stoa compares

stoa isn't another app to work in, and it isn't here to replace your chatbot, notes app, or assistant. It's the layer underneath them: the place your knowledge actually lives, which those tools reach over MCP. Each of them nails part of the job (a chatbot reasons, a notes app organizes, an AI-memory tool remembers). What none of them do is turn your own documents into one maintained, entity-resolved, fully-cited knowledge base you can reach from anywhere and truly own. stoa does that, then hands the result back to the tools you already like.

Capability	Chatbot	Notes app	AI memory	stoa
Turns any document into a retrievable corpus	◐ connects to sources; stores nothing itself	◐ stores, doesn't extract	◐ no denoising or cleaning	✅
Maintained knowledge graph	—	◐ graph visualization, not a graph model	◐ conversation-recall memory, no cited wiki over it	✅ entity-resolved, kept current
Retrieval beyond semantic search (keyword + graph walk)	◐ possible, but closed	—	◐ some fuse signals; varies	✅
Every answer cited to your source	◐ cites files, but can hallucinate	—	✅ some cite; depth varies	✅ [n] to the exact passage, deep-linked
Provenance — trace each fact to its source, with change history	—	—	◐ recall, no source spans	✅ cited spans + supersession history
Programmatic access (MCP + CLI)	◐ calls out to sources	◐ limited, sometimes paywalled	✅ API / MCP-first	✅ MCP + CLI
Shareable — invited people grow one brain together, in sync	—	✅ real-time editing	◐ per-user partitions, not co-writing	✅
Open source — inspect it, self-host it, own it	—	◐ a few are; most aren't	—	✅

---

Integrations

stoa plugs into the AI tools you already use, via MCP or CLI (Claude, ChatGPT, your editor, the terminal), so you can ask your brain and cite it right where you work. Step-by-step connect guides per client are in docs/connect/.

Authentication

You choose how a client proves who it is. stoa runs its own OAuth 2.1 authorization server for browser connectors and mints scoped, revocable personal access tokens for everything else, and you can see and revoke connected apps and tokens anytime in Settings.

Method	Best for	How it works
OAuth 2.1 (3-legged)	connector clients: Claude.ai, ChatGPT	Browser sign-in with a consent screen where you grant read or write; nothing to copy. Opt-in on your instance.
Personal access token	agents & editors: Claude Code, Cursor	Mint a scoped (read / write), revocable token in Settings → Access tokens; the client sends it as Authorization: Bearer. The default.
Token-free local	stoa on your own machine	Tools launch stoa over stdio: no token, no login.

Tools

Tool	What it does
stoa_ask	Ask a question; get a cited, synthesized answer with source deep-links.
stoa_list_brains	List the brains you can access.
stoa_lookup_entity	Look up one thing: its facts and relationships, structured (with supersession history on request).
stoa_ingest_document	Add a document (staged for your review unless the brain opts into auto-write).
stoa_ingest_status	Poll an ingest job to completion.

The skill

stoa comes with a skill that teaches your agent to use stoa well:

• Reach for your brain first for what you've saved, instead of guessing from training or the web.
• Cite its sources, and never mangle your files.
• Treat staged writes as pending your review: it won't claim something's saved until you approve it.
• Offer to save the things worth keeping.

It's a starting point, so make it yours: tailor it to how you work and what you keep in your brain (which brains hold what, the phrasing you use, what's worth capturing).

The CLI

stoa ships a stoa command-line tool that does everything the app and API can, run inside the backend container (bring the stack up first):

docker compose exec backend stoa <command>

Common commands: create-brain and list-brains; ingest <brain> <file>; ask <brain> "<question>" (add --also-brain to ask across several); export and import a brain's portable bundle; lint and prune for health checks; and reembed to switch embedding models. A developer eval harness is included for benchmarking retrieval.

---

FAQ

🧭 The basics

A personal context layer for everything you learn. Drop in your files, and stoa compiles them into a maintained knowledge graph and a cited wiki you can talk to, always showing its work. Instead of re-reading your files on every question, it builds the picture once and keeps it current as you add more.

Most of what you learn never gets synthesized. It sits in scattered PDFs, transcripts, notes, and threads you'll never re-read. stoa turns that pile into one connected, cited picture you can question, so your past reading compounds.

Documents, today: PDFs, Word / PowerPoint / Excel files, plain text, Markdown, HTML, and CSV. And here's the point: you don't have to prep any of it. Drop it in however messy it is; stoa converts it to clean text, strips the noise (headers, boilerplate, reply-chains), and pulls out the meaning, then builds its graph on that clean version. No formatting, tagging, or structure required from you. On the way: audio & video transcription, live-link fetching, richer image understanding, and source connectors.

No. Cleaning, extraction, graph-building, reconciliation, and retrieval all happen automatically. stoa shows you what it did if you're curious, but you never configure any of it. If you want to peek under the hood, see How it works.

Short answer: because it keeps stoa simple to run, while still giving you a real graph. The knowledge graph is a real entity-and-claim model in ordinary Postgres, not a bolt-on:

• Entities, relationships, and claims are first-class rows. Graph traversal runs as a recursive query, and multi-hop retrieval walks the graph with Personalized PageRank.
• One store for everything: your files, the wiki, the graph, and the vector embeddings (pgvector) all live in that Postgres, so hybrid retrieval (meaning + keyword + graph walk) needs no separate graph database or vector cluster.
• Simple and portable: the whole stack comes up with docker compose up, runs at $0 locally, and the database is just a rebuildable index over your files.

🔒 Local-first & ownership

Two things most tools don't give you together. Your brain is a folder of plain files you own (the originals, the processed markdown, the wiki, and the graph), so you can move it, open it anywhere, or delete it anytime, with no lock-in. And you choose where the AI runs: a cloud model with your own key, or a fully local model, per brain.

Only if you choose it. A local brain runs entirely on your device. Point a brain at a cloud model and your prompts go to that provider with your key. There is no silent cloud fallback: nothing leaves your box without a loud, explicit choice.

Always. Bring your own key (OpenAI, Anthropic, Bedrock, or anything LiteLLM supports), or run local models with Ollama. You're never locked to one provider: configure as many as you like and mix and match across brains. If you'd rather not think about providers at all, the managed edition offers an optional managed-inference add-on where we run it for you, fully private thanks to confidential computing, so no one, not even us, can see your data.

👥 Sharing & teams

Yes. Invite people as viewers (read & ask) or editors (also add documents). It's private by default, a shared link never grants access on its own, and collaborators can reach a shared brain over MCP too, from their own tools.

That's a core use case: a shared brain is one source of truth a whole team asks and contributes to, while you stay in control of who can read, who can add, and what agents may write.

☁️ The managed edition

Yes. The full engine is free and open source (Apache-2.0), self-hosted on your own machine with your own model key, and nothing comes to us. The managed edition is for people who'd rather not run it themselves: hosted, zero-ops, private by design. You'd pay for the convenience, never for capability. See the pricing page for details.

Yes. By default you bring your own model provider, so anything you send goes only to the provider you chose. With the optional Maximum privacy add-on, we run the inference for you inside a no-human-access architecture, so no one, not us and not even the model provider, can see your data. Instead of relying on human administrators to obey privacy rules, it relies on technical restrictions built straight into the core infrastructure:

• No shell access — there's no way to open terminal connections or use standard tools like SSH or physical serial consoles.
• Scoped admin APIs — operators can only interact with the environment via isolated, pre-programmed, authenticated, and fully audited APIs, none of which have the authority to extract or view your data.
• Confidential computing hardware — advanced chip architecture encrypts your data directly within the CPU and GPU memory buffers, not just at rest.
• Cryptographic attestation — before any machine is given the keys to your data, it must mathematically prove it's running the exact approved, untampered software.

Join the waitlist for early access.

---

Use cases

However you work, solo or as a team, stoa turns your pile of context into answers you can trust. Pick the one that sounds like you.

Months of meeting notes, specs, and threads about a launch.

• On your own: you scroll Slack and three docs, half-remember who owns what, and rebuild the picture from scratch every time someone asks.
• With a chatbot or notes app: it has your docs and threads and will pull the ones that mention the launch. But it retrieves by similarity; it doesn't hold the relationships between the pieces: the decision, who made it, and how the facts have evolved since.
• With stoa: it follows decision → owner → what changed, retires the earlier go-live date instead of returning both, and cites the launch review, the sync notes, and the pricing thread.

Dozens of papers on retrieval, half-read, scattered across your disk.

• On your own: you remember two of them disagreed but not which, so you re-skim a dozen PDFs to find the tension again.
• With a chatbot or notes app: it'll summarize any paper you name, even weigh two side by side. What it's missing is the web between them: which finding refines, contradicts, or supersedes which, across all of them at once.
• With stoa: it hops from the shared claim out to each paper and surfaces the disagreement as a disagreement, citing both sides, not two stray hits.

Discovery calls, follow-up emails, and CRM notes for every account.

• On your own: you skim the last call transcript before the next one and hope you remember what actually mattered.
• With a chatbot or notes app: it's wired into your inbox and CRM and will pull the last email and the call notes. But it fetches the closest-matching snippets, not the account's relationship graph: the stakeholders, the commitments you made, how their objections shifted, what's true now.
• With stoa: it walks account → champion → prior commitment and reconciles the noisy history into the current picture, not every old snippet.

One dispute across a master agreement, its amendments, a side letter, and case law.

• On your own: you reconcile the master agreement against two amendments and a side letter by hand, pin down which definition controls, then line up the authorities that cut each way.
• With a chatbot or notes app: it'll surface the clause, the amendment, the case. But it won't track which amendment supersedes which, which defined term is in force, or where two authorities conflict.
• With stoa: it tracks the supersession and the redefined term, and flags the authorities that agree and the ones that don't, each one cited.

A semester of lecture slides, textbook chapters, and your own messy notes.

• On your own: you Ctrl-F across a folder of PDFs and still can't line up the lecture with the reading that explained it.
• With a chatbot or notes app: it can find the lecture that covers a topic, but it treats each PDF as its own blob, so it won't connect that lecture to the reading, or notice your notes and the slides mean the same thing in different words.
• With stoa: it recognizes the lecture, the textbook chapter, and your notes are the same concept worded differently, and links them into one cited page.

Sales, engineering, and product feeding one shared brain.

• On your own: each person searches their own inbox and docs; the picture lives in five heads and never lines up in one place.
• With a chatbot or notes app: teams keep a wiki and dump files in a shared drive, then point an assistant at the pile and hope. Similarity search over a stale dump isn't a maintained, shared brain.
• With stoa: different people fed those facts, and stoa reconciles them into one current answer everyone sees, no matter who asked.

---

Contributing & community

stoa is in active development and we'd love your help: issues, ideas, and pull requests are all welcome. If you're using stoa with a document type or model provider we don't cover well yet, tell us. Those reports shape what gets built next. (Contribution guidelines are on the way.)

License

stoa is open source under the Apache License 2.0 (see also NOTICE).