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

Plugins

Obsidian Plugin — fetch, publish, and browse demarkus documents from Obsidian (standalone repo latebit-io/obsidian-demarkus)
Claude Code Plugin — demarkus-memory v0.1.1, shipped via the marketplace; source at plugins/claude-code/ in the monorepo

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 + tools/demarkus-join binary + Claude Code plugin slash commands (/soul-join, /soul-leave, /soul-refresh) + broker /me/install. Approved 2026-05-15 with the "no MVPs, no shortcuts" + "single-broker for now" directives. 8 PRs sequenced; ~10-12 working days end to end. PR1 (#135), PR2 (#136), PR3 (#137), PR4 (#138 + #139) merged 2026-05-15. Next: PR5 (broker /me/install) — see sub-plan below, ready to start cold next session.
Universe Onboarding — PR5 (broker /me/install) — detailed sub-plan for the bearer-authenticated per-user install bundle. Four sub-steps, ~155 lines of code + ~280 tests, ~1 day PR. Smaller than PR4 because PR4's compositeVerifier already handles broker-signed + IdP-signed bearer verification end-to-end; PR5 is a handler that wraps a new Issuer.MintFiltered. Includes open-design-questions list (GET vs POST, 200-empty vs 403, ordering) and next-session resume steps.

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

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