tessellum 0.0.1

Typed atomic notes in a graph — a Zettelkasten that scales. Knowledge construction with Building Blocks, Folgezettel trails, and the Dialectic Knowledge System (DKS).

Tessellum

Typed atomic notes in a graph — a Zettelkasten that scales.

Knowledge construction for humans and agents, built on six architectural pillars: Zettelkasten, PARA, Building Blocks, Epistemic Functions, Dialectic Knowledge System (DKS), and CQRS.

Tessellum is a knowledge-construction system, not an agent-memory store. The unit of work is a typed atomic note — a tessellum, a small mosaic tile — that carries one epistemic claim. You write tessellae; Tessellum indexes them, retrieves them with hybrid BM25 + vector search, lets you grow Folgezettel trails that record how thinking developed, and runs a closed-loop Dialectic Knowledge System that updates warrants from observed disagreement. The architecture is CQRS: a typed prescriptive substrate (what you author) and a computational descriptive retrieval layer (what queries return) — read-side and write-side cleanly separated.

Status

v0.0.1 — namespace reservation. Repository skeleton + this README. The v0.1 user-facing release ships the engine port + 20 essential skills + 8 BB-type example notes. See CHANGELOG.

The Six Pillars

Pillar	What it gives you
Z — Zettelkasten	Atomic notes, bidirectional links — Luhmann's method that scaled to ~90k connected ideas
PARA — Projects/Areas/Resources/Archives	Tiago Forte's organizational scheme; four-fold structure that survives growth
BB — Building Block	8 typed atomic units with defining epistemic functions (vault/resources/term_dictionary/term_building_block.md)
EF — Epistemic Function	Each BB has a function — claim / refute / observe / synthesize / index
DKS — Dialectic	Closed-loop protocol — arguments attract counters, counters absorbed by syntheses (vault/resources/term_dictionary/term_dialectic_knowledge_system.md)
CQRS — Read/Write Split	System P (typed substrate, prescriptive) ⊥ System D (retrieval, descriptive)

What Tessellum Is Not

	Tessellum
Note app (Obsidian / Notion / Roam)	Tessellum constructs knowledge — typed atomicity, dialectic, CQRS — not just stores it
Agent memory (Mem0 / Letta / palinode)	Tessellum is a typed knowledge system. Memory tools focus on per-session recall; Tessellum focuses on epistemic structure
Knowledge graph (Neo4j / Stardog)	The graph emerges from typed wikilinks and Folgezettel trails. You write atomic markdown, not Cypher
RAG framework (LangChain / LlamaIndex)	Retrieval is hybrid BM25 + vector + PageRank + best-first BFS over a typed graph. Notes are typed atoms, not opaque chunks

Quick Start

pip install tessellum
tessellum init ~/my-vault
tessellum capture term "PageRank" --as concept
tessellum index --vault ~/my-vault
tessellum search "graph traversal"
tessellum answer "what is the difference between PageRank and PPR?"

Architecture

                    ┌──────────────────────────────────────┐
                    │  vault/  (markdown + YAML)           │
                    │  System P — typed substrate          │
                    │   • 8 BB types × ~80 sub-kinds       │
                    │   • PARA categories                  │
                    │   • Folgezettel trails               │
                    └──────────────────┬───────────────────┘
                                       │ indexed
                                       ▼
                    ┌──────────────────────────────────────┐
                    │  data/databases/   (one .db file)    │
                    │  SQLite + sqlite-vec + FTS5          │
                    └──────────────────┬───────────────────┘
                                       │ queried
                                       ▼
                    ┌──────────────────────────────────────┐
                    │  src/tessellum/retrieval/            │
                    │  System D — descriptive retrieval    │
                    │   • Hybrid BM25 + vector via RRF     │
                    │   • PPR / Best-First BFS             │
                    │   • BB-aware re-ranking              │
                    └──────────────────┬───────────────────┘
                                       │ exposed
                                       ▼
                    ┌──────────────────────────────────────┐
                    │  Interfaces                          │
                    │   • CLI: `tessellum search/answer`   │
                    │   • MCP server (Claude / Cursor / …) │
                    │   • Composer pipeline (typed-contract│
                    │     knowledge auto-digestion)        │
                    └──────────────────────────────────────┘

