Meridian

Summary

Meridian is a knowledge capture and synthesis system that runs entirely on a single Hetzner VM, processing documents through a fixed three-stage pipeline — capture → raw → wiki — with all client-facing tools acting as thin HTTP wrappers around server-side logic. The central design choice is that curation happens downstream of intake: every source (Fathom meeting transcripts, Obsidian notes, Claude Code sessions, manual CLI submissions) lands in the same capture/ directory, and a Daily Distill agent running at 6 AM applies a two-dimensional quality gate before anything reaches the wiki. Promotion thresholds are adaptive: permissive during bootstrap (fewer than 20 wiki articles) and selective in steady state, which is the mechanism that prevents an empty wiki from staying empty while also preventing a mature wiki from filling with noise. The Compiler's two-pass architecture — Haiku for planning, Sonnet for execution — reflects the same cost-conscious design philosophy that runs through every component.

Current Understanding

Meridian's architecture is built around one governing principle: all intelligence lives on the server, all clients are dumb. This is not an accident — it is an explicit design decision that makes behavior identical across machines, concentrates debugging to a single observable state, and eliminates the class of bugs that arise when client-side logic diverges from server-side expectations ^[1].

The Three-Stage Pipeline

Documents move through exactly three stages: capture/ (intake), raw/ (scored, awaiting promotion decision), and wiki/ (promoted, organized knowledge). Each stage has a distinct responsibility and a distinct agent ^[2].

The separation matters because quality assessment and filing are different cognitive tasks. Conflating them — asking a single agent to simultaneously judge whether a document is worth keeping and where it should live — produces worse results on both dimensions. Meridian avoids this by assigning the Daily Distill agent to the quality gate and the Compiler to the filing decision, with the two never operating on the same document at the same time.

The one exception to the strict three-stage flow is Claude Code sessions, which are also processed via a /debrief endpoint in parallel with the standard pipeline ^[3]. Session transcripts carry structural characteristics — JSONL format, tool-call sequences, extended reasoning chains — that warrant dedicated handling rather than forcing them through the generic intake path.

The Daily Distill Agent and Adaptive Thresholds

The Daily Distill agent runs at 6 AM via n8n schedule and scores every document in raw/ on two dimensions: Relevance (0–10) and Quality (0–10) ^[4].

The threshold logic is the most operationally significant design decision in the pipeline. During bootstrap — defined as fewer than 20 wiki articles — a score of 6+ on both dimensions triggers automatic promotion. Once the wiki reaches steady state (20+ articles), the bar rises: 8+ on both dimensions for automatic promotion, with 6–7 scores routed to a human approval queue rather than rejected outright ^[5].

This adaptive threshold solves a real bootstrapping problem. A wiki with five articles cannot afford to reject borderline content — it needs shape before it can be selective. A wiki with 200 articles can afford to be choosy, and must be, or quality degrades over time. The human approval queue at 6–7 in steady state is the right call: these documents are not clearly bad, but they are not clearly good enough to promote automatically, and a human can resolve the ambiguity in seconds.

The Compiler: Two-Pass Filing

The Compiler operates as a two-pass pipeline. Pass 1 uses Claude Haiku to generate a filing plan — which documents go where, what new directories or topics to create, what existing articles to update. Pass 2 uses Claude Sonnet to execute that plan with 3 concurrent workers ^[6].

The target throughput is 5 documents in under 60 seconds. The model split is deliberate cost optimization: Haiku is fast and cheap for the planning task, which is primarily structural reasoning over existing wiki topology. Sonnet handles execution, where writing quality and contextual judgment matter more. Using Sonnet for both passes would be slower and more expensive without meaningfully improving filing accuracy.

Before every filing decision, the Compiler reads wiki/_index.md to understand the current wiki structure ^[7]. This is the mechanism that prevents the Compiler from creating duplicate topics or filing documents into categories that have already been superseded. A single meeting document may produce multiple wiki artifacts across both client and knowledge directories — the _index.md read ensures those artifacts land in coherent locations relative to what already exists.

