Metadata-Version: 2.4
Name: zttl
Version: 0.2.5
License-File: LICENSE
Summary: Zettelkasten note management on frontmattered markdown
Home-Page: https://github.com/cjohnhanson/zettel
License-Expression: MIT
Requires-Python: >=3.9
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM

# zettel

Zettel is a zettelkasten knowledge base for code repositories. It keeps atomic
notes as markdown files in `.zettel/`. Notes link to each other through YAML
frontmatter and inline `[[id]]` references. Git tracks the notes next to the
code, and no external service holds them.

During research an agent reads code, traces bugs, and compares options. That
work is usually lost at the end of the session. Zettel writes it down as notes
labeled with their provenance: who produced each piece of text, and what kind
of claim it makes. A human reviews the agent content later and approves what
they stand behind.

## Install

The package is `zttl`, because `zettel` was taken on every registry. On
npm it is `@cjohnhanson/zttl`, because the registry refuses `zttl` as
too close to names it already holds. The command is `zettel`, and both
names install together.

```sh
cargo install --locked zttl
brew install cjohnhanson/tap/zettel
uv tool install zttl
npm install -g @cjohnhanson/zttl
```

`cargo install` builds from source. It needs Rust 1.88 and a C
compiler. The other three carry a prebuilt binary for macOS and Linux,
x86-64 and arm64, published by a tagged release.

To build the unreleased `main` branch:

```sh
cargo install --locked --git https://github.com/cjohnhanson/zettel
```

Or run it without installing:

```sh
uvx zttl read
npx @cjohnhanson/zttl read
```

