Tylluan

Persistent memory, a knowledge graph, and real tool execution for AI agents — running entirely on your machine.
Sees what others miss, remembers what others forget.

Why Tylluan exists

Most AI memory systems ask you to trust someone else's server with your data: an API key, a subscription, a vendor who can change the terms — or cut your access — tomorrow. Tylluan takes the opposite approach. It's a single Rust binary that gives an AI agent long-term memory, a knowledge graph, and the ability to actually run tools, and none of it leaves your machine unless you explicitly tell it to.

Concretely, that means:

Your data stays yours. Memory lives in a local SQLite database with local embeddings (full semantic search with mxbai-embed-large in server profile; BM25-only zero-download in portable profile; BGE-M3 also supported). There's no cloud round-trip in the critical path, and no proprietary format underneath — you can open the database with any standard SQLite tool.
It works without an internet connection. We've run it on a Raspberry Pi 4 with 12,000 stored memories, federated with three peers over encrypted Noise XK, on a network with no internet access at all.
Nothing here can be taken away from you. MIT licensed, no vendor lock-in, no feature gated behind a subscription.

Agent memory is a crowded space right now — Mem0, Letta, Zep, Cognee, Graphiti, A-MEM, and others all take real, different approaches, and are worth evaluating on their own terms depending on what you need. What Tylluan specifically bets on is running well on modest, offline, or air-gapped hardware, with a compiled binary instead of a Python service you have to keep alive, and a mesh where peers share knowledge directly without a coordinator node in the middle.

Air-gapped by default (fixed 2026-08-23): the kernel used to attempt a STUN request to stun.l.google.com:19302 on every boot regardless of whether federation/mesh was even enabled — real outbound traffic on a host meant to stay fully offline. STUN discovery is now opt-in: [nat] enabled = false by default, gating the whole discovery block. Set enabled = true explicitly if you want NAT traversal for the mesh.

The honest trade-off: several of those other projects have years of community history and production hardening that Tylluan doesn't have yet. ROADMAP.md is where we track what's actually shipped versus what's still planned — we'd rather you find out something isn't ready from us than from a broken deploy.

What it actually does

At its core, Tylluan is a local Rust kernel your agent talks to over MCP. It remembers things across restarts, builds a knowledge graph out of what it learns, and can execute real tools — read files, run git commands, search the web, query a database — on your behalf. If you run more than one instance, they can sync knowledge with each other over an encrypted peer-to-peer mesh, with no central server required.

Design north star: one binary, a different tylluan.toml per environment, the same code everywhere. Memory persists whether or not a network is available; peers sync opportunistically when one shows up, never as a requirement.

Capability	Details
Memory	BM25 + FTS5 + local vector search (1024-dim native `mxbai-embed-large` in server profile / BM25 in portable), fused with RRF, plus LightRAG-style graph traversal (PageRank + degree penalty)
Agent Identity	Declarative agent contracts (`.tylluan/agents.toml`) — role assignment per `agent_id`, no manual wiring
Tools	46 guilds — bash, git, filesystem, docker, code analysis, vision, web search, and more — auto-discovered at startup
Collaboration	Multi-agent channels (Coloquio), shared documents, Bounded Work Contracts
Federation	Peer-to-peer knowledge sync, Noise NK / ChaCha20-Poly1305 encrypted, provenance-tracked, echo-loop safe
Mesh	Kademlia DHT + Gossip dissemination — encrypted with Noise NK once peers know each other's pubkey; a legacy no-discriminator wire path exists for backward compat with older peers and does carry plaintext, see docs/concepts/SECURITY_FEDERATION.md
A2A Protocol	Agent Card discovery + JSON-RPC 2.0 server — interoperates with any Agent2Agent-compliant client (LangGraph, CrewAI, etc.), not just other Tylluan instances
MCP Native	SSE + HTTP Streamable — works with Claude, Cursor, VS Code, LM Studio, any MCP client
GPU Acceleration	Optional DirectML (Windows, any GPU vendor) or CUDA execution provider for local ONNX inference — CPU stays the zero-config default

Full technical capabilities →

