Metadata-Version: 2.4
Name: tessellum
Version: 0.0.1
Summary: Typed atomic notes in a graph — a Zettelkasten that scales. Knowledge construction with Building Blocks, Folgezettel trails, and the Dialectic Knowledge System (DKS).
Project-URL: Homepage, https://github.com/TianpeiLuke/Tessellum
Project-URL: Documentation, https://github.com/TianpeiLuke/Tessellum/tree/main/docs
Project-URL: Repository, https://github.com/TianpeiLuke/Tessellum
Project-URL: Issues, https://github.com/TianpeiLuke/Tessellum/issues
Project-URL: Changelog, https://github.com/TianpeiLuke/Tessellum/blob/main/CHANGELOG.md
Author: Tianpei (Luke) Xie
License: MIT
License-File: LICENSE
Keywords: agent-memory,ai-agent,atomic-notes,building-block,cqrs,dialectic,dks,epistemic,folgezettel,fts5,hybrid-retrieval,knowledge-graph,knowledge-management,llm,mcp,personal-knowledge-management,pkm,rrf,sqlite-vec,zettelkasten
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Education
Classifier: Intended Audience :: Information Technology
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Scientific/Engineering :: Information Analysis
Classifier: Topic :: Software Development :: Documentation
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Text Processing :: Markup :: Markdown
Classifier: Typing :: Typed
Requires-Python: >=3.11
Requires-Dist: click>=8.1
Requires-Dist: fa2
Requires-Dist: igraph
Requires-Dist: jsonschema>=4.0
Requires-Dist: matplotlib
Requires-Dist: networkx
Requires-Dist: numpy
Requires-Dist: pillow
Requires-Dist: pydantic<3.0,>=2.7
Requires-Dist: python-frontmatter>=1.1
Requires-Dist: pyyaml<7.0,>=6.0
Requires-Dist: rank-bm25
Requires-Dist: rich>=13.7
Requires-Dist: sentence-transformers
Requires-Dist: sqlite-vec>=0.1.6
Requires-Dist: tiktoken
Provides-Extra: agent
Requires-Dist: anthropic; extra == 'agent'
Provides-Extra: dev
Requires-Dist: build; extra == 'dev'
Requires-Dist: mypy; extra == 'dev'
Requires-Dist: pytest-asyncio; extra == 'dev'
Requires-Dist: pytest-cov; extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Requires-Dist: ruff; extra == 'dev'
Requires-Dist: twine; extra == 'dev'
Provides-Extra: ingest
Requires-Dist: beautifulsoup4; extra == 'ingest'
Requires-Dist: html2text; extra == 'ingest'
Requires-Dist: pdfplumber; extra == 'ingest'
Requires-Dist: pypdf2; extra == 'ingest'
Requires-Dist: python-docx; extra == 'ingest'
Requires-Dist: python-pptx; extra == 'ingest'
Requires-Dist: watchdog>=4.0; extra == 'ingest'
Provides-Extra: mcp
Requires-Dist: fastapi>=0.115; extra == 'mcp'
Requires-Dist: mcp>=1.0; extra == 'mcp'
Requires-Dist: uvicorn>=0.32; extra == 'mcp'
Provides-Extra: papers
Requires-Dist: pyzotero; extra == 'papers'
Requires-Dist: requests; extra == 'papers'
Description-Content-Type: text/markdown

# 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](CHANGELOG.md).

## 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](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](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

```bash
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](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](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](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`](vault/0_entry_points/entry_master_toc.md). See [DEVELOPING.md](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](LICENSE) — 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
