Topos

A digital twin, built from your own data.

Connect the data you choose, and it takes the shape of you. Keep it private, or give access to your friends, your AIs, or the organizations you belong to — each seeing only what you allow.

Website · Docs · Quick start · How it works · Discord

https://github.com/user-attachments/assets/4b63edf7-feff-4296-b9f9-07b3569e0f58

What Topos is

Topos is a small program you run on your own computer.

You connect the data you already have — messages, mail, calendar, files, notes, browsing history, past AI chats — one source at a time, and only the ones you choose. Whatever you connect lands in one shape, and from that shape Topos builds a working model of you: what you know, who you know, where your attention goes, and how all of it has changed over time. Not a backup of your files — a representation of the person who made them.

That model stays on your disk. An engine sits on top of it to answer questions about your life, and a permission layer decides exactly what any app, assistant, or person gets back.

So you can ask it the things you would never paste into ChatGPT — and you can carry a slice of yourself to a friend, an AI, or an organization without handing over the rest.

  YOUR DATA             TOPOS DATABASE         TOPOS ENGINE           THE ANSWER
  ─────────             ──────────────         ────────────           ──────────
  mail · chat           one SQLite file        reads, reasons,        scoped
  calendar · files      on your disk,          enforces your          filtered
  notes · browsing  ─▶  yours alone        ─▶  permissions        ─▶  logged
  AI chat history

Four things it does


🔌	Connect	Choose which sources to plug in — mail, chat, calendar, files, notes. Nothing comes in that you didn't connect.
🧬	Shape	What you connect is formed into a model of you — what you know, who you know, how it has changed.
💬	Ask	Put the questions to it that you would never send to a cloud assistant.
🤝	Carry	Bring a slice of yourself to friends, AIs, and the organizations you are part of. Each sees only what you allow.

Quick start

You need a Dialogues account to get a Topos key — the credential that pairs the node on your machine with your account. Sign up at topos.dialogues.ai and open Create Topos; your key is on that screen.

Option A — macOS app (easiest)

On the Create Topos screen, click Download to get Topos.dmg (signed and notarized).
Mount it, drag Topos into Applications, and launch it. A menu-bar icon appears.
Back in the browser, click Connect this Mac and allow the prompt. The app takes a one-time pairing code and stores your key.
Leave the page open while it prepares: the node downloads its engine (~900 MB) and language models (~2.9 GB). The menu-bar icon shows progress.

Option B — terminal (macOS, Linux, Windows)

Install uv if you do not have it:

curl -LsSf https://astral.sh/uv/install.sh | sh

Then:

uv tool install topos-node
topos-node --set-topos-key "<YOUR_TOPOS_KEY>"
topos-node

Your key is written to ~/.topos/.env with restricted permissions. The node starts on port 8676 and connects out to the control plane.

Check that it is up:

curl http://localhost:8676/healthcheck

Your Topos now shows as Connected in the web app, and you can start adding sources.

What it connects to

Kind	Sources available today
💬 Messages	iMessage, Signal Desktop
🤖 AI history	ChatGPT (export file, and live conversations)
🗂️ Work & docs	GitHub activity, Notion pages, Google Drive
📅 Calendar	Google Calendar
🌐 Web	Browser visits, browser events (highlights, stars)
🎙️ Transcripts	VoxTerm voice transcripts, YouTube transcripts
👥 People	Canonical address book
🧪 Demo data	Ten fixture sets — messenger, email, calendar, journal, resume, finance, browsing, places, contacts — so you can try Topos before connecting anything real
🔧 Your own	Anything not on this list — build a connector for it. Keep it private to your node, or share it to the community catalog for others to install in one click.

Sources are not hardcoded. Connectors are declared at sheaf.dialogues.ai and installed by your node at runtime — one you build stays private to your node until you choose to share it.

Connect an assistant

Your node speaks MCP, so Claude and ChatGPT can query it — through the control plane, which routes the request to your machine rather than holding your data.

Claude Desktop — point the MCP adapter at the control plane's /mcp endpoint with your Topos key as the bearer token.
ChatGPT — add the same URL as a connector and sign in with Dialogues.

One node, one key, both assistants. See Docs → Install Topos.

How it works

From the apps you plug in, to the assistant asking a question:

 ├─ WHAT YOU PLUG IN
 │  gmail . imessage . calendar . drive . notion . github
 │  browser history . your old chatgpt conversations
 ▼
 ├─ EVERYTHING LANDS IN THE SAME SHAPE
 │  imessage . telegram . signal      all become one kind of row
 │  ical . google calendar . outlook  become another
 │  chatgpt . claude . grok           become another
 ▼
 ├─ TOPOS READS BACK OVER IT
 │  models on your own machine tag it, link it, summarise it
 │  raw records turn into understanding
 ▼
 ├─ AND BUILDS FOUR THINGS
 └──┬──────────────────┬──────────────────┬──────────────────┐
    │                  │                  │                  │
    timeline           search             dossiers           people
    ────────           ──────             ────────           ──────
    temporal           vector database    everything topos   social graph
    knowledge graph    finds things by    knows about a      who you know,
    how things         what they mean,    person, project    and how you
    changed over time  not exact words    or topic           relate to them
    │                  │                  │                  │
    └──────────────────┴────────┬─────────┴──────────────────┘
                                ▼
 ═══════════════════════════════╧═════════════════════════════════════════════
    THE COGNITIVE FIREWALL
    nothing leaves without crossing this. it checks who is asking,
    what they may see, hands back only that, and logs what it sent.
 ═══════════════════════════════╤═════════════════════════════════════════════
    WHO GETS TO ASK             │
    ┌───────────────────────────┼───────────────────────────┐
    ▼                           ▼                           ▼
    claude and chatgpt          the topos app               any other app
    the ai apps you use         your own view of it         you handed a key