Capability	Details
Signal Loop (ADR-011)	`recall_feedback` table tracks which memories actually got used; resolved during `NightConsolidation` via word-overlap against downstream tool calls — a confirmed-useful result also reinforces that memory's lifecycle state (see Memory Lifecycle below), so real usage, not just passing time, keeps it accessible
Coherence Gate	Layered defense on every recall against memory poisoning — deterministic pattern/provenance/drift filters always active, plus an LLM-backed hybrid classifier for genuinely ambiguous cases, currently running in observation mode
Plan Mode (M31-P2)	`tylluan_do(plan=true)` returns the proposed guild/tool/args without executing anything — a dry run you can inspect first
Agent Contracts (M19-P5)	`.tylluan/agents.toml` — per-agent role assignment committed alongside `AGENTS.md`
HNSW Index	Approximate nearest-neighbor search for larger datasets (kicks in above ~12k nodes)
Episodic Memory	Coloquio conversations are automatically stored in the knowledge graph as episodic nodes
Memory Lifecycle (ADR-012)	Memories move through `active → quiet → consolidated → archived` as they age, instead of a binary decay-then-delete — an `archived` memory is never deleted, just excluded from normal recall. Pass `include_archived: true` to `tylluan_recall` to search them anyway; a real usage hit reactivates it back to `active`. Durable summaries (`agent_summary`, `session_digest`) are structurally immune to automatic pruning, not just protected by convention.
Guild Dispatch	Peers discover each other's tool capabilities and can dispatch guild calls remotely over Noise NK, with load/latency-aware routing and a circuit breaker for degraded peers
Encryption	AES-256 at rest via SQLCipher (`--features encryption`) — active by default on binaries built with that feature, off otherwise; every real database goes through the same `open_db()` path, see docs/concepts/SECURITY.md
Query Cache	TTL LRU embedding cache, avoids redundant inference on repeated queries
Complexity Cascade	Heuristic scoring escalates multi-step or ambiguous intents to a coordinator, no LLM required
TRINITY Coordinator	Thinker/Worker/Verifier pattern for tasks that need real synthesis across steps

Dashboard

Tylluan ships with a React dashboard for watching the kernel work.

Production (single binary): served automatically at http://127.0.0.1:47004/ once the kernel is running.
Development: cd dashboard && pnpm dev for the hot-reloading dev server at http://localhost:5173/.

Five tools, nothing hidden behind them

Every MCP client that connects to Tylluan sees exactly these five tools — no matter how many guilds are running underneath:

tylluan_do        Route a task to a guild, described in natural language
tylluan_recall    Search long-term memory (hybrid keyword + vector) or an agent's persona
                  (pass include_archived: true to also search lifecycle-archived memories)
tylluan_remember  Store knowledge, or update an agent's persona persistently
tylluan_think     Reason over the knowledge graph
tylluan_graph     Direct graph operations — triples, paths, PageRank

That's deliberate. Whatever guild ends up doing the work — git, vision, a database query — the client only ever sees this one clean interface.

How well does retrieval actually work?

These numbers are from v0.12.0 (2026-07-05), measured with BGE-M3 — the model Tylluan used at the time, not the current default. The kernel has since moved to mxbai-embed-large (2026-09-30) as its default embedding model. We have not re-run LongMemEval-S against the new default yet, so treat the table below as a historical baseline for the retrieval architecture (BM25+vector+RRF+graph), not a live claim about today's exact numbers. Re-running this benchmark against the current default is open work — see ROADMAP.md.

We evaluated on LongMemEval-S (50 human-authored questions covering episodic memory, multi-hop reasoning, and temporal questions), using real BGE-M3 embeddings on CPU — no simulated numbers:

Metric	Value	Backend
Recall@5	82%	BGE-M3 + BM25 + RRF
Recall@10	90%	BGE-M3 + BM25 + RRF
Recall@1	46%	BGE-M3 + BM25 + RRF
MRR / R-Precision	0.46	BGE-M3 + BM25 + RRF
Latency p50	12.9 ms	CPU, no GPU

