---
created: '2026-05-10'
path: Sources/Homelab
project: trellis-mcp
status: active
tags:
- mcp
- claude-code
- lovebug
type: project-plan
updated: '2026-05-10'
---

## Goal

Build an MCP server (`trellis`) that captures and resumes long-running threads of work across artificial conversation boundaries. The unit is a *thread* — a logical work effort that may span multiple chat sessions over days or weeks. Pause/resume verbs let you switch contexts without losing state.

Solves the "where exactly did we leave the Traefik debugging" problem. Memory is too lossy; chat history finds old conversations but doesn't restore working state. Trellis sits between them: synthesized state per thread, on demand.

## Locked Decisions

**Three-layer model** — keep these separate, none should swallow another's job:
- CLAUDE.md / LOVEBUG.md = instructions (how to behave)
- Trellis threads = record (where we are in the doing)
- Memory / vault = lessons and outcomes (what we learned, what we built)

**Naming** — `trellis`. Garden-themed, fits the brand world, metaphor maps cleanly (persistent structure things grow on, you keep returning to it).

**Deployment** — separate MCP server, not folded into herby-dev. Different scope: herby-dev is your knowledge management, trellis is cross-cutting infrastructure usable from any agent context. Same deployment pattern as herby-dev: Cloudflare Tunnel, FastMCP, Authentik in front. Hostname `trellis.herbylab.dev`.

**Storage** — Postgres on the existing instance. Database `trellis`, schema `trellis`. Schema namespace makes future consolidation into a single database trivial.

**Schema shape** — four tables, append-only events log:
- `threads` — one row per named thread (slug, topic, goal, status, parent_id for forks)
- `tags` — separate table with DB-level normalization (lowercase, dash-separated, regex-checked)
- `thread_tags` — join table
- `events` — append-only log (started, checkpoint, status_change, fork, metadata_change)

Checkpoint payload is freeform markdown. The agent synthesizes whatever shape fits the thread (current state, decisions, open questions, next steps) — structure not enforced at the DB level.

**Tool surface (v1)** — seven tools, all suffixed with `_thread`:
- `start_thread` — creates row, writes `started` event
- `pause_thread` — writes `checkpoint` event, requires state payload
- `resume_thread` — reads thread + latest checkpoint (no write)
- `get_thread` — read-only inspection, optional full event history
- `list_threads` — filtered summary view
- `fork_thread` — new thread row with parent_id, fork event on parent
- `update_thread` — mutates thread fields, writes metadata_change/status_change event

**Lifecycle is prompt-driven** — system does nothing autonomously. No background jobs, no auto-abandon, no reminders. Threads exist and persist until you explicitly act on them.

**Active context lives in the harness, not the DB** — pause is a signal to the harness ("save and switch"); the DB just stores the trail. One active thread at a time in any given chat session is the harness's concern; the DB doesn't care how many threads are in flight.

## Open Items

- [ ] Postgres deployment shape — LXC vs Docker, fresh instance vs reusing existing
- [ ] Migration tooling — Alembic, plain SQL files, or simpler
- [ ] Tunnel + Authentik setup for `trellis.herbylab.dev` (parallels herby-dev work)
- [ ] Server framework — presumably FastMCP + Python to match herby-dev, confirm at build time
- [ ] First-run question: when trellis is operational, the trellis build itself becomes the first thread; paste design state from this project plan as the initial checkpoint

## Phases

### Phase 1 — Infrastructure

- [ ] Postgres instance available with `trellis` database and `trellis` schema
- [ ] Cloudflare Tunnel hostname `trellis.herbylab.dev`
- [ ] Authentik application + provider for trellis
- [ ] Repo `trellis-mcp` scaffolded

### Phase 2 — Schema and migrations

- [ ] Apply v1 schema (threads, tags, thread_tags, events)
- [ ] Verify CHECK constraints (status enum, tag normalization regex)
- [ ] Verify GIN/btree indexes resolve the resume-by-slug hot path

### Phase 3 — Tool implementation

- [ ] `start_thread`, `pause_thread`, `resume_thread` (the core loop)
- [ ] `get_thread`, `list_threads` (read paths)
- [ ] `fork_thread`, `update_thread` (mutation paths)
- [ ] Tag normalization in tool layer with clear errors before DB constraint fires

### Phase 4 — Wire-up and first use

- [ ] Connect from desktop Claude, mobile Claude, Claude Code, Lovebug
- [ ] Bootstrap: file the trellis build itself as the first thread
- [ ] Iterate based on real use — payload shape, missing affordances, etc.

## Notes

**Deferred to v2:**

- Multi-agent / non-Claude support
- Auto-thread for unnamed conversations
- Auto-status changes (abandon after N days, surfacing stale threads, etc.)
- Read patterns beyond resume-by-name: date ranges, full-text search, decision timelines, fork trees
- Fork merging
- Soft delete / archival
- Tag metadata (description, color)
- Transcript path as a real column (Claude Code transcripts at `~/.claude/projects/`)
- A `resumed` event kind if telemetry on resumes proves useful

**Design principles that drove the shape:**

- *Append-only in spirit* — historical information isn't adjusted, only added to. Even fields that look mutable (current state, next steps) are superseded by newer events rather than rewritten. The thread row reflects current state; events tell you how it got there.
- *Coarse event grain* — about session-level state ("we paused here, this is what we knew"), not per-interaction ("decision added"). The unit is the checkpoint, not the keystroke.
- *Pause = save-and-switch action, not a status* — every thread that isn't actively being worked on is implicitly paused. No separate "paused" status needed.
- *Trigger is naming* — short topical Q&A doesn't need a thread. Lifting to trellis happens when you explicitly say "start a thread called X."

**Schema-namespacing rationale** — putting trellis tables in a `trellis` schema (even inside its own database) costs nothing now and makes any future merge into another database a no-op. Connection sets `search_path` so queries don't qualify table names.

**Why two MCPs instead of one** — herby-dev is your knowledge management, scoped to your homelab. Trellis is cross-cutting infrastructure usable from any agent context. Folding them couples unrelated concerns; deployment overhead of a second MCP is low given herby-dev established the pattern.

**Why separate tags table** — preference for normalization upfront. Array column would work for v1 but you know you'll end up at a join table eventually, so start there.