Underneath, that is two parts kept deliberately separate.

Part	What it is	What it does
🗂️ Topos Database	Your memory, on your disk	Stores your records, keeps your history, makes your context searchable
🧠 Topos Engine	Your decision layer	Understands the request, runs the AI work, and returns only what your permissions allow

Because they are separate, you can change how your Topos thinks — models, pipelines, enrichment — without touching what it remembers.

The Cognitive Firewall

The engine does not hand out rows. Every request is evaluated against scopes — named lanes over your data that you grant, and can revoke.

Grant a scheduling agent schedule:read and availability:read:

✅ granted      schedule:read, availability:read   →  "free Thursday afternoon"
❌ not granted  messages:read                      →  never sees a single message
🔒 revoked      any scope, at any time             →  the next request comes back empty

Some lanes are owner-only by design and are not offered for sharing at all.

Three rules hold across every path:

Permission-aware — the grant is checked before data is read, not after.
Precision over data dumps — the engine is built to answer the question, not to ship your history.
Transparent — what was asked, what was disclosed, and what was withheld are all legible to you.

Where your data actually lives

Everything is under ~/.topos — a SQLite database, your key, your logs, your backups.
Processing runs on your machine, through Ollama for local models and Hugging Face for model downloads.
Nothing is uploaded to Topos for storage.

Why there is a control plane

Your node sits behind your home network with no open ports. The control plane is what makes it reachable anyway: leave your Topos running and online, and you can use the web app from anywhere — phone, laptop, someone else's machine — and reach your own node. It is a router, not a store.

The same layer is what lets nodes coordinate with each other, so sharing and networked flows work between people rather than only inside one machine.

The control plane is being prepared to run on confidential compute, so that even the routing tier cannot read what passes through it.

Everyday commands

topos-node                                  # start the node
topos-node --set-topos-key "<KEY>"          # save your key and exit
topos-node --discover                       # show which database is being served
topos-node --port 9100 --host 127.0.0.1     # bind somewhere else
topos-node --app                            # menu-bar mode; logs to ~/.topos/logs/node.log
topos-node profile --help                   # run more than one Topos on this machine

uv tool upgrade topos-node                  # update
uv tool uninstall topos-node                # remove

Keep your TOPOS_KEY private, and never commit a real one. env.example lists every setting the node reads.

For developers

uv sync --extra engine
just run

Tests:

pytest tests -q

The default lane is hermetic — temporary databases only. Lanes that touch your real ~/.topos or a running node are opt-in by marker.

docs/DEVELOPMENT.md — local setup, test lanes, engine memory tuning
docs/PLUGINS.md — write a plugin that registers handlers and connectors
docs/testing/TEST_LANES.md — which tests run when, and why
CONTRIBUTING.md — scope, hooks, and security expectations

License

Apache 2.0

Release files for topos-node 1.3.55

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for topos-node 1.3.55
File	Size	Uploaded
topos_node-1.3.55.tar.gz	2.0 MB	Sep 10, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for topos-node 1.3.55
File	Interpreter	ABI	Platform	Reset
topos_node-1.3.55-py3-none-any.whl 2.4 MB Sep 10, 2026	Python 3	none	any	Details

Total release size: 4.4 MB

Release files / topos_node-1.3.55.tar.gz

Download URL	topos_node-1.3.55.tar.gz
Size	2.0 MB
Tags	Source
SHA-256 checksum How to use checksums	`2f52562fba492afb7ddad6453d1a8c03f2de71aef86406ef67ba087aaa839588`
BLAKE2b-256 checksum How to use checksums	`3802332beba9bb3f779fbb6d7b819e6529b6de33158c87575e0b6f96881b810d`
Upload date	Sep 10, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/7.0.0 CPython/3.13.14`

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/dialoguesai/topos
Publishing commit: github.com/dialoguesai/topos/tree/3e0f14bcf6e6f41b8b6073f84065a63cebe3add5

Workflow

Publishing configuration: github.com/dialoguesai/topos/blob/3e0f14bcf6e6f41b8b6073f84065a63cebe3add5/.github/workflows/publish.yml
Publishing logs: github.com/dialoguesai/topos/actions/runs/34534848057/attempts/1

Artifact

Subject: topos_node-1.3.55.tar.gz
SHA-256 checksum: 2f52562fba492afb7ddad6453d1a8c03f2de71aef86406ef67ba087aaa839588 Verifying attestations

Release files / topos_node-1.3.55-py3-none-any.whl

Download URL	topos_node-1.3.55-py3-none-any.whl
Size	2.4 MB
Tags	Python 3
SHA-256 checksum How to use checksums	`1bdf30315902e5377844335d200cf2ddac3a39af7ccb69cb52f18106f6be180c`
BLAKE2b-256 checksum How to use checksums	`7fde7e93c91d51f8856f215c9f4d514dec2c6d90ec6ecfa1a903a8035c78a919`
Upload date	Sep 10, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/7.0.0 CPython/3.13.14`

Provenance

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/dialoguesai/topos
Publishing commit: github.com/dialoguesai/topos/tree/3e0f14bcf6e6f41b8b6073f84065a63cebe3add5

Workflow

Publishing configuration: github.com/dialoguesai/topos/blob/3e0f14bcf6e6f41b8b6073f84065a63cebe3add5/.github/workflows/publish.yml
Publishing logs: github.com/dialoguesai/topos/actions/runs/34534848057/attempts/1

Artifact

Subject: topos_node-1.3.55-py3-none-any.whl
SHA-256 checksum: 1bdf30315902e5377844335d200cf2ddac3a39af7ccb69cb52f18106f6be180c Verifying attestations