Note: LongMemEval-S tests single-needle retrieval ($R=1$ ground-truth session per query), for which Recall@K and MRR / R-Precision are the standard IR metrics (unnormalized Precision@5 is mathematically bounded by $\frac{1}{5} = 20.0%$, where 82% Recall yields an expected Precision@5 of 16.4%).

For comparison, a synthetic corpus of short descriptions only reaches 50% Recall@5 — real human queries actually do better, which tells us the pipeline degrades gracefully rather than overfitting to easy cases. Full results: benchmarks/longmemeval_v0.12.0.json.

If you're on modest hardware

Three profiles trade retrieval quality for footprint — pick based on what you're running on:

Profile	Model	Download	RAM	R@5*	R@10*	Latency p50*
`portable`	BM25 only	0 MB	~30 MB	38%	42%	0.4 ms
`clinic`	BGE-Small (384d)	~100 MB	~300 MB	61%	68%	3.2 ms
`server`	mxbai-embed-large (1024d)	unverified	unverified	82%	90%	12.9 ms

*server row's R@5/R@10/latency are the BGE-M3 numbers above, not yet re-measured against the current default (mxbai-embed-large) — see the note above. portable/clinic are unaffected by the default-model change.

portable is the default profile installed by install.sh/install.ps1 (zero downloads, instant boot, ideal for Raspberry Pi or offline deployments); clinic suits a RAM-constrained laptop; server is for a desktop or server where full semantic retrieval quality is the priority.

Agent skills

Once connected, an agent can call any guild through tylluan_do just by describing what it wants:

Skill	Example
Run code	"run this Python script and return the output"
Web search	"search for the latest Rust async patterns"
Vision	"describe what's in this screenshot"
Git	"show me the last 10 commits in this repo"
Docker	"list running containers and their memory usage"
Database	"query the SQLite database at ./data.db"
PDF	"extract the key points from this paper"
Deep research	"research and summarize the state of MCP tooling in 2026"

Does routing need an LLM call to the cloud?

No — routing is 100% local, and no LLM sits in that path.

When you call tylluan_do("search for Rust async patterns"), the kernel embeds the intent with the local embedding model (mxbai-embed-large in server profile, local ONNX, CPU — or falls back to keyword scoring in portable profile where embedding_model = "none"), scores it against every guild's description, escalates to a coordinator if the intent looks multi-step or ambiguous, and returns the best match with structured arguments. No HTTP call leaves your machine, no API key required — the escalation logic is pure heuristics running in-process on your CPU.

Two things worth not conflating here:

Embeddings are always in the path. Every routing decision and every memory search runs through a local neural network — that's not optional, and it's not a generative LLM.
Generative LLM inference is optional and never in the routing hot path. Tylluan can run one internally via llama.cpp + GGUF (auto-downloads a precompiled binary, no external service needed) for specific, non-blocking uses — an offline evaluation judge, and a calibrated second opinion on memory candidates already flagged by the cheaper deterministic filters. You can also point it at an Ollama, LM Studio, or llama.cpp instance you already have running — it detects a live backend before starting its own.

So "no cloud required" is the real invariant here. "No LLM at all" was never quite accurate for the embedding layer, and it isn't for the optional generative layer either — what stays true is that nothing in Tylluan depends on a cloud service to function.

CI

1076 tests across Rust kernel (lib), tylluan-link, and tylluan-fsrs — all green. Every push runs Rust build + test, clippy, cargo-deny (bans, licenses, advisories), Python lint + test, a dashboard build, and the security audit suite. Details in STATUS.md and .github/workflows/ci.yml.

Quick Start

Setup takes under a minute. The automated installer configures the portable profile by default (BM25-only, zero downloads, instant boot on any hardware). You can upgrade to full semantic search (mxbai-embed-large) at any time with tylluan-cli install --profile server or tylluan start --setup (which auto-detects your RAM and GPU). The kernel probes whether ONNX Runtime is actually loadable before ever calling into it (fixed 2026-08-23, verified live in CI via a dedicated no-ONNX boot smoke test) — if it isn't present, the reranker is skipped and the kernel falls back to BM25-only, rather than panicking.

