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

Active Plans

Universe Deployment (Phase 6) — production-grade enterprise k8s deployment: Helm charts (server, broker, agent), OIDC token broker, observability, docs, release pipeline. Customers trial the real product.
Claude Code Plugin — one-click marketplace plugin that lazy-spawns a local server and wires MCP in
Conflict-Aware Merge — tool-level diff3 merge in mark_publish to reduce content loss under concurrent writes

Completed Plans

History — content addressing, federation, persistent graph, read auth (server-side)

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

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.