soul.demarkus.io:6309/roadmap.md/v87 draft reader meta

Roadmap

Where demarkus has been and where it's going. This page is the hub: one row per roadmap item, with the detail in a topic file under /roadmap/.

Active and planned

Item	Status	Where
Phase 5: The Demarkus Agent & Private Networks	active	protocol phases
Phase 6: Universe Deployment	planned	protocol phases
Distribution & Package Management	planned	distribution, deployment, and hosted service
Plugins	active	plugins and vocabulary
Knowledge Layer & Storage Backends	active	knowledge layer, catalog, and store
Store: make LIST and FETCH agree on flat files	active	knowledge layer, catalog, and store
Host-Agnostic MCP Layer	planned	MCP and agent surface

Topic files

scope and content contract: What the server will and will not serve, and how the markdown-only rule is enforced. (2 entries)
protocol phases: The six numbered phases from the read-only MVP to universe deployment, and the verb set. (7 entries)
knowledge layer, catalog, and store: LOOKUP, OKF metadata, graph and edge semantics, storage backends, and store consistency work. (5 entries)
MCP and agent surface: The MCP tool surface agents see and the host-agnostic layer planned above it. (2 entries)
plugins and vocabulary: Per-host memory plugins, their release history, and the product vocabulary they expose. (5 entries)
distribution, deployment, and hosted service: Packaging, the single-host install, token issuance, the production knowledge system, and the memory broker. (7 entries)
backlog and polish: TUI polish, deliberately unprioritized features, operational polish, and docs hygiene. (4 entries)

Done

Item	Where
Phase 1: MVP (Read-Only)	protocol phases
Phase 2: Publish Operations	protocol phases
Phase 3: Agent-Native & Advanced Features	protocol phases
Phase 4: The Information Graph	protocol phases
Verb Set	protocol phases
LOOKUP Catalog Verb	knowledge layer, catalog, and store
Open Knowledge Format (OKF) Compatibility	knowledge layer, catalog, and store
MCP Agent Ergonomics & Attach Surface	MCP and agent surface
Remote Token Issuance	distribution, deployment, and hosted service
Five-Minute Appliance & Install Hardening	distribution, deployment, and hosted service
Markdown-Only Content Contract	scope and content contract
OpenCode Memory Plugin	plugins and vocabulary
Production Shared Knowledge System	distribution, deployment, and hosted service
Universe-wide LOOKUP	knowledge layer, catalog, and store
Memory Broker: memory-as-a-service for MCP hosts	distribution, deployment, and hosted service
Tenant identity pinning	distribution, deployment, and hosted service
Vocabulary: soul becomes memory	plugins and vocabulary
Cursor Memory Plugin	plugins and vocabulary
Vocabulary revision: soul is the instance name	plugins and vocabulary

Backlog and reference

Five-minute appliance: the appliance work this roadmap section records
OKF type adoption: the type policy behind the OKF section
Postgres backend: the second store backend in the knowledge layer
Version retention: the retention work named in the backlog
Obsidian plugin plan: the plugin released in the plugins section

Format

The roadmap is a hub plus topic files, so no single document outgrows the full-body fetch threshold.

/roadmap.md (this file): one row per item with status and a link; no detail here. Statuses: active, planned, done, backlog.
/roadmap/<topic>.md: the entries for one area, each a ## section titled <Name>: <STATUS> (<dates, PRs>). Append new sections at the end of the topic file and add the row here in the same edit.
New topic file when an area has no file yet or a file passes about 16KB; never a second catch-all.
Anchors are stable: the section heading is the link target. Do not retitle a shipped entry; add a dated line under it.

soul.demarkus.io:6309/roadmap/agent-surface.md draft reader meta

Roadmap: MCP and agent surface

The MCP tool surface agents see and the host-agnostic layer above it. Part of the roadmap hub.

MCP Agent Ergonomics & Attach Surface

Status: done (2026-07-04/05)

Two same-week phases that made MCP agents cheap to serve and demarkus pleasant to drive from Claude Code / Desktop. Plans: /plans/mcp-client-ergonomics.md and /plans/mcp-resources-prompts.md. Both fully shipped AND deployed on both MCP surfaces (local demarkus-mcp and the broker gateway).

Shipped:

Size-adaptive mark_fetch: full body under 8KB; above it an outline (heading tree with GitHub-slug #anchors + per-section line counts + opening paragraph + hint). url#anchor slices one section at any size; force overrides. Killed the five-figure-token fetches of append-heavy docs (measured: a 52KB roadmap → 5.9KB outline).
Session unchanged-dedup: re-fetch of an unchanged doc returns status: unchanged since vN (identity = version+etag; identity-flip edge cases spelled out). Process-scoped in the local client; MCP-session-keyed at the broker (multi-tenant safe: no session → no dedup; LRU eviction at cap, since mcp-go only unregisters sessions on explicit DELETE).
mark_explore: one-call orientation card (outline head, opening paragraph, outbound links, backlinks, siblings; 10/section + "+N more").
MCP resources: documents as client-attachable context, zero tool turns: mark:// URI templates, #anchor section attach, well-known + background-listed picker entries (client) / per-world index hubs (broker).
MCP prompts: orient / recall / whats-new as server-vended slash commands; the broker variants sweep worlds via mark_worlds.
Shared packages client/mdoutline (outline/slice + render helpers) and client/fetchdedup (dedup identity + notice text); one implementation for both surfaces (the changedNote mirror drifted twice in review before hoisting; lesson in /debugging.md).
One #section grammar everywhere: mark_fetch, mark_explore, MCP resource URIs, and the demarkus-library librarian's open tool (adopted 2026-07-05) all share the same anchors from the same implementation.
Deployed: plugin users via client v0.15.0→v0.17.0 (tools 0.4.1+, pin chain now self-driving after the #228 pin-bump automation fix); knowledge.demarkus.io via broker 0.5.0 (ergonomics) and 0.6.0 (resources+prompts).

Remaining: none. Follow-ups all landed (broker parity, resources/prompts, librarian adoption).

Host-Agnostic MCP Layer

Status: done (added 2026-08-27; closed 2026-10-20, each item shipped under another entry)

2026-10-20: all three items are in place. (1) demarkus-mcp sends server instructions on initialize (host line, section-first and read-outcome guidance from mcpfmt), as do both gateway profiles; goldens pin them (layering plan, step 1). (2) demarkus-mcp vends orient, recall, whats-new, journal and context as MCP prompts; the memory gateway vends soul-context, soul-journal and soul-export. (3) The write gates run in the store in both tiers since server 0.70.0 (ADR 0045, PRs 625 and 628), so a host without hooks gets the same refusals. The .mcpb Desktop extension was not built. What a plugin-less host still lacks is the remaining prompt set, tracked as memory gateway parity.

Original framing: Claude Desktop (and any non-Claude-Code host) got only raw mark_* tools: no plugin prompt guidance, no gates, no skills. Rather than building anything Desktop-specific, push the plugin's value down into the MCP layer so every host inherits it. Context in journal 2026-08-27.

Server instructions in demarkus-mcp's initialize result. Ship the memory/knowledge usage prompt there: recall-first, routing, tagging rules, metadata-not-frontmatter.
MCP prompts. Ship soul-context, soul-journal, promote as MCP prompts; hosts surface them natively, replacing slash commands.
Server-side gates. Tag/style/destination gates were Claude Code hooks, so other hosts bypassed them. Move enforcement into the server; hooks become a mirror.

Accepted losses for non-Code hosts: session hooks (journal nudge), project-binding enforcement at spawn, /promote-scan automation.

Token-Efficient Retrieval

Status: done (set as the feature focus 2026-09-06; all eight workstreams merged by PR 431 on 2026-09-08; closed on the roadmap 2026-10-20)

2026-10-20: the plan's eight workstreams (benchmark, body match, section-first reads, lean envelope, hub size gate, promote dedup, budgeted context, document curation) are built and measured; the real-corpus baseline followed in graph evaluation. Tokens per correct answer went from 3,363 to about 1,250 on the live soul. The one budget still missed, calls to evidence 2.5 against 2, is ranking work carried by the graph roadmap's done slices and the use-aware ranking backlog entry in deterministic memory.

Reach the right knowledge with the fewest tokens, measured as tokens per correct answer. Body match as an optional mode of the catalog verb (never a new verb), snippets and section anchors, lean response envelopes, hub size gate, promote dedup in software, a retrieval benchmark that gates every step. Plan: /plans/token-efficient-retrieval.md. Continued Ecosystem Optimization and closed the "semantic recall beyond tags" gap in graph and backends.