Supported platforms:

Platform	Binary
Linux x86_64	`tylluan-x86_64-unknown-linux-gnu.tar.gz`
Linux ARM64 (Raspberry Pi 4+)	`tylluan-aarch64-unknown-linux-gnu.tar.gz`
macOS Apple Silicon	`tylluan-aarch64-apple-darwin.tar.gz`
Windows x86_64	`tylluan-x86_64-pc-windows-msvc.tar.gz`

1 — Install

No Rust, Python, or Node needed to run the kernel binary and use it as MCP memory. Running the 46 guilds via tylluan_do (bash, filesystem, scheduler, etc.) requires Python 3.12 + FastMCP separately — without them, those guilds crash-loop and /api/v1/doctor reports degraded (verified 2026-08-22).

# Linux / macOS
curl -fsSL https://raw.githubusercontent.com/Forja-orca/tylluan/main/install.sh | sh

# Windows (PowerShell)
irm https://raw.githubusercontent.com/Forja-orca/tylluan/main/install.ps1 | iex

This drops tylluan-nexus and tylluan-cli into ~/.tylluan/bin/ and adds them to your PATH. Open a new terminal before continuing so the PATH change takes effect.

2 — Start

The installer starts the kernel automatically. If you need to start it manually:

tylluan-cli start

It boots instantly in portable mode (BM25-only, zero downloads):

✅ Tylluan v0.17.0 running at http://127.0.0.1:47004

Check it's actually up:

curl -s http://127.0.0.1:47004/health

Tip

Upgrading to semantic search (vector embeddings):

Auto-detect hardware: tylluan start --setup (probes RAM/GPU and writes optimal profile to tylluan.toml)
Full semantic (1024d): tylluan-cli install --profile server (downloads mxbai-embed-large, ~670 MB)
Lightweight semantic (384d): tylluan-cli install --profile clinic (downloads bge-small, ~67 MB)

Auth: a bearer token is generated automatically at .tylluan-token on first boot. Dev mode (--dev) skips auth entirely — only use that on a network you fully control.

3 — Connect your agent

{ "mcpServers": { "tylluan": { "type": "sse", "url": "http://127.0.0.1:47004/sse" } } }

Client	Where
Claude Code	`claude mcp add --transport sse tylluan http://127.0.0.1:47004/sse`
Claude Desktop	`claude_desktop_config.json`
Cursor	`~/.cursor/mcp.json`
VS Code	`.vscode/mcp.json` in your workspace

Use 127.0.0.1, not localhost. On Windows, localhost resolves to IPv6 first and can silently miss the kernel.

4 — Try it

export TYLLUAN_TOKEN=$(cat .tylluan-token)

# Store a memory
curl -X POST http://127.0.0.1:47004/api/v1/memory/write \
  -H "Authorization: Bearer $TYLLUAN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"content": "Tylluan is running local graph RAG."}'

# Retrieve it
curl "http://127.0.0.1:47004/api/v1/memory/search?q=How+does+Tylluan+query+graphs" \
  -H "Authorization: Bearer $TYLLUAN_TOKEN"

PowerShell equivalent (Windows)

$env:TYLLUAN_TOKEN = Get-Content .tylluan-token

⚠️ This is research software. Tylluan runs real code on your machine. It's a research lab, not a hardened enterprise product — read DISCLAIMER.md before you put anything sensitive near it.

Going further

Topic	Guide
Configuration, auth, troubleshooting	docs/getting-started/QUICKSTART.md
Python guilds (46 tools)	guilds/README.md
Build from source	docs/getting-started/QUICKSTART.md#build-from-source
CLI reference	`tylluan-cli --help`
Installation profiles	`tylluan-cli install --profile=portable`

Where things stand — v0.17.0

This release adopts the MCP 2026-07-28 spec end to end (stateless core, Tasks, real MCP Apps manifests) and closes an 8-phase push to make Tylluan itself an agent's continuity, trust, and action layer — self-documenting guild contracts, unified bootstrap/resume, evidence-backed memory, a Trust Console for runtime/code drift, and a first real dataset circuit turning CoherenceGate's LLM judge decisions into structured, ground-truth-labeled examples. Three real bugs were found live and fixed the same way as always: root cause first, then a regression test, then verified against the live kernel — including a long-standing SSE-mode hang traced to a header-forwarding bug and confirmed fixed by the affected client itself.

