# 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](/architecture.md) — system design, module boundaries, key decisions
- [Universe Pattern](/universe.md) — souls, worlds, and hubs as a deployment topology
- [Patterns](/patterns.md) — code patterns, conventions, idioms used in this codebase
- [Guidelines](/guidelines.md) — hard rules for code quality, must be referenced before writing code
- [Debugging](/debugging.md) — lessons learned from bugs and investigations
- [Roadmap](/roadmap.md) — what's next, what's in flight, what's done, and what's deliberately not prioritized
- [Ecosystem](/ecosystem.md) — browsers, plugins, and tools that implement or integrate with demarkus
- [Debt](/debt.md) — technical debt and improvement opportunities
- [Journal](/journal/) — session notes and evolution log, one file per day at `/journal/<YYYY-MM-DD>.md`
- [Guide](/guide.md) — agent install guide for setting up demarkus-soul
- [Thoughts](/thoughts.md) — my own reflections, ideas, and open questions
- [FAQ](/faq.md) — 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](/plugins/obsidian/index.md) — fetch, publish, and browse demarkus documents from Obsidian (standalone repo `latebit-io/obsidian-demarkus`)
- Claude Code Plugin — `demarkus-memory` v0.3.0, 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 for joining organizational broker-fronted knowledge systems alongside the personal-soul flow; **v0.3.0 (2026-05-31, #168)** wires the `mark_lookup` tool and injects standing SessionStart guidance so sessions self-document to the soul and recall via lookup, fixes the `knowledge-join` tool-count text (13→14 tools), and bumps the binary pins to SERVER 0.17.13 / CLIENT 0.12.38 / TOOLS 0.1.28.

## Active Plans

Verified against code/PRs on 2026-05-31. Two plans have real remaining work:

- [Universe Deployment (Phase 6)](/plans/universe-deployment.md) — 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](/plans/versions-sharding.md) — 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

- [Broker Authorization Code Grant](/plans/broker-auth-code-grant.md) — 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](/plans/lookup-verb.md) — 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](/plans/knowledge-system-gke-deploy.md) — 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](/plans/universe-onboarding.md) — 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](/plans/broker-stable-mint.md) — 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](/plans/broker-deadcode-cleanup.md) — 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)](/plans/universe-onboarding-pr5.md) — 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](/completed-plans.md) — 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](/plans/content-addressing.md) — hash-based fetch, in-memory index, mirror foundation
- [Federation](/plans/federation.md) — agent-driven hash discovery, mark_index, mark_resolve
- [Persistent Graph](/plans/persistent-graph.md) — disk-backed graph store, incremental crawl, backlinks
- [Read Auth](/plans/read-auth.md) — per-path read token enforcement for private networks
- [Security Hardening](/plans/security-hardening.md) — systemd sandboxing, security docs, write isolation
- [Conflict-Aware Merge](/plans/conflict-merge.md) — tool-level diff3 merge in `mark_publish` (shipped client/v0.12.25 + v0.12.26)
- [Claude Code Plugin](/plans/claude-code-plugin.md) — 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)
- [Universe Onboarding — PR3 (broker device flow)](/plans/universe-onboarding-pr3.md) — 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)](/plans/universe-onboarding-pr4.md) — 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](/plans/broker-https-gateway.md) — **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](/plans/search-verb.md) — **superseded** by LOOKUP. The full-text TF-IDF SEARCH design was descoped; full-text stays permanently in an opt-in sidecar.
- [POC Deployment](/plans/poc-deployment.md) — **canceled.** The separate-POC-slice approach was rejected in favor of "build the real product once" (see universe-deployment).
- [Obsidian Plugin](/plans/obsidian-plugin.md) — **obsolete.** Source moved to the standalone `latebit-io/obsidian-demarkus` repo (2026-04-24); monorepo copy removed.