Topos Node

Topos Node is your personal AI node that runs on your own device. It helps you process and organize your data locally, then connect to Topos and 3rd-party services with explicit user-controlled access.

• Product: topos.dialogues.ai
• Company: dialogues.ai
• Topos Apps/Sources: sheaf.dialogues.ai

Why Topos Node

• Runs locally on your machine
• Keeps your node data under your control
• Supports source ingestion, local processing, and controlled sharing flows
• Installs as a single command-line tool via uv

How Topos Works (in product terms)

Topos Node has two core parts that work together to give you control:

Your Apps/Data -> Topos Database -> Topos Engine -> Safe Responses

🛡️ Cognitive Firewall (user control first)

The Topos Engine acts as a Cognitive Firewall: it helps ensure only the right information is used and shared.

🤖 Core ML tools in the Engine

Topos Engine uses both local and model-hub paths so users can choose flexibility and control:

Why this split matters

• 🏠 Your data lives in one durable place (Database)
• ⚙️ Intelligence and policy decisions happen in a separate runtime (Engine)
• 🛡️ The Cognitive Firewall model helps protect context while still enabling useful AI actions
• 🔄 You can evolve processing/model strategy without changing your core stored memory

Shared runtime contracts

The shared/ package in this repo is part of the node runtime contract. It contains common schema and filtering definitions used by both API and engine paths.

Architecture notes (where truth lives)

This README is orientation, not the architecture ledger. Prefer:

• As-built / why: sibling topos-research-wiki → 20_ARCHITECTURE/ (As_Built_Node, firewall, query, MCP, graph, …)
• As-is invariants / checks: sibling topos-ops-wiki → 25_SYSTEMS/ (SYS-node, SYS-cognitive-firewall, …)
• Target design: topos-data-wiki (status: target) — do not implement from it without checking as-built

Quick Start

1) Install

uv tool install topos-node

2) Configure

Topos Node requires a TOPOS_KEY.

topos-node --set-topos-key "<YOUR_TOPOS_KEY>"

This stores your key in:

• ~/.topos/.env

Optional:

• TOPOS_CONTROL_PLANE_URL if you need a non-default endpoint

3) Run

topos-node --host 0.0.0.0 --port 9000

4) Verify

curl http://localhost:9000/health

Common Commands

# Start node
topos-node

# Save your TOPOS_KEY for future runs
topos-node --set-topos-key "<YOUR_TOPOS_KEY>"

# Discover available local databases and exit
topos-node --discover

# Use custom database path
topos-node --db-path /path/to/topos.sqlite

# Bind custom host and port
topos-node --host 127.0.0.1 --port 9100

Upgrade or Uninstall

# Upgrade to latest
uv tool upgrade topos-node

# Remove
uv tool uninstall topos-node

Security and Privacy Notes

• Do not commit topos/.env or any real credentials.
• Keep your TOPOS_KEY private.
• Review env.example for available configuration options.

Developing Locally

uv sync --extra engine
just run

Engine memory (local dev)

ML models are cached inside the Engine with LRU eviction. For lighter local runs (especially inside Cursor's integrated terminal), see Engine memory management.

# Default: ENGINE_MAX_RESIDENT_MODELS=3; pipeline flush is automatic
# Override only if needed, e.g. lower RAM: export ENGINE_MAX_RESIDENT_MODELS=2
export PRIVACY_FILTER_DEVICE=cpu

Run tests:

pip install -e ".[dev,engine]"
pytest tests -m "public and not e2e" -q

Plugins

Topos Node supports optional plugins: separate Python packages installed alongside topos-node that register handlers, connectors, or other runtime hooks. The core node does not hardcode plugin names — discovery is entirely via setuptools entry points.

Contract: topos.extensions

Minimal plugin

pyproject.toml:

[project]
name = "my-topos-plugin"
dependencies = ["topos-node[local]"]

[project.entry-points."topos.extensions"]
my_plugin = "my_topos_plugin:register"

my_topos_plugin/__init__.py:

def register() -> None:
    from my_topos_plugin.handlers import example  # noqa: F401 — registers @handles

my_topos_plugin/handlers/example.py:

from typing import Any, Dict, Optional
from topos.core.handlers.registry import handles

@handles("my_message_type")
async def handle_my_message(message: Dict[str, Any]) -> Optional[Dict[str, Any]]:
    return {"status": "ok", "payload": {"received": message.get("type")}}

Install and run

pip install topos-node my-topos-plugin
topos-node

Handlers registered in register() are available to the control-plane WebSocket and local API paths that dispatch through topos.core.handlers.

Starter template

Fork dialoguesai/topos-plugin-template for a working package with tests and CI. It registers a sample plugin_template_ping handler you can copy and rename.

Guidelines

• Use unique message type names (prefix with your project) to avoid colliding with core handlers.
• Keep plugins in separate repositories — do not add proprietary logic to this repo.
• Message types your plugin handles do not need to appear in the public engine protocol snapshot unless the hosted control plane will send them to all nodes.

Contributing

See CONTRIBUTING.md for:

• public vs private test lanes
• where deployment scripts now live
• contribution scope and security expectations

License

Apache License 2.0. See LICENSE.