Milestone	Description	Status
MCP 2026-07-28 adoption (M39)	Stateless core wired end-to-end and verified live with curl, Tasks with closed-state guards, real MCP Apps manifests (`ui://tylluan/knowledge-graph-canvas`) replacing a bare capability flag	✅
Continuity/Trust/Action layer (M40)	8 phases: self-documenting guild contracts, unified `agent_bootstrap`/resume, full plan→act→verify→undo cycle, evidence/provenance on memory, Trust Console drift detection, concurrency test suite, near-invisible setup	✅
CoherenceGate → dataset circuit	Structured A/B examples (gate vs LLM judge) with real post-hoc ground truth from the existing Signal Loop — phase 1+2 shipped, nothing trained yet by design	✅
Connection audit (v0.15.0)	Full stack re-verified against a live kernel: guild IPC pointed at the wrong port in 5 places, vision inference crashed under real GPU/kernel contention (fixed by forcing CPU after root-causing a Windows driver timeout), silent writes bypassing the embedding pipeline, dashboard panels showing stale or fabricated data	✅
Mesh encryption (v0.15.0)	Production gossip loop now encrypts with Noise NK once a peer's public key has propagated, with a config-gated fallback for first contact — previously sent entirely in the clear despite the crypto layer existing and being tested	✅
Guild registry completeness (v0.15.0)	13 additional guilds activated via `[guilds.v2]`, plus a structural test that fails CI if a guild is ever registered in the catalog but unreachable at runtime — this exact class of bug had shipped silently twice before	✅
CoherenceGate Layer 4 hybrid	Deterministic trigger zones + an LLM classifier for genuinely ambiguous cases, now wired into the live recall path in observation mode (logs its verdict without affecting results yet)	✅
A2A Protocol (M38)	Agent Card + JSON-RPC 2.0 server, interoperable with any Agent2Agent-compliant client	✅
Signal Loop + Coherence Gate (ADR-011)	`recall_feedback` tracks real memory usefulness; layered defense against memory-poisoning attacks on every recall	✅
llama.cpp integration	Real GGUF inference via an auto-downloaded `llama-server` binary, detects and defers to an external Ollama/LM Studio if one is already running	✅
Mesh — DHT, Gossip, Noise (M14)	Kademlia routing, epidemic dissemination, Noise XK/NK transport encryption	✅
Federation (M11)	Peer sync — push/pull/auto-sync, encrypted, provenance-tracked, echo-loop safe	✅
Single binary (M7)	`--features bundled-dashboard` embeds the React dashboard at compile time	✅
v1.0.0	External security audit, community validation, stable API, Docker smoke CI	🔜

For the full history, see CHANGELOG.md. For what's genuinely still open — including a few things this release found and deliberately chose not to rush — see ROADMAP.md.

Architecture

High-Level Overview