A release also carries prebuilt archives and a `.deb`, on the [releases
page](https://github.com/cjohnhanson/zettel/releases). Each archive
holds the binary and the man page. Install a `.deb` with `dpkg -i`: it
is a file, not a repository, so `apt-get install` does not reach it.

Check the install with `zettel --version`.

## Usage

```sh
zettel init                                                  # run inside a git repo
zettel note create "Connection pooling causes stale reads" \
  --tag bug,postgres --body "Pool reuses sockets after failover..."
zettel note list --tag postgres
zettel search "stale read"
zettel context a3f2 --depth 2
```

Every command:

```sh
zettel init                                  # make .zettel/ in a git repo
zettel note create "Title" -t a,b -p agent:summary   # make a note; set tags and provenance
zettel note list [--tag t] [--provenance p]  # list the notes
zettel note list --unreviewed                # list the notes with unreviewed agent content
zettel note show <id>                        # show the full content of one note
zettel note edit <id> --add-link b7c1        # link one note to another
zettel note review <id> [--approve all]      # list provenance spans; approve agent content
zettel note delete <id>                      # remove a note
zettel read [--tag t] [--provenance p]       # show the content of the matching notes/spans
zettel search <pattern>                      # search all notes with a regex
zettel backlinks <id>                        # show the notes that link to this note
zettel context <id> --depth N                # show the notes within N hops
zettel orphans                               # show the notes with no links
zettel store list                            # show this store and the stores it declares
zettel store sync                            # fetch the declared remote stores into the cache
zettel store root [<path>]                   # show or set the store that reads fall back to
zettel check                                 # check for broken links and invalid provenance
zettel migrate                               # convert pre-provenance notes (status keys)
zettel stats                                 # show counts, tag distribution, and connectivity
zettel serve [--bind ADDR] [--access MODE]   # serve this knowledge base over MCP
zettel docs [topic]                          # show the bundled documentation
zettel prime                                 # print what zettel is, for an agent's context
```

## How it works

Each note is one markdown file with YAML frontmatter:

```markdown
---
title: Connection pooling causes stale reads
tags: [bug, postgres]
links: [b7c1]
provenance: agent:summary
---

After failover, the pool reuses sockets bound to the old primary.
See [[b7c1]] for the workaround.

<!-- prov agent:inference -->
The 2026-08-02 retry storm probably started here.
<!-- /prov -->

<!-- prov human:cody -->
Confirmed with the infra team.
<!-- /prov -->
```

The note ID is the filename stem, so the frontmatter does not repeat
it. Zettel keeps the notes in one flat `.zettel/` directory:

```
.zettel/
  a3f2-connection-pooling-causes-stale-reads.md
  b7c1-workaround-force-new-connection.md
```

Notes connect through the frontmatter `links` field and inline `[[id]]`
references. Zettel walks the note graph. It computes backlinks, finds the
orphan notes, shows the neighborhood of a note, and checks for broken links.

Every piece of text has a provenance. The frontmatter `provenance:` key sets
the note default; a `<!-- prov ... -->` marker overrides it for one section.
The origins:

- `human[:name]` — a person wrote it.
- `agent[:kind]` — an agent wrote it: a `summary` of sources, an `index`,
  or an `inference` (a new claim not present in the sources).
- `citation[:source]` — quoted verbatim; the source is a note ID or a
  `src=<url>` attribute. A citation of a note is a link-graph edge.
- No provenance means unknown. Unknown is never upgraded to human, so an
  agent that forgets the label cannot mint human-authored text.

A human approves agent content with `zettel note review <id> --approve`,
which writes a `reviewed=` stamp. A later reader filters by all of this:
`zettel read --provenance human,citation,reviewed` returns only the text a
human wrote, quoted, or vouched for. Nothing verifies a label against what
actually wrote the span. Reading the files directly gives the same labels
and the same caveat.

## Composed stores

A knowledge base can link into others. Declare them in `stores.yml`:

```yaml
format: 2
stores:
  - alias: project
    path: ../project                            # this machine
  - alias: handbook
    git: https://example.com/org/handbook       # a git repository
  - alias: archive
    blob: https://example.com/notes             # an https prefix with an index.txt
```

`zettel store sync` fetches the remote stores into a local cache. It is
the only command that reaches the network.

A reference then names the store. Write `[[project:a3f2]]` in a body,
`project:a3f2` in `links:`, or `citation:project:a3f2` in a provenance
marker. A reference with no alias stays local.

The declarations set the direction. A personal knowledge base declares
the repositories that it annotates. A repository does not declare the
personal knowledge base. It cannot: the target does not exist for the
other users who clone the repository. Two repositories can declare each
other, because each one is equally reachable.

Each command runs from one store. It reads that store and the stores
that the store declares. Thus one note has different backlinks in
different stores. Dependency stores are read-only.

## Serving over MCP

`zettel serve` offers the same knowledge base to a Model Context
Protocol client. The library answers both interfaces, so the server
returns what the CLI returns.

```sh
zettel serve                        # speak MCP on stdin and stdout
zettel serve --bind 127.0.0.1:7431  # serve over HTTP for a client that connects
zettel serve --access read-write    # also allow note creation
```

The server is read-only by default. With `--access read-write` it
stamps every note it writes as agent-written. It refuses any other
provenance, and it never exposes approval. A served store has no
authentication: bind it to `127.0.0.1`, or put a proxy that
authenticates in front of it.

## Documentation

- [What is Zettel?](docs/what-is-zettel.md) — the zettelkasten model, the note format, the workflow
- [Getting started](docs/getting-started.md) — a walkthrough of the first notes
- [CLI reference](docs/cli-reference.md) — the complete command documentation

Run `zettel docs` to read the same documentation from the binary.

## Related

- [tisket](https://github.com/cjohnhanson/tisket) — issue tracker. Markdown issues with YAML frontmatter, in the repository
- [almanac](https://github.com/cjohnhanson/almanac) — agent skill index, over pluggable sources
- [gaff](https://github.com/cjohnhanson/gaff) — context-lifecycle handler for coding agents
- [missouri](https://github.com/cjohnhanson/missouri) — end-to-end tests as directed graphs of filesystem states
- [mdstore](https://github.com/cjohnhanson/mdstore) — the frontmattered markdown library zettel stores notes with

## License

MIT.

