soul.demarkus.io:6309/index.md/v40 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 v0.2.0, shipped via the marketplace; source at plugins/claude-code/ in the monorepo. v0.2.0 (2026-05-23) adds the /knowledge-join slash command for joining organizational broker-fronted knowledge systems alongside the existing personal-soul flow.

Active Plans

  • LOOKUP verb — add LOOKUP (verb 7) as the card catalog for a world: given a subject, return which docs declare that tag (or match it in the title) and their importance, token-efficiently, as a supplement to the index hub. Two axes — query matches tags + title, filter matches any frontmatter key=value. In-memory catalog (path → tags, importance, title) built on the startup walk + inline updates; markdown table response, no body snippets, read-auth filtered. Server interprets only importance + tags. Full-text/semantic matching stays permanently in an opt-in sidecar. Tracks #113. Draft, pending Fritz review 2026-05-30.
  • Broker Authorization Code Grant — implement RFC 6749 authorization_code + PKCE (S256) on the broker so Claude Code's MCP SDK can auth against broker.knowledge.demarkus.io without pivoting to device flow. Replaces the unsupported_response_type stub at /oauth/authorize. 3 PRs (~3 days). Pending Fritz review 2026-05-26.
  • Knowledge System — GKE Reference Deployment — public, GitHub-template deployment repo (latebit-io/demarkus-knowledge-system-deploy) standing up knowledge.demarkus.io on GKE via OpenTofu + ArgoCD + OpenBao + bank-vaults webhook + restic→GCS backups. 10 phases, Phase 1 (bootstrap state + GCP project) next. Doubles as the canonical working example of a deployed knowledge system.
  • Universe Deployment (Phase 6) — production-grade enterprise k8s deployment: Helm charts (server, broker, agent), OIDC token broker, release pipeline, observability. ~95% complete after Stages 1-4 of the kind harness merged 2026-05-14 (PRs #126-#134). §6.6 (docs) + §6.4 Kustomize overlay remaining.
  • Universe Onboarding — last-mile user-onboarding flow: OIDC device-code auth + broker /me/install + plugin slash commands. PR1-PR4 merged 2026-05-15. PR5 merged 2026-05-20 (#141). PR6 (tools/demarkus-join binary) canceled 2026-05-20 in favor of the MCP Gateway plan (now complete); join flow ships as /knowledge-join (Slice 8, #152, 2026-05-23). PR7/PR8 absorbed into MCP Gateway Slices 7-8.
  • Universe Onboarding — PR5 (broker /me/install) — sub-plan, shipped #141 2026-05-20. Bearer-authenticated per-user install bundle. Stays as the identity-introspection surface alongside the MCP gateway's operational data plane.

Completed Plans

  • 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
  • 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)
  • 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.
trail
  1. soul.demarkus.io:6309 v40