flowchart LR
  CLIENTS["Clients & IDEs<br/>Claude Code · Cursor · VS Code · A2A · CLI"]

  subgraph SOVEREIGN["tylluan-nexus (:47004) — Sovereign Core"]
    TOOLS["5 Sovereign Tools<br/>tylluan_do · remember · recall · think · graph"]

    subgraph GOVERN["Cognitive Governance & Routing"]
      SCHED["Cognitive Scheduler<br/>TaskContext · RiskTier · CallerTrust"]
      DECIDER["Decision Fabric (ADR-018)<br/>DecisionProvider · System One"]
      CGATE["CoherenceGate (ADR-011)<br/>L1-L4 Firewall · Signal Loop"]
    end
  end

  subgraph MEMORY["SilvaDB Cognitive Store"]
    SILVA[("SQLite WAL + FTS5 BM25")]
    GRAPH["HNSW (1024d) · PageRank (Penalty) · FSRS-5"]
  end

  subgraph INFER["Local Inference (Zero Cloud)"]
    ONNX["ONNX Runtime Embedded<br/>BGE-M3 (1024d) · Jina Reranker"]
    LLAMA["Local LLM Backend<br/>llama-server GGUF · Ollama"]
  end

  subgraph EXEC["Execution & Agent Collaboration"]
    GUILDS["46 Python Guilds<br/>FastMCP stdio child processes"]
    COLOQUIO["Coloquio & Contracts<br/>Multi-Agent Channels · BWC"]
    WAKE["Stigmergy & Wake-Up (ADR-015)<br/>Insession Cron · Proactive Triggers"]
  end

  subgraph MESH["tylluan-link Distributed Mesh"]
    P2P["P2P Session Pool & Dispatch<br/>Noise NK/XK · ChaCha20-Poly1305"]
    GOSSIP["Gossip Engine & DHT<br/>Anti-Entropy · 256 K-Buckets · STUN"]
  end

  PEERS["Remote Peers<br/>LAN (mDNS) · WAN (DHT)"]

  SPARSE["Research: Sparse Lexical (SPLADE)"]:::future
  POSTCARD["Roadmap: Postcard zero-copy Serde"]:::future

  CLIENTS ==> TOOLS
  TOOLS ==> SCHED
  SCHED ==> DECIDER
  DECIDER ==> GUILDS
  TOOLS ==> CGATE
  CGATE ==> MEMORY
  MEMORY <==> ONNX
  EXEC <==> MEMORY
  DECIDER -.-> LLAMA
  SCHED ==> P2P
  P2P <==> GOSSIP
  GOSSIP ==> PEERS

  ONNX -.-> SPARSE
  MEMORY -.-> POSTCARD

  classDef sovStyle fill:#064e3b,stroke:#34d399,color:#f8fafc,stroke-width:2px;
  classDef govStyle fill:#065f46,stroke:#6ee7b7,color:#f8fafc,stroke-width:1.5px;
  classDef memStyle fill:#04382c,stroke:#34d399,color:#f8fafc,stroke-width:1.5px;
  classDef execStyle fill:#172554,stroke:#60a5fa,color:#f8fafc,stroke-width:1.5px;
  classDef inferStyle fill:#4c1d95,stroke:#c084fc,color:#f8fafc,stroke-width:1.5px;
  classDef meshStyle fill:#082f49,stroke:#38bdf8,color:#f8fafc,stroke-width:1.5px;
  classDef extStyle fill:#0f172a,stroke:#475569,color:#e2e8f0,stroke-width:1.5px;
  classDef future fill:#78350f,stroke:#f59e0b,stroke-width:1.5px,stroke-dasharray:4 4,color:#fef3c7;

  class CLIENTS,PEERS extStyle;
  class TOOLS sovStyle;
  class SCHED,DECIDER,CGATE govStyle;
  class SILVA,GRAPH memStyle;
  class GUILDS,COLOQUIO,WAKE execStyle;
  class ONNX,LLAMA inferStyle;
  class P2P,GOSSIP meshStyle;

  linkStyle 0,1,2,3,4,5 stroke:#34d399,stroke-width:2.5px;
  linkStyle 6 stroke:#c084fc,stroke-width:2px;
  linkStyle 7 stroke:#60a5fa,stroke-width:2px;
  linkStyle 8 stroke:#a855f7,stroke-width:1.5px,stroke-dasharray:3 3;
  linkStyle 9,10,11 stroke:#38bdf8,stroke-width:2.5px;
  linkStyle 12,13 stroke:#f59e0b,stroke-width:1.5px,stroke-dasharray:3 3;

Detailed Layered Topology & Circuits

_{💡 Click the diagram to open full-resolution SVG in a new tab for infinite zoom. For an interactive version (pan/zoom, click a component to see its real source file:line) download architecture_interactive.html and open it locally.}

Stack

