Completed Plans

Archive of implementation plans that have been executed and shipped.

Content Addressing — COMPLETED ✓

Completed: March 2026 (Phase 3)

Hash-based fetch, in-memory index, mirror foundation. All five implementation steps completed:

1. content-hash added to FETCH responses — SHA-256 of stripped body in metadata
2. Hash index in Store — BuildHashIndex(), LookupHash(), UpdateHashIndex(), RemoveHashEntry()
3. Index updates on writes — Write(), SetArchived() keep index synchronized
4. Hash-based FETCH — isHashPath() validates /sha256-<64hex>, handleFetchByHash() retrieves by hash
5. Startup initialization — BuildHashIndex() called on server startup

Key details: Content-hash is separate from etag (stripped body vs full doc). Current versions only indexed. Read auth checked after hash resolves to real path. In-memory index rebuilt on startup.

Foundation for: Federation, content-addressed mirroring, distributed caching

Federation — COMPLETED ✓

Completed: March 2026 (Phase 3)

Agent-driven hash discovery via MCP tools. Zero server changes, zero new verbs.

Shipped:

• mark_index MCP tool — crawls source server, collects hashes, publishes index to hub
• mark_resolve MCP tool — resolves content by hash using hub index
• client/internal/index package — Parse, Build, Merge for markdown hash index documents
• Manifest check enforced by tool, force override, dry_run mode, 1000 doc cap

Persistent Graph — COMPLETED ✓

Completed: March 2026 (Phase 4)

Disk-backed graph store, incremental crawl, backlinks.

Shipped:

• client/internal/graphstore package — nodes, edges, etags, timestamps, atomic writes, schema versioning
• CrawlAndPersist — unified crawl + merge + save, nil-safe, shared across CLI/TUI/MCP
• mark_backlinks MCP tool — reverse link lookup
• Graph export — Store.Export() renders as publishable markdown, ParseExport() parses back
• TUI graph view — Links (BFS), Backlinks, Topology sub-views
• Graph seeding — TUI loads instantly from stored graph while crawl runs in background

Read Auth (Server-Side) — COMPLETED ✓

Completed: 2026-03-14 (Phase 5)

Per-path read token enforcement on the server. Fully backwards compatible — no read tokens = everything public.

Shipped:

• RequiresReadAuth(path) on TokenStore — pre-computed readPaths at load time
• authorizeRead handler helper — checks token store, exempts /.well-known/agent-manifest.md
• Integrated into FETCH, LIST, VERSIONS handlers
• Content-addressed fetch respects read auth (hash resolves to path first, then checks auth)
• Versioned path auth — /doc.md/v2 checks auth on base path /doc.md
• Directory path normalization — /private and /private/ both match /private/** patterns

Remaining (Phase 5): Client-side read auth — fetch.Client read methods (Fetch, List, Versions) need a token parameter, then CLI, TUI, and MCP need to pass it through. The server enforces correctly; the clients just can't send a token on reads yet.

Conflict-Aware Merge in mark_publish — COMPLETED ✓

Completed: 2026-05-05 (PR #101 in client/v0.12.25 — diff3 + merge-candidate response; v0.12.26 — default flipped from "fail" to "merge")

Tool-level diff3 merge that reduces content loss under concurrent writes. The MCP tool produces a structurally-merged candidate body when mark_publish hits a version conflict; the agent semantically verifies the candidate and republishes. No wire-protocol changes; merge logic lives entirely in the Go client.

Shipped:

• client/internal/merge/ package — Diff3(base, ours, theirs) Result (in-package implementation, ~250 lines, line-based LCS + hunk walk, no external dependency) + Candidate(client, path, ours, expectedVersion, meta) orchestrating publish-or-merge in one shot.
• on_conflict parameter on mark_publish: "merge" (default since v0.12.26) returns a merge candidate on conflict; "fail" opts out to strict optimistic-concurrency semantics.
• Git-style conflict markers in body (<<<<<<< / ======= / >>>>>>>) — agents handle natively from training; format lives in client Go code and can be swapped without breaking the wire protocol.
• LCS dp table capped at 2M cells (~16 MB) — pathological inputs (1 MiB body of 1-byte lines) fall through to a single-hunk merge rather than allocating gigabytes.
• Candidate rejects responses where latest.Version <= 0 to prevent silent "create-only" semantics from re-publishing into nothing.

Key decisions:

• Tool never auto-publishes a diff3 result. Always returns the candidate to the agent for semantic verification. Line-disjoint changes are not semantically-disjoint (duplicate bullets, contradictions, list reorder collisions can pass diff3 but corrupt the document).
• No internal retry loop in the tool. Each mark_publish call is one-shot; iteration lives in the agent's natural fetch-modify-publish loop.
• mark_append deliberately out of scope. Append-as-stream is the right primitive there; auto-resolve handles its tiny race window because there is nothing to merge.
• Default flipped from "fail" to "merge" in v0.12.26 because the "fail"-default left naive callers exposed to silent content loss — the exact failure mode the feature exists to prevent. The shape change (merge-candidate vs conflict) is loud, not silent.

Wire-level impact: zero. on_conflict is an MCP tool parameter handled in the Go client.

Claude Code Plugin — COMPLETED ✓

Completed: 2026-04-23 plan landed; demarkus-memory plugin v0.1.1 shipped on the marketplace; SessionStart hook + lazy-spawned server + auto-generated token in active use across every demarkus development session since.

One-click marketplace install gives Claude Code users a local, versioned memory layer backed by a spawned demarkus-server. Zero core code changes — the plugin is built entirely on existing primitives (DEMARKUS_AUTH env var, demarkus-token generate, ALPN-tagged /health, tokens.Resolve).

Shipped:

• plugins/claude-code/ plugin tree: .claude-plugin/plugin.json, hooks/postinstall.sh + hooks/session-start.sh, .mcp.json, slash commands (/soul, /soul-journal, /soul-status, /soul-init, /soul-context, /soul-memory), skills/memory/SKILL.md triggering on remember/save/recall intents, seed/index.md template.
• .claude-plugin/marketplace.json at repo root for /plugin marketplace add latebit-io/demarkus.
• postinstall.sh — detects platform via uname -sm (darwin/arm64, darwin/amd64, linux/amd64, linux/arm64), downloads demarkus-server + demarkus-mcp + demarkus-token from GitHub releases, verifies SHA256 checksums against bundled file, installs to ${CLAUDE_PLUGIN_ROOT}/bin/.
• session-start.sh — probes existing demarkus server on default port 6310 via ALPN-tagged /health (a non-demarkus process can't pass ALPN negotiation, so port-reuse is safe), spawns server detached when absent, generates a /*-scoped publish+archive token on first run, writes raw token to ~/.demarkus/soul/.token mode 600, exports DEMARKUS_AUTH before MCP client launches, copies seed index.md when content root is empty.
• Plugin config at ~/.demarkus/plugin-memory.conf records the chosen MODE (default | isolated | reuse), SOUL_DIR, PORT.

Key decisions:

• Lazy spawn, no service manager (no launchd/systemd in v1). Server persists across sessions; next session reuses it via the ALPN-tagged probe.
• No core code changes. Every primitive (DEMARKUS_AUTH, /health, tokens.Resolve, the demarkus-token generate CLI redirection pattern) already existed. The plugin is pure plumbing.
• Content root at ~/.demarkus/soul/ by default. All versioning, graph data, tokens, logs live under it.
• Token mode 600 on ~/.demarkus/soul/.token.

In active use: the demarkus development workflow itself uses the plugin as the agent's memory layer — every session this conversation runs against the lazy-spawned server, every journal entry is a mark_append via the plugin's MCP wiring, the universe-deployment plan is fetched/republished through it.

Phase 6 — Universe Deployment (mostly complete)

Phase 6 (/plans/universe-deployment.md) is ~90% complete as of 2026-05-13: Helm charts for server / broker / agent, OIDC token broker binary + chart, kind-tested upgrade-wipe regression, per-service runtime images, OCI Helm chart publish via release pipeline, structured-slog observability with operator-facing schema doc. Remaining: §6.4 (topology examples) and §6.6 (ops-runbook docs), both under reframing per the "ops polish vs knowledge universe" cost/value pushback. Active plan stays at /plans/universe-deployment.md until §6.4 + §6.6 are resolved or formally deferred.