See vault/resources/analysis_thoughts/thought_six_pillars_architecture.md for the full pillar-by-pillar deep dive.

The Building Block Ontology

Every tessellum has a building_block field in YAML frontmatter — one of 8 typed roles, each with a defining epistemic function. The directed edges between types form a 10-edge epistemic ontology that drives the Dialectic Knowledge System. See vault/resources/term_dictionary/term_building_block.md.

Folgezettel Trails

Wikilinks tell you what's related. Folgezettel trails tell you how thinking developed — argument → counter → response → reframe → synthesis, encoded in trail IDs (7 → 7a → 7a1 → 7a1a). See vault/resources/term_dictionary/term_folgezettel.md.

Project Structure

Tessellum/
├── src/tessellum/      Python code only (composer / retrieval / indexer / cli / mcp)
├── vault/              Knowledge vault — Tessellum dogfoods itself; public docs LIVE here
│   ├── 0_entry_points/ Master TOC + per-surface entries (skills, FZ trails, code, …)
│   ├── resources/
│   │   ├── term_dictionary/   Conceptual primer (BB, FZ, DKS, CQRS, Z, PARA, …)
│   │   ├── how_to/            How-to guides (getting started, note format, agent integration)
│   │   ├── analysis_thoughts/ Architecture arguments + FZ trails
│   │   └── skills/            Skill canonical bodies (single source of truth)
│   └── examples/        One worked example per Building Block type
├── inbox/              User drop zone (papers, SOPs, plans, drafts)
├── data/               Derived artifacts (DBs, indexes — gitignored, regenerable)
├── experiments/        Experiment outputs
├── scripts/            Operational utilities
├── tests/              Test suite
├── .claude/skills/     Claude Code skill thin-headers (point at vault/resources/skills/)
└── .kiro/skills/       Kiro skill thin-headers (point at vault/resources/skills/)

No separate docs/ directory — Tessellum's own documentation IS a typed-knowledge vault. Start at vault/0_entry_points/entry_master_toc.md. See DEVELOPING.md for the rationale.

Compared to Adjacent Tools

	Tessellum	Obsidian	palinode	Mem0
Typed atomic notes (8 BB types)	✅	—	partial (5)	—
Folgezettel trails	✅	manual	—	—
Dialectic / counters as first-class	✅	—	—	—
CQRS read/write split	✅	—	—	—
Hybrid BM25 + vector retrieval	✅	plugin	✅	proprietary
MCP server	v0.1	plugin	✅	—
Closed-loop dialectic compaction	✅ (DKS)	—	partial (5 ops)	—
Knowledge-construction (vs storage)	✅	—	—	—

License

MIT — use freely, contribute back.

Origin

Tessellum is the public release of the typed-knowledge system originally developed inside Amazon's buyer-abuse-prevention research vault. The architecture (BB ontology, Folgezettel trails, DKS protocol, CQRS thesis) was discovered through ~14 long-running Folgezettel research trails over 2024–2026.

The name Tessellum is Latin: small mosaic tile — the atomic typed unit. A vault is the mosaic.

Acknowledgments

• The Zettelkasten community (especially Sascha Fast at zettelkasten.de) for the Building Block taxonomy this work builds on
• Niklas Luhmann for proving typed atomic notes scale to ~90k connected ideas
• Tiago Forte for the PARA scheme
• The Phasespace-Labs / palinode project for independently validating the SQLite + sqlite-vec + FTS5 + RRF stack
• CQRS architects (Greg Young, Udi Dahan) for the read/write split applied here to typed knowledge