Component	Technology
Kernel	Rust (tokio + axum)
Embeddings	mxbai-embed-large (local ONNX, CPU, default) — configurable: bge-m3, bge-small, nomic, none
Reranker	Jina v1 Turbo (local ONNX)
Generative inference	`llama.cpp` (`llama-server`, auto-downloaded), agnostic to an external Ollama/LM Studio if one's already running
Search	BM25 + FTS5 + local vector + RRF hybrid fusion + entity boost
Storage	SQLite WAL + mmap vector index
Federation	SQLite `peers.db` + Noise NK / ChaCha20-Poly1305
Mesh	Kademlia DHT + Gossip + Noise Protocol XK/NK
Guilds	Python (fastmcp)
Dashboard	React + Vite + Tailwind, embedded in the binary

Project structure

tylluan/
├── crates/
│   ├── tylluan-kernel/    Core kernel — memory, routing, guilds, federation, security
│   ├── tylluan-common/    Shared types and errors
│   ├── tylluan-link/      Federation networking — mesh identity, DHT, NAT, mDNS, Gossip, Noise
│   ├── tylluan-cli/       CLI management binary — start / stop / status / install
│   └── tylluan-evals/     Benchmarks — Recall@N, Precision@N, latency percentiles
├── guilds/                Python tool plugins (fastmcp), auto-discovered at startup
├── dashboard/             React dashboard (Vite + Tailwind), embedded in the binary
├── docs/                  Architecture and guides
├── integrations/          MCP client config examples (Claude, Cursor, LM Studio)
└── tests/                 Integration and E2E tests

Federation

Point two or more Tylluan instances at each other and they'll share knowledge securely:

# tylluan.toml
[silva]
sync_interval_ms = 3600000      # the key the auto-sync loop actually reads; 0 = disabled

[federation] auto_sync_interval_secs/auto_sync_mode are read by the federation API handler but not by any background sync loop — [silva] sync_interval_ms is the key the auto-sync loop actually reads. Don't rely on auto_sync_* for automatic sync scheduling (tracked in ROADMAP_O3.md).

# Add a peer
curl -X POST http://127.0.0.1:47004/api/v1/federation/peers \
  -H "Content-Type: application/json" \
  -d '{"name":"node-b","url":"http://192.168.1.10:47004","auth_token":"...","shared_secret":"..."}'

# Push local knowledge to all approved peers
curl -X POST http://127.0.0.1:47004/api/v1/federation/sync

# Pull from a specific peer
curl -X POST "http://127.0.0.1:47004/api/v1/federation/sync/pull?peer=node-b"

# See where a given node's knowledge came from
curl "http://127.0.0.1:47004/api/v1/federation/nodes?source=node-b"

A few invariants that hold regardless of configuration: unapproved peers are never synced, protected nodes are never exported, and anything received from a peer is tagged with federation_source and excluded from further outbound sync by default — so knowledge can't loop endlessly between instances.

Security

Tylluan runs real code on your machine. Before you deploy it anywhere that matters, read:

SECURITY.md — how to report a vulnerability
DISCLAIMER.md — what's on you as the operator
docs/concepts/SECURITY.md — the threat model, mapped to OWASP ASI 2026, including how the Coherence Gate (ADR-011) defends every tylluan_recall against memory-poisoning attacks

A few defaults you shouldn't change without understanding the consequences:

host = "127.0.0.1" — localhost only
dev_mode = false — auth enabled
Never set host = "0.0.0.0" together with dev_mode = true

Examples

# Memory basics: remember, recall, think
python examples/01_memory_basics.py

# Multi-agent communication via Coloquio
python examples/02_multi_agent_coloquio.py

# Knowledge graph exploration
python examples/03_knowledge_graph.py

# Autonomous multi-hop chain — no orchestrator, no API keys
python examples/multi_model_coloquio/run.py

# Bounded Work Contract — 3 agents, shared budget, finite iterations
python examples/bounded_work_contract/run.py

Examples resolve the active kernel port automatically from data/active_port.json or TYLLUAN_PORT (defaults to 47004). Override with --port <PORT> or --kernel http://127.0.0.1:<PORT>.

Full source in examples/.

Documentation

