soul.demarkus.io:6309/index/decisions.md/v17 draft reader meta

Decisions

Part of the demarkus-soul hub. Architecture decision records for the core project, canonical here since 2026-09-28; docs/adr/ in git is a frozen archive of 0001 to 0027 (see where decisions live). Sub-project decisions live in their own series, for example /demarkus-library/adr/. Status and dates live in each ADR.

ADR 0001: broker confidential web-client registry
ADR 0002: align store frontmatter with the Open Knowledge Format
ADR 0003: default OKF type on publish
ADR 0004: edge semantics, provenance on every edge, typed relations via rel- metadata
ADR 0005: node identity omits the default port
ADR 0006: the Postgres backend is an optional build, not a dependency; superseded by ADR 0010
ADR 0007: SNI selects and pins one virtual Mark server per QUIC connection
ADR 0008: GCS world state commits through one root CAS
ADR 0009: AGPL for the core, MIT for plugins and satellites
ADR 0010: remove the Postgres backend; the knowledge server owns shared multi-writer state
ADR 0011: allowlisted private-use scheme redirects for MCP hosts, unblocking Cursor's MCP OAuth against the broker
ADR 0012: body match is an optional mode of LOOKUP; recall specified, ranking left to the implementation
ADR 0013: source revisions, extraction views, graph freshness and generated-format compatibility
ADR 0014: the protocol module is wire and stored format only
ADR 0015: the backend contract takes a context per call and reads through views
ADR 0016: the publish policy is enforced above the store, inside its commit
ADR 0017: archive preconditions, closed views, and seeding above the store
ADR 0018: one mark URL parser, and host case is not identity
ADR 0019: tool bodies and the write contract live in shared packages
ADR 0020: one reconcile owner in docwrite, and write tools check arguments before authorization
ADR 0021: a world registry that announces drops, DNS label world names, one tenant door for tools and resources
ADR 0022: the MCP gateway takes its dependencies from Run, not the Server; NewServer takes a deps struct
ADR 0023: the broker is core, oauthsrv, gateway and storage behind one Run, with brokertest for shared fixtures
ADR 0024: the plugin binary is provision and registry package families by concern, and a harness is a host.Host value
ADR 0025: WATCH is the eighth verb, the store emits hints only, and protocol 1.0 freezes after WATCH and ALPN mark/1
ADR 0026: a client SDK under MIT with its own semver, CC0 wire fixtures, the server never imports it, exact relicensed file list
ADR 0027: world token files are optional at open and split into a broker-owned runtime file and an operator-owned static file; the chart's bootstrap Job becomes optional for GitOps
ADR 0028: every store owns a durable change epoch and sequence behind backend.ChangeSource, proven by one conformance suite; the file store keeps a journal, the bucket store its receipts (proposed)
ADR 0029: the broker issues the federation agent's hub token from agentTokens, with a broker record as the ownership marker; the umbrella drops the bootstrap Job (proposed)
ADR 0030: the broker generates and persists its state cookie key, so the chart render is deterministic under Argo CD (proposed)

soul.demarkus.io:6309/index.md draft reader meta

demarkus-soul

The living knowledge base for the demarkus project, served by demarkus itself: an agent's memory, architecture notes, debugging lessons, and decisions, all versioned. This page is a link hub; every topic page below links back here, and the pages themselves carry status.

Sections

Vision: the north star, live and reactive knowledge, three layers and the order of work
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
Conventions: collaboration and repo/plugin conventions (how I work)
Debugging: lessons learned from bugs and investigations
Roadmap: hub with one row per item; detail in topic files under /roadmap/
Benchmarks: current cost per query, definitions, and how it compares to published claims
Ecosystem: browsers, plugins, and tools that implement or integrate with demarkus
Debt: technical debt and improvement opportunities
Journal: session notes, 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
RFC review FAQ: terse Q&A for the RFC review session

Topics

Second-level hubs and reference pages split out of this index:

Decisions: the ADR series for the core project and where the canonical copies live
Active plans: plans with remaining work
Completed plans: plans that shipped, plus the older history archive
Plan archives: original plan documents kept for reference, superseded and canceled ones included
Knowledge server: the multi-world knowledge server plan and its decisions
Plugins: the agent plugins, their sources, version history, and install notes
Vocabulary: memory store, soul, knowledge system, world

Sub-projects

Standalone-repo projects in the ecosystem, each with its own hub under /<slug>/:

demarkus-library: the web front-end, a Go and htmx reading room over a broker-fronted knowledge system
demarkus-knowledge-system-deploy: GitOps deploy repo for the production knowledge system
mark-knowledge: the hosted service build, in its own repo and its own soul (port 16310); demarkus-side constraints in demarkus as a service

Current focus

Realtime demarkus: the live track, WATCH hints from the store, replica push, fan-out at the QUIC broker, live views
demarkus-sdk: the MIT client SDK every surface and application speaks demarkus through
Token-efficient retrieval: tokens per correct answer as the metric; body match, lean envelopes, hub size gate, dedup in software
Ecosystem optimization: feature freeze on exposed tooling, measured prompt and schema budgets, mechanics moved from prompts into software
demarkus 1.0: the definition of 1.0, six open decisions, ten ordered workstreams
Fortify the durable core: the properties that must outlive every overlay and eight ordered fortifications
Memory and knowledge layering: the code shaped as two tiers over one memory model, without breaking current contracts

Research

Research: Research documents, one link each.
Retrieval recovery plan: failure audit, benchmark calibration and the next bounded retrieval investigation
Document Graph: > Exported: 2026-08-17T22:27:43Z > Nodes: 220 > Edges: 866
Plan: replace OpenBao with GCP Secret Manager
Knowledge plugin pilot readiness: Blockers and should-haves for demarkus-knowledge before the 4 teams of 4 company pilot: join scope, Cowork, policy, onboarding, evals
Near-duplicate gate: Near-duplicate detection in the store: a warn-only write gate in both tiers, a doctor tier, and a dry-run publish that promote uses; thresholds from a benchmark on real worlds.
ADR 0046: The near-duplicate gate refuses in the store, with an override: The near-duplicate gate refuses in the store by default, with near-duplicate-override as the recorded way to keep both; warn