Journal — 2026-05-31

demarkus-memory plugin v0.3.0 — self-documenting sessions + LOOKUP recall (#168, merged)

Shipped a plugin update that started as a security-pin bump and grew into a real feature. Merged to main as squash commit c54927e.

What landed

• Security pins bumped to the fix-containing releases from yesterday's dep bump: SERVER 0.17.10→0.17.13, CLIENT 0.12.36→0.12.38, TOOLS 0.1.16→0.1.28. The existing version-sentinel drift logic in ensure_binaries propagates these to existing installs on next session start. Plugin version 0.2.0→0.3.0; reconciled the stale marketplace.json (was wrongly 0.1.1).
• Always-on self-documentation. New context/session-guidance.md is injected every session via a SessionStart hookSpecificOutput.additionalContext payload. session-start.sh now folds all setup output to stderr ({ … } 1>&2) so stdout carries only the JSON, and emits it last. Two new lib.sh helpers: json_escape (portable awk JSON-string encoder, no jq) and server_health_warning.
• Server-down warning. When the configured memory server isn't reachable, the injected context leads with a ⚠️ so the agent surfaces it instead of silently failing memory calls. Health signal is PID-liveness (managed modes) / adopted-process scan (reuse) — deliberately NOT the port probe, which degrades to permissive without lsof/ss and would false-warn.
• LOOKUP integration. mark_lookup is now the first recall step in the skill ("what do I know about X") with the catalog-not-full-text caveat. Agent-owned tagging + importance is now instructed across all three write paths — free-form publishes (skill), proactive self-documentation (session guidance), and /soul-journal (creation-time tags/importance, with a re-publish note since mark_append carries no metadata). knowledge-join.md corrected 13- → 14-tool surface.

Review + fixes

• CodeRabbit flagged one real issue: server_health_warning passed raw .pid contents to kill -0, which misreads empty/option-like (-1)/garbage content as alive. Fixed with a ^[0-9]+$ guard before probing; tested across no-file / empty / option-like / garbage / dead-pid / live-pid.
• The "docstring coverage 50% < 80%" pre-merge warning was a soft check, skipped with reason (the bash helpers already carry header comments; not contorting code for a metric).

.gitignore bug caught in passing

Fritz noticed tools/demarkus-token showed as ignored. Root cause: the unanchored stray-binary entry tools/demarkus-token matched the source package directory (tools layout puts main packages at tools/<name>/, unlike client/server which use cmd/), silently ignoring any new untracked file in the package. main.go survived only because it predated the rule. First instinct was to delete the line, but Fritz pushed back ("it should build on change no?") — empirically confirmed cd tools/demarkus-token && go build does drop a tools/demarkus-token/demarkus-token binary, so the protection was real. Correct fix: anchor to the binary path. Extended to demarkus-publish and demarkus-broker, which had the same latent footgun and were never covered.

Lesson

"Delete the redundant ignore" was wrong — the artifact it guarded against does get built (just via a different invocation than I first reasoned about). Test the actual build behavior before declaring an ignore rule pointless. Anchoring beats deleting when a stray-binary name collides with a source directory.

Note

This entry couldn't be tag/importance-stamped: the demarkus-soul MCP mark_publish gateway here predates the metadata param that #168 (and the earlier LOOKUP work) added to the local demarkus-mcp. So the very recall improvement shipped today isn't yet available on this soul's gateway — worth a follow-up to bump the soul server/client to a build that exposes publisher metadata over MCP.

Soul-doc reconciliation + plugin-store divergence check (later session)

Fritz asked "are we using the new plugin." Surfaced two things worth recording.

Soul docs lagged the plugin release

/index.md (was v40, modified 05-30) and /roadmap.md (v37) both predated #168's merge, so they still narrated the plugin as v0.2.0. The plugin code itself was consistent at v0.3.0 (repo plugin.json + marketplace.json + installed cache all agree) — drift was docs-only. Updated both: index Plugins bullet + Claude Code Plugin version-history block in roadmap now reflect v0.3.0 (#168) with the lookup-wire / self-doc-guidance / pin-bump summary. index → v41, roadmap → v38.

The session was NOT routing through the plugin's store

Four mark-protocol MCP servers are wired in this Claude Code install:

• demarkus-soul → demarkus-mcp -host mark://soul.demarkus.io — the remote production soul. This is what the preflight + all work used (correct, per CLAUDE.md).
• plugin:demarkus-memory:demarkus-memory → wrapper at …/cache/demarkus/demarkus-memory/0.3.0/…, points at mark://localhost:6309 — the plugin's lazy-spawned local store.
• demarkus-hub, knowledge — also connected.

The plugin's local localhost:6309 store is stale and unrelated: its /index.md is v7, modified 2026-05-01, and it's a hub for nib / Junto projects, not demarkus. So the v0.3.0 plugin is installed and live in-session (it injected the SessionStart self-documentation guidance), but its backing store is a different, month-old personal soul — divergent from the demarkus soul where project knowledge actually lives. Two distinct backends; no conflict, but worth knowing they aren't the same memory.

Resolved a prior-entry worry

The earlier entry noted the soul's MCP gateway predated the metadata param so this journal "couldn't be tag/importance-stamped." That's no longer true — today's index/roadmap publishes carried metadata (tags + importance) and succeeded, and this journal already shows tags/importance in frontmatter. The soul gateway now exposes publisher metadata over MCP. Follow-up closed.