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