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

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).

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).

FAQ

What are the advantages of using this over git for an AI brain?

Git is designed for code merging. Demarkus is designed for knowledge.

Git solves branch/merge problems you don't have with documentation. For a knowledge base, those features create friction. Demarkus eliminates it.

Every write creates a new immutable version (v1, v2, v3). No branching, no divergent histories, no reconciliation needed. Two people documenting the same thing in git means a merge conflict. In demarkus, it just works.

Instead of "where is the context for X?", you can fetch by content hash across multiple servers without central coordination. Federation handles the rest.

The persistent graph enables backlinks: "show me everything that references this topic." Git gives you git grep and hope. Demarkus builds a navigable graph that agents traverse through MCP tools and humans browse in the TUI.

Git assumes one repo everyone pulls from. Demarkus assumes many servers that discover each other via content hashes. Your docs, someone else's docs, all connected.

The AI-brain problem

The challenge is making expert knowledge available to everyone. Grouped by domain, by discipline, by whatever makes sense. Not locked in one repo, not scattered across wikis.

Demarkus solves this with structure and links. Each expert domain gets its own evolving docs, linked to related context. You find them via backlinks and graph traversal, not file paths that move.

Backlinks answer real questions: what else references this domain? What decisions were made here? What changed last time? You can fetch by content hash: ask "show me everything about X" without knowing where it lives. And federation means someone on another team documents a domain you depend on, and you discover it automatically through the graph.

Git can't do this. It's one repo, text search, and merge conflicts. Demarkus is a connected graph of knowledge that grows as people write.