---
title: Seele
scope: 3dmk
type: documentation
subject: seele
group: Systems
status: current
version: "2.1.3"
source: https://3dmk.com/documentation#seele
author: Nick Olson
contact:
  email: 3dmk@3dmk.com
  site: https://3dmk.com
license: CC BY 4.0
license_url: https://creativecommons.org/licenses/by/4.0/
attribution: Nick Olson, 3dmk.com
---

# Seele

Seele is the documentation store for the development environment. It keeps standards, processes, project documents, and knowledge bases outside the conversation. An agent pulls only the nodes that a job needs. That leaves more of a limited context window for the task, and the answer stays tied to the real documentation.

## Role

Seele is the default source for any document, standard, or reference. Agents reach it through Core Model Context Protocol (MCP) tools. A `seele://<id>` reference in a prompt points an agent at one node. The Design and Studio knowledge bases live here too. Each project also keeps its chain of documents here, from current state through planned work.

Two access paths meet at the same data. A deterministic read starts from a known node ID. It walks the graph from there. A search starts from a query. It returns ranked node handles without their content.

## Parts

The `core-seele` service is one Python and FastAPI process. Five internal parts divide the work.

| Part | Job |
|---|---|
| Graph engine | Serves reads from an in-memory copy of the graph |
| Write gate | Validates each batch and writes it to PostgreSQL and the in-memory graph |
| Importer | Splits Markdown files into nodes and edges for the write gate |
| ID minter | Issues 6-character base62 identifiers from a counter |
| Consistency check | Compares the in-memory graph with PostgreSQL |

The write gate enforces three rules. Inline references become edges. Each filename stays unique. Each node has at most one parent. The gate flags an unknown vocabulary value with a warning in place of a refusal. One unresolved reference in an import batch stops the whole batch, so no partial write lands.

## Data

PostgreSQL is the source of truth. Three tables hold current nodes, current edges, and version history. Every write stores a full snapshot of the node and its edges. Those snapshots rebuild any earlier state of the graph.

A node holds an identity, metadata, Markdown content, and an optional embedding vector. Content carries no headings, because the tree of nodes supplies the heading structure. Each node records its token count, so a caller sees the context cost before a read.

Each edge carries one of three relations. The relation sets how a read loads the target node.

| Relation | Meaning | Read behavior |
|---|---|---|
| `hasPart` | A parent holds a child | Loads every descendant |
| `requires` | A node depends on another node | Loads the target, one hop only |
| `references` | A node points to another node | Returns the target ID without content |

Search uses PostgreSQL full-text ranking with optional theme and subject filters. Vector similarity search is deferred.

## Connections

Seele exchanges data with six other systems.

| System | What passes between them |
|---|---|
| Core MCP | The `seele_search`, `seele_read`, `seele_write`, and `seele_import` tools, forwarded by the Core MCP relay |
| PostgreSQL | Nodes, edges, and version records |
| `core-auth` | Access tokens, checked on every call except health checks |
| `core-db` | Schema patches, applied at deploy time |
| Consul | Service registration, and a fresh address lookup for each relay call |
| Vault | Database and service credentials at runtime |