Document	Purpose
CHANGELOG.md	Full version history
ROADMAP.md	Versioned roadmap
STATUS.md	Verified technical state — the source of truth
CONTRIBUTING.md	How to contribute
CODE_OF_CONDUCT.md	Community standards
docs/getting-started/QUICKSTART.md	Detailed setup guide
docs/concepts/FEDERATION_V3.md	Federation protocol spec

How to help

Tylluan is in active pre-production, and the thing it needs most right now is real-world testing on hardware and networks we don't have on hand:

Hardware reports — run it on a Raspberry Pi 4, an old laptop, a mini PC, and share your latency and RAM numbers in GitHub Discussions.
Retrieval quality — try the hybrid search on your own data and tell us honestly whether it found what you expected. Failure reports are at least as useful as success stories here.
Bug reports — if installation or model loading breaks for you, open an issue with the output of tylluan-cli logs attached.

License

MIT — use it, fork it, build on it.

Tylluan (Welsh: owl) — sovereign memory for sovereign agents.

Name		Name	Last commit message	Last commit date
.agents		.agents
.deepeval		.deepeval
.githooks		.githooks
.github		.github
.tylluan		.tylluan
assets		assets
aur		aur
benches		benches
benchmarks		benchmarks
crates		crates
dashboard		dashboard
desktop		desktop
docs-site		docs-site
docs		docs
examples		examples
guilds		guilds
integrations		integrations
packages/tylluan-ui-core		packages/tylluan-ui-core
schemas		schemas
scoop		scoop
scripts		scripts
tests		tests
tools		tools
.dockerignore		.dockerignore
.gitattributes		.gitattributes
.gitignore		.gitignore
AGENTS.md		AGENTS.md
AI_POLICY.md		AI_POLICY.md
AUDIT_REPORT.md		AUDIT_REPORT.md
CHANGELOG.md		CHANGELOG.md
CLAUDE.md		CLAUDE.md
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
Cargo.lock		Cargo.lock
Cargo.toml		Cargo.toml
DISCLAIMER.md		DISCLAIMER.md
Dockerfile		Dockerfile
LICENSE		LICENSE
README.md		README.md
ROADMAP.md		ROADMAP.md
SECURITY.md		SECURITY.md
SPEC.md		SPEC.md
STATUS.md		STATUS.md
deny.toml		deny.toml
dist-workspace.toml		dist-workspace.toml
docker-compose.yml		docker-compose.yml
install.ps1		install.ps1
install.sh		install.sh
models.toml		models.toml
pyproject.toml		pyproject.toml
rust-toolchain.toml		rust-toolchain.toml
tylluan-mcp.bat		tylluan-mcp.bat
tylluan-mcp.sh		tylluan-mcp.sh
tylluan.docker-secondary.toml		tylluan.docker-secondary.toml
tylluan.docker.toml		tylluan.docker.toml
tylluan.example.toml		tylluan.example.toml

Navigation Menu

Repository navigation

About

Repository files navigation

Tylluan

Why Tylluan exists

What it actually does

Dashboard

Five tools, nothing hidden behind them

How well does retrieval actually work?

If you're on modest hardware

Agent skills

Does routing need an LLM call to the cloud?

CI

Quick Start

1 — Install

2 — Start

3 — Connect your agent

4 — Try it

Going further

Where things stand — v0.17.0

Architecture

High-Level Overview

Detailed Layered Topology & Circuits

Stack

Project structure

Federation

Security

Examples

Documentation

How to help

License

About

Releases

Packages

Used by

Contributors

Languages

Latest commit

History

Folders and files

Repository files navigation

Tylluan

Why Tylluan exists

What it actually does

Dashboard

Five tools, nothing hidden behind them

How well does retrieval actually work?

If you're on modest hardware

Agent skills

Does routing need an LLM call to the cloud?

CI

Quick Start

1 — Install

2 — Start

3 — Connect your agent

4 — Try it

Going further

Where things stand — v0.17.0

Architecture

High-Level Overview

Detailed Layered Topology & Circuits

Stack

Project structure

Federation

Security

Examples

Documentation

How to help

License

About

Resources

Code of conduct

Contributing

Security policy

Stars

Watchers

Forks

Releases

Packages

Used by

Contributors

Languages