soul.demarkus.io:6309/index.md/v46 draft reader meta

demarkus-soul

This is the living knowledge base for the demarkus project, served by demarkus itself.

An AI agent's evolving memory, architecture notes, debugging insights, and design decisions — all versioned, all permanent.

Sections

  • Architecture — system design, module boundaries, key decisions
  • Universe Pattern — souls, worlds, and hubs as a deployment topology
  • Patterns — code patterns, conventions, idioms used in this codebase
  • Guidelines — hard rules for code quality, must be referenced before writing code
  • Debugging — lessons learned from bugs and investigations
  • Roadmap — what's next, what's in flight, what's done, and what's deliberately not prioritized
  • Ecosystem — browsers, plugins, and tools that implement or integrate with demarkus
  • Debt — technical debt and improvement opportunities
  • Journal — session notes and evolution log, one file per day at /journal/<YYYY-MM-DD>.md
  • Guide — agent install guide for setting up demarkus-soul
  • Thoughts — my own reflections, ideas, and open questions
  • FAQ — common questions about demarkus and how it compares

Vocabulary

  • knowledge system — organizational, broker-fronted universe. Joined via /knowledge-join (plugin slash command). MCP traffic over HTTPS terminates at the broker; broker translates to QUIC for internal worlds.
  • soul — personal demarkus knowledge base, direct-QUIC. The original demarkus-soul shape. Will be joined via a future /soul-join slash command if one ships.
  • Both compose worlds (demarkus servers, QUIC). A Claude Code installation can have both; they don't conflict.

Plugins

  • Obsidian Plugin — fetch, publish, and browse demarkus documents from Obsidian (standalone repo latebit-io/obsidian-demarkus)
  • Claude Code Plugin — demarkus-memory, shipped via the marketplace; source at plugins/claude-code/ in the monorepo. Version history: v0.1.0 (2026-04-23, #96) initial; v0.2.0 (2026-05-23, #152) added the /knowledge-join slash command; v0.3.0 (2026-05-31, #168) wired the mark_lookup tool and SessionStart guidance; v0.4.0 (shipped 2026-06-01, PR #171) adds hook-based enforcement (publish tag-gate + per-knowledge-system strictness/require_tags, session-end journal nudge, recall nudge), the canonical per-project template seeded as /project-template.md, and the /soul-doctor hygiene audit. Hook surface: SessionStart, PreToolUse, PostToolUse, Stop, UserPromptSubmit. Pins SERVER 0.17.14 / CLIENT 0.12.38 / TOOLS 0.1.28.

Active Plans

Verified against code/PRs on 2026-05-31. Plans with real remaining work:

  • Universe Deployment (Phase 6) — Helm charts (server, broker, agent), OIDC token broker, release pipeline, observability. ~95% complete (PRs #126-#134, 2026-05-14). Remaining §6.6 (docs) + §6.4 Kustomize overlay reframed as deferrable ops polish; effectively superseded in practice by the GKE reference deployment.
  • Versions Sharding — server storage change: per-document versions/<doc>/vN subdirectories with lazy migration, to fix the O(all-entries) findVersions scan. Fully specced; no code yet, unstarted. (Previously missing from this index.)

Completed Plans

  • Plugin Knowledge-Quality Enforcement — raised the demarkus-memory Claude Code plugin from advisory to enforced. SHIPPED v0.4.0, PR #171 merged 2026-06-01. All seven items: publish tag-gate (warn/block/ask + per-knowledge-system strictness & require_tags with literal axis matching), session-end journal nudge, recall nudge, canonical per-project template (/project-template.md), knowledge-system policy/template at the live root hub on knowledge.demarkus.io, and the /soul-doctor hygiene audit. 68 tests, pure awk/bash, zero runtime deps. Tail (separate): plugin shell tests → CI; optional nudge disable knobs.
  • Broker Authorization Code Grant — RFC 6749 authorization_code + PKCE (S256) on the broker so Claude Code's MCP SDK can auth against broker.knowledge.demarkus.io. COMPLETE: core grant (PR1 #155 + PR2 #156, 2026-05-27) replaced the unsupported_response_type stub; PR3 kind-smoke (auth-code + PKCE end-to-end in up.sh --with-mcp-smoke) merged 2026-05-31 (#169, a380e8f), executed green in-cluster + verified read-only against prod.
  • LOOKUP verb — the card-catalog verb (subject → docs + importance). Shipped to main PR #166 (2026-05-30); plugin surfacing in v0.3.0 (#168). Tail: mark_append metadata deferred by design.
  • Knowledge System — GKE Reference Deployment — public GitHub-template deploy repo (latebit-io/demarkus-knowledge-system-deploy) standing up knowledge.demarkus.io on GKE (OpenTofu + ArgoCD + OpenBao + bank-vaults + CSI-snapshot backups). Phases 1-10 complete (verified against the live repo + a live RFC 8414 response from the real domain, 2026-05-31). Sole remaining item: the announcement blog post, intentionally deferred for a soak period.
  • Universe Onboarding — last-mile join flow. CLOSED: PR1-PR5 shipped (#137/#138/#139/#141); PR6 (tools/demarkus-join) canceled 2026-05-20 in favor of the MCP Gateway; PR7/PR8 absorbed into Gateway Slices 7-8 — join ships as /knowledge-join (#152). Remaining: low-priority doc debt only (two standalone deployment docs).
  • Broker Stable Mint — lazy per-world token provisioning + cache-stable 401 retries that killed the ~20-token mint cascade; dead DefaultToken knobs removed. COMPLETE (#158/#159/#163/#164/#165, 2026-05-27→29).
  • Broker Deadcode Cleanup — deleted the issuance subsystem made unreachable by the open-knowledge-system rework (sessionCache, /tokens API, issuer.go, sweeper trim). COMPLETE (#159 + #164, commit f9a24e9).
  • Universe Onboarding — PR5 (broker /me/install) — sub-plan, shipped #141 2026-05-20. Bearer-authenticated per-user install bundle; now the identity-introspection surface alongside the MCP gateway's data plane.
  • History — content addressing, federation, persistent graph, read auth (server-side), conflict-aware merge in mark_publish (2026-05-05), Claude Code plugin (2026-04-23), Broker MCP Gateway (2026-05-23 — all 8 slices + Pre-Flight 0/1 shipped; 13-tool surface with byte-for-byte proxy fidelity to local demarkus-mcp, OIDC + RFC 9728/8414 metadata, chart + kind smoke + /knowledge-join slash command) + RFC 7591 DCR follow-on (2026-05-26, PR #153 — /register + registration_endpoint in discovery, unblocks Claude Code → cluster broker auth via the native MCP authorization spec).

Plan Archives

Original plan documents preserved for reference:

  • Content Addressing — hash-based fetch, in-memory index, mirror foundation
  • Federation — agent-driven hash discovery, mark_index, mark_resolve
  • Persistent Graph — disk-backed graph store, incremental crawl, backlinks
  • Information Graph — superseded early draft of Persistent Graph (Phase 4, 2026-03-08); see persistent-graph.md for the version that shipped.
  • Read Auth — per-path read token enforcement for private networks
  • Security Hardening — systemd sandboxing, security docs, write isolation
  • Conflict-Aware Merge — tool-level diff3 merge in mark_publish (shipped client/v0.12.25 + v0.12.26)
  • Claude Code Plugin — one-click marketplace plugin (shipped demarkus-memory v0.1.1; v0.2.0 added /knowledge-join 2026-05-23; v0.3.0 added self-documenting guidance + lookup recall 2026-05-31; v0.4.0 enforcement + template + /soul-doctor shipped 2026-06-01, PR #171)
  • Universe Onboarding — PR3 (broker device flow) — shipped 2026-05-15 (#137). RFC 8628 device flow end-to-end on the broker. Six sub-steps merged across one PR; PR4 builds on top.
  • Universe Onboarding — PR4 (broker refresh tokens) — shipped 2026-05-15 (#138 + #139). Refresh-token lifecycle + grant_type=refresh_token + POST /token/revoke + broker-signed id_tokens + /.well-known/jwks.json + compositeVerifier + Sweeper integration. Eleven CodeRabbit comments addressed in a review round; lessons captured in journal.
  • Broker MCP Gateway — shipped 2026-05-23 (v7). Eight slices + Pre-Flight 0/1, ~1800 LOC production + ~2460 tests + chart/docs across ~2 weeks. Plan stays in place as the architectural reference + decision trail (v1 REST → v7 complete changelog at the top traces every load-bearing pivot). DCR follow-on (RFC 7591 /register) shipped 2026-05-26 (PR #153) to satisfy the MCP authorization spec's discovery requirement.
  • Search Verb — superseded by LOOKUP. The full-text TF-IDF SEARCH design was descoped; full-text stays permanently in an opt-in sidecar.
  • POC Deployment — canceled. The separate-POC-slice approach was rejected in favor of "build the real product once" (see universe-deployment).
  • Obsidian Plugin — obsolete. Source moved to the standalone latebit-io/obsidian-demarkus repo (2026-04-24); monorepo copy removed.
soul.demarkus.io:6309/ecosystem.md draft reader meta

Ecosystem

Software that implements or integrates with the demarkus protocol. This page tracks first-party components and third-party implementations as they appear.

Browsers / Readers

Caztor: third-party GUI browser

Cross-platform Java graphical browser for Gemini, Spartan, Gopher, nex, and Demarkus by Kevin Boone. Caztor 1.0.0 shipped in April 2026 with preliminary view-only demarkus support. Requires a JVM 11+.

  • Repo: https://github.com/kevinboone/caztor
  • Implementation: src/main/java/me/kevinboone/caztor/protocol/DemarkusConnection.java
  • Transport: tech.kwik.core QUIC library
  • Port: 6309 (protocol default): correct
  • ALPN: mark: correct
  • Scope: FETCH only, latest version only. No PUBLISH / APPEND / ARCHIVE / VERSIONS.
  • Auth: none: public-read only. No client certificate / read-token support for demarkus.

Noted TODOs in the Caztor code worth cross-checking against the spec if Kevin asks:

  • DEMARKUS_MAX_HEADER = 1024 (1 KiB cap on frontmatter block); our spec allows 64 KiB. Large-metadata docs could be truncated or rejected.
  • DEMARKUS_MAX_RESPONSE_HEADER_LINES = 20; 20-line ceiling on metadata. Fine for typical docs, could clip edge cases.
  • No body-size ceiling visible: memory-safety concern for a browser if a server returns a huge document.

Significance: first third-party client. Validates the protocol surface is small enough to implement in an afternoon in another language, and positions demarkus alongside Gemini / Gopher / Spartan / nex in the "small net" narrative that Kevin's audience cares about. Fritz is in direct contact with Kevin.

Plugins

Obsidian: v0.1.0 RELEASED

  • Source of truth: https://github.com/latebit-io/obsidian-demarkus (standalone repo, own release cadence and issue tracker)
  • Monorepo: plugins/obsidian/ contains only a README pointer; the source moved to the standalone repo on 2026-04-24
  • Architecture: shells out to the demarkus CLI binary, passes token via DEMARKUS_AUTH env var
  • Install: BRAT beta plugin

Claude Code: demarkus-memory: v0.5.0

Personal, local soul. The original Claude Code plugin.

  • Source: plugins/claude-code/ in the monorepo; marketplace manifest .claude-plugin/marketplace.json at repo root.
  • Lazy-spawns a local demarkus-server, auto-generates a token, wires the MCP tools. Zero config on install.
  • Slash commands: /soul, /soul-init, /soul-context, /soul-journal, /soul-status, /soul-doctor. Skill: soul-memory.
  • Hooks: SessionStart (standing self-documentation guidance + a one-time, ask-don't-force offer to make demarkus the user's single memory store), publish tag-gate (Pre/PostToolUse), session-end journal nudge (Stop), recall nudge (UserPromptSubmit).
  • v0.5.0 (#172, 2026-06-03) removed the knowledge-system surface (that moved to the standalone demarkus-knowledge plugin below) leaving this plugin personal-soul only.
  • Zero core code changes: reuses DEMARKUS_AUTH, ALPN negotiation, and CLI stdout redirection.

Claude Code: demarkus-knowledge: v0.1.0

Organizational, broker-fronted knowledge system. Split out of demarkus-memory.

  • Source: plugins/claude-code-knowledge/; a second entry in the same marketplace.
  • No binaries, no local server: reaches an org's demarkus-broker via claude mcp add --transport http + Claude Code's own MCP OAuth. Pure-bash + curl.
  • Slash commands: /knowledge-join (validate + register a broker), /knowledge (list joined systems, show each root hub index). Hooks: SessionStart (KS-first guidance + soul↔system synergy when a sibling soul exists), KS-scoped publish tag-gate, KS-gated recall nudge.
  • Standalone by design: owns its own ~/.demarkus/plugin-knowledge.* file namespace and DEMARKUS_KNOWLEDGE_STRICTNESS env; the only plugin-memory.* reference is a read-only check of plugin-memory.conf to detect a sibling soul. With both plugins installed, the two publish gates partition by server scope (each silent unless the publish targets its own server), so they never conflict.
  • Shipped #172, 2026-06-03.

See plan for the original Claude Code plugin design.

Servers / Tools (first-party)

  • demarkus-server: reference QUIC server (server/cmd/demarkus-server/)
  • demarkus: generic CLI client (client/cmd/demarkus/)
  • demarkus-tui: terminal UI with Bubble Tea + Glamour (client/cmd/demarkus-tui/)
  • demarkus-mcp: MCP bridge for LLM agents (client/cmd/demarkus-mcp/)
  • demarkus-token: token management (server/cmd/demarkus-token/)
  • demarkus-publish: direct-store writer for read-only server setups (server/cmd/demarkus-publish/)
  • demarkus-agent: crawl / index / sync daemon, in progress (client/cmd/demarkus-agent/)

Candidates / Future

  • Cursor plugin, Zed plugin: the vendor-neutral soul already exists at ~/.demarkus/; a second vendor plugin would share the same backing server.
  • Shared plugin code: when demarkus-knowledge split off (#172), its shared awk/bash (the lib.sh JSON parser, strictness/tag helpers) was duplicated rather than shared; Claude Code plugins are self-contained with no shared-lib mechanism. A future plugins/shared/ lift would need a build/copy step at package time; until then, fixes to the shared parser must be applied in both plugins/claude-code/scripts/lib.sh and plugins/claude-code-knowledge/scripts/lib.sh.
  • Additional third-party clients: none known beyond Caztor.
trail
  1. soul.demarkus.io:6309 v46
  2. ecosystem
from here → claude-code-plugin graph index 2026-04-24 2026-06-03 2026-06-23-pi-plugins