Source-of-Truth Files and Configuration Discipline

Two files function as system-wide source of truth: AGENTS.md (wiki schema, directory conventions, filing rules, frontmatter spec) and wiki/_index.md (current wiki structure) ^[8].

All LLM system prompts live in prompts/*.md files, never hardcoded in Python scripts ^[9]. This is the correct architecture for a system that will be tuned over time: prompt changes should not require touching application code, and application code should not contain implicit behavioral assumptions that are invisible to anyone reading the prompts.

wiki/log.md is append-only and records every agent action in the format ## [date] operation | description ^[10]. The append-only constraint is load-bearing — it means the log is a reliable audit trail rather than a mutable state file that could be corrupted by a failed agent run.

Multi-Source Intake

Five capture paths funnel into the same capture/ directory: Fathom meeting transcripts (via webhook → n8n → /capture/fathom), Obsidian notes, Claude Code sessions (via post-session hook POSTing JSONL to /capture/claude-session), manual CLI submission, and direct file drop ^[11].

The design principle here is zero-friction intake. Curation is a downstream problem; capture should never be the bottleneck. All endpoints except /health require bearer token authentication ^[12], which is the minimum viable security posture for a system that accepts arbitrary document content from multiple sources.

The five-agent roster — Daily Distill, Compiler, Debrief, Q&A, Linter — maps cleanly onto the pipeline stages, with each agent owning a discrete responsibility and implemented as a discrete Python script ^[13]. This structure makes individual agents replaceable without touching the rest of the system.

What Works

Adaptive promotion thresholds tied to wiki maturity. The bootstrap/steady-state threshold split directly addresses the cold-start problem that kills most knowledge systems before they develop useful structure. A fixed high threshold would starve an empty wiki; a fixed low threshold would fill a mature wiki with noise. The 6+ bootstrap / 8+ steady-state split, with a human queue at 6–7 in steady state, is the right three-way partition ^[14].

Two-pass compilation with model-appropriate assignment. Using Haiku for planning and Sonnet for execution cuts cost and latency without sacrificing output quality, because the planning task (structural reasoning over wiki topology) does not require Sonnet's writing capability. The 5-documents-in-60-seconds target is achievable with 3 concurrent workers in Pass 2 ^[13].

Single capture/ directory as universal intake. All five capture sources land in the same place, which means the Daily Distill agent has a single queue to process and the pipeline has a single entry point to monitor. Adding a new capture source requires only a new endpoint and a webhook — no changes to downstream agents ^[15].

wiki/_index.md read before every filing decision. This prevents the Compiler from creating structural drift — duplicate topics, orphaned directories, inconsistent naming — across runs. The index read is cheap relative to the filing operation and eliminates an entire class of consistency bugs ^[8].

Prompts in prompts/*.md, not in Python. Behavioral changes to any agent require editing a markdown file, not touching application code. This lowers the barrier to prompt iteration and makes the system's behavioral assumptions visible to anyone who can read a file ^[9].

Append-only wiki/log.md. An append-only log is a reliable audit trail by construction. Every agent action is recorded with date, operation, and description, which makes post-hoc debugging tractable and provides a complete history of wiki evolution ^[10].

All execution on the VM, clients as thin wrappers. Identical behavior across machines, single place to debug, single observable state. The CLI and web interfaces are HTTP clients, not agents — they cannot diverge from server behavior because they contain no behavior of their own ^[16].

Bearer token auth on all non-health endpoints. Minimum viable security for a multi-source intake system. Simple to implement, simple to rotate, and sufficient to prevent unauthorized document injection ^[12].

What Doesn't Work

Fixed promotion thresholds without maturity awareness would fail. A system that applied the steady-state 8+ threshold from day one would reject too much during bootstrap and never develop the wiki structure needed to make later filing decisions coherent. This is the failure mode the adaptive threshold design explicitly avoids — worth naming because it is the obvious simpler implementation ^[17].

Hardcoding prompts in application code. The explicit decision to externalize all prompts to prompts/*.md implies that the alternative — inline prompts in Python — was considered and rejected. Inline prompts make behavioral changes require code deployments, hide assumptions from non-engineers, and make prompt iteration slower ^[9].

Single-pass compilation without a planning step. Asking a single model call to simultaneously decide where documents go and write the resulting wiki content conflates two tasks with different requirements. The two-pass split exists because planning benefits from a fast, cheap model and execution benefits from a more capable one ^[13].

Mutable log files. An append-only constraint on wiki/log.md is only meaningful if it is enforced. A mutable log that agents can overwrite or truncate loses its value as an audit trail the moment any agent run fails mid-write ^[10].

Patterns Across Clients

No client-specific observations exist in the current fragment set — Meridian is the system itself, not a client engagement. The patterns below describe internal system behavior rather than cross-client variation.

Separation of concerns is the dominant architectural pattern. Capture, quality assessment, and filing are handled by distinct agents with distinct models and distinct triggers. This appears in the pipeline stage separation, the two-pass Compiler, and the agent roster design ^[18].

Centralized source-of-truth files prevent configuration drift. AGENTS.md and wiki/_index.md serve as the single authoritative references for schema and structure respectively. Every agent reads from these files rather than maintaining local state, which means updates propagate automatically ^[8].

Zero-friction intake, selective promotion. The system accepts everything at the capture layer and applies judgment downstream. This is the correct ordering — a system that filters at intake loses documents before they can be evaluated; a system that filters at promotion can always revisit the threshold ^[15].

Maturity-aware behavior. The bootstrap/steady-state threshold distinction is the clearest example, but the underlying pattern — system behavior should adapt to system state — likely applies to other components as the wiki grows ^[17].

Cost-conscious model selection. Haiku for planning, Sonnet for execution. The pattern is: use the cheapest model that can do the task adequately, reserve expensive models for tasks where quality is the binding constraint ^[13].

Exceptions and Edge Cases

Claude Code sessions bypass the standard pipeline via /debrief. The general rule is capture → raw → wiki. Claude Code sessions enter through /capture/claude-session and are also processed by the Debrief agent via a separate endpoint. The structural distinctiveness of JSONL session transcripts — tool calls, reasoning chains, extended context — justifies parallel handling rather than forcing them through the generic scoring path ^[3].

A single document may produce multiple wiki artifacts. The general model is one document → one wiki article. Meeting transcripts in particular may produce artifacts in both client directories and knowledge directories simultaneously, because a single meeting can contain both client-specific decisions and generalizable knowledge ^[13].

The human approval queue at 6–7 in steady state is a deliberate exception to full automation. The system is otherwise fully automated, but documents scoring in the 6–7 range in steady state are explicitly routed to human review rather than auto-promoted or auto-rejected. This acknowledges that the boundary between "good enough" and "not good enough" is genuinely ambiguous at that score range ^[14].

/health endpoint requires no authentication. All other endpoints require bearer token auth. The health endpoint exception is standard practice for load balancers and monitoring systems that need to check availability without credentials ^[19].

Evolution and Change

All fragments in the current set share a single date (2026-04-05), which means the observation window captures a snapshot of the system at one point in time rather than its evolution. No historical changes or in-progress transitions are documented in the available evidence.

The adaptive threshold mechanism — bootstrap permissive, steady state selective — implies that the system's behavior will change as the wiki grows past the 20-article threshold. This is a designed-in evolution: the system is expected to become more selective over time without any configuration changes.

The two-pass Compiler architecture with named model assignments (Haiku, Sonnet) will be sensitive to Anthropic's model releases and deprecations. As model capabilities shift, the cost-quality tradeoff that justifies the Haiku/Sonnet split may change, and the model assignments in the pipeline configuration will need to be revisited.

No signals in the current fragments suggest imminent architectural changes. The design decisions documented in meridian-design-decisions.md read as settled choices rather than provisional ones, which suggests the core architecture is stable.

Gaps in Our Understanding

No evidence on Linter agent behavior. The Linter is named in the five-agent roster but not described in any fragment. Its trigger conditions, what it checks, what it does when it finds issues, and how it interacts with the rest of the pipeline are unknown. This matters for understanding the full quality-maintenance loop ^[13].

No evidence on Q&A agent behavior. Same gap as the Linter — named but undescribed. The Q&A agent presumably handles retrieval or question-answering over wiki content, but the mechanism, model, and interface are not documented in the current fragment set ^[13].

No evidence on failure handling. What happens when the Daily Distill agent fails mid-run? When the Compiler crashes after Pass 1 but before Pass 2 completes? When a webhook fires but the receiver is unavailable? The pipeline design is well-documented for the happy path; the failure modes and recovery procedures are not ^[4].

No evidence on the Obsidian capture path mechanics. Fathom and Claude Code capture paths are documented with specific endpoints and webhook configurations. The Obsidian path is mentioned as a source but not described mechanically — it is unclear whether it uses a dedicated endpoint, a file-drop mechanism, or something else ^[15].

No evidence on what happens to documents that score below 6 in steady state. The 8+ auto-promote and 6–7 human-queue paths are documented. Documents scoring below 6 are presumably rejected, but whether they are deleted, archived, or retained in raw/ indefinitely is not specified ^[20].

No evidence on wiki scale behavior. All design decisions are documented for a wiki in early-to-mid growth. How the Compiler's _index.md read scales as the wiki grows to hundreds or thousands of articles — whether it remains fast, whether the index needs to be paginated or summarized — is not addressed ^[8].

Open Questions

What is the Linter agent's scope? Does it check frontmatter validity, internal link integrity, topic duplication, or something else? Understanding this determines whether the Linter is a maintenance tool or a quality gate.

How does the Q&A agent retrieve content? Does it use vector search, full-text search, or direct file reads? The retrieval mechanism determines the latency and accuracy characteristics of any Q&A interface built on top of the wiki.

What is the failure recovery model for mid-pipeline crashes? If the Compiler completes Pass 1 (filing plan) but fails during Pass 2 execution, does it re-run Pass 1 on the next trigger or resume from the existing plan? Idempotency of the pipeline stages is not documented.

How does the bootstrap threshold transition work in practice? Is the 20-article threshold a hard cutover or a gradual transition? If a wiki oscillates around 20 articles (promotions and deletions), does the threshold flip back and forth?

What is the Debrief agent's relationship to the standard pipeline? Claude Code sessions enter via /capture/claude-session and are also processed by Debrief via /debrief. Are these two separate processing paths that produce different outputs, or does Debrief augment the standard pipeline output?

Does the two-dimensional scoring (Relevance + Quality) use a minimum-of-both or average logic? A document scoring 9 on Relevance and 5 on Quality would pass the bootstrap threshold on average but fail on Quality alone. The promotion logic for documents with asymmetric scores is not specified ^[4].

How are prompts/*.md files versioned? If a prompt change degrades output quality, is there a rollback mechanism, or does recovery require manual git revert?

What monitoring exists on the n8n schedule? If the 6 AM Daily Distill trigger fails silently, documents accumulate in raw/ without promotion. Whether there is alerting on missed runs is not documented ^[21].

Related Topics

• Meridian Architecture
• Meridian Capture Pipeline
• Meridian Agents
• Meridian Design Decisions
• Meridian Receiver Api
• Meridian Cli
• Meridian Directory Structure

Sources

Synthesized from 9 Layer 2 articles, spanning 2026-04-05 to 2026-04-05.