feat: MCP resources + doctor sync receipt - #36
Merged
Conversation
Ship Memory Hive as a native Claude Code Agent Skill. The template carries the on-demand depth layer (retrieval verb guide, raw-learning frontmatter spec, lane rules, curator loop) so the always-on CLAUDE.md boot block can stay small; Claude Code loads the full body only when memory work is happening (progressive disclosure), and the skill is invocable as /memory-hive. Installer wiring, doctor receipts, CI smoke, and docs land in the follow-up commit. https://claude.ai/code/session_01TbAgEqEHJ4xTcx9otN3DrN
Extend the platform smoke steps: auto-inject asserts the rendered skill lands at ~/.claude/skills/memory-hive/SKILL.md with intact frontmatter, substituted paths, and a placeholder-bearing shipped template; opt-out asserts MEMORY_HIVE_SKIP_CLAUDE_SKILL=1 skips the skill while the CLAUDE.md block still lands; idempotent asserts stable checksums across re-installs. https://claude.ai/code/session_01TbAgEqEHJ4xTcx9otN3DrN
Wire the skill template into the full install/verify lifecycle:
- install.sh: render templates/skills/memory-hive/SKILL.md (same
${HIVE_DIR}/${INSTALL_DIR} substitution as the boot block) and write it
atomically to ~/.claude/skills/memory-hive/SKILL.md when ~/.claude
exists. New platform record id `claude-skill` with wired/skip/gone
banner lines. Opt out with MEMORY_HIVE_SKIP_CLAUDE_SKILL=1 (skill
only) or MEMORY_HIVE_SKIP_CLAUDE_CODE=1 (both surfaces). Unrendered
template also shipped to $INSTALL_DIR/templates/ for inspection.
- memory-hive doctor: new check 4b warns (exit 1) when the skill file is
missing or references a different install, with a re-install hint;
silent when ~/.claude is absent.
- SKILL.md: align body with repo truth — lint errors vs warnings split,
50KB size cap, `kind:` documented as optional promote/conflicts
metadata (not lint-enforced), tasks/queue.md marked curator-written /
read-for-coordination, architecture deep-link points at the GitHub
source instead of a file the installer never ships.
- docs: INTEGRATION.md, templates/platforms/claude-code.md, README, and
CHANGELOG describe the two-surface model (always-on CLAUDE.md block +
on-demand skill) and the new env vars/uninstall steps.
The skill gives Claude Code progressive disclosure: one description line
always in context, full operational depth (retrieval verbs, lint-passing
frontmatter, lane rules, curator loop) loaded only when memory work is
happening — also invocable directly as /memory-hive.
https://claude.ai/code/session_01TbAgEqEHJ4xTcx9otN3DrN
Make the on-demand depth layer work on every platform, not just Claude Code. The single source of truth moves to templates/guide.md; surfaces are assembled from it: - New `memory-hive guide [topic]` verb renders the guide with the install's real paths at read time. Topics narrow to one section (paths|id|hydrate|retrieve|write|lanes|curate|health). Any agent that can run a shell — Cursor, Codex, Gemini CLI, Goose, Warp, Amp, OpenCode, ... — now has the same progressive disclosure Claude Code gets. - The Claude Code Agent Skill is now assembled at install time from the SKILL.md frontmatter head + guide.md body, so the skill and the cross-platform guide cannot drift apart. Older checkouts without guide.md fall back to the self-contained SKILL.md render. - install.sh ships the unrendered guide to $INSTALL_DIR/templates/ (load-bearing for the verb); doctor warns when it goes missing. - The managed boot block — spliced into all 17 auto-inject platforms — gains a 'Going deeper' pointer to `memory-hive guide`. - Fix two pre-existing boot-block bugs that taught lint-failing writes on every platform: the raw-learning example now uses the canonical agent-subdir layout (learnings/raw/<id>/YYYY-MM-DD-<slug>.md) and includes the required `confidence` field; lane-keeping now scopes shared-pool writes to the agent's own subdir. - CI: assert the skill body is assembled from guide.md, the shipped guide keeps placeholders, `guide` renders cleanly, topic extraction works, unknown topics fail, and wired boot blocks carry the pointer. https://claude.ai/code/session_01TbAgEqEHJ4xTcx9otN3DrN
… Code The boot block and Agent Skill are prompt-level: they ask the model to follow the memory contract. These hooks make the harness enforce it: - SessionStart hook (templates/hooks/session-start.sh): injects a token-budgeted hive bundle plus a `memory-hive guide` pointer into every new session as additionalContext, tagged with the agent id, hive path, and model when the payload names one. Sessions boot hydrated even if the model never reads CLAUDE.md. - Stop hook (templates/hooks/stop-ritual.sh): when a substantive session ends without a fresh dated line in the agent's log.md, block exactly once with instructions to run the ritual. stop_hook_active prevents loops, short transcripts are exempt, and every failure path (missing hive, missing python3, unparseable payload) exits 0 — hooks fail open, never trapping a session. - install.sh renders both scripts to $INSTALL_DIR/hooks/ and merges the entries into ~/.claude/settings.json via python3 (already required for HyperRecall). Entries carry a `# memory-hive` command marker so re-runs replace exactly ours; user-authored hooks are never touched and malformed settings.json is left alone with a warning. New platform record id `claude-hooks`; opt out at install with MEMORY_HIVE_SKIP_CLAUDE_HOOKS=1, mute at runtime with MEMORY_HIVE_HOOKS_DISABLE=1, retarget with MEMORY_HIVE_AGENT_ID. - Both scripts drain the hook payload from stdin before the python heredoc runs — `python3 - <<EOF` takes its program from stdin, so reading the payload inside python would see EOF and silently no-op. - doctor check 4d warns when the scripts are missing or settings.json no longer references them; CI smoke-tests the merge (idempotency, user-hook preservation, matcher), the SessionStart JSON contract, all three Stop-hook paths, and the skip env var. https://claude.ai/code/session_01TbAgEqEHJ4xTcx9otN3DrN
Promote the Unreleased section to 1.3.0 (guide verb + Agent Skill + harness hooks + boot-block lint fixes) and list `guide` in the README inspection command family. https://claude.ai/code/session_01TbAgEqEHJ4xTcx9otN3DrN
Tag pushes keep working unchanged. workflow_dispatch (version + optional sha) now creates the tag via the API first and then publishes the same changelog-backed release in one run — needed because tags created with GITHUB_TOKEN do not re-trigger the tag-push path, and some environments can push branches but not tag refs. https://claude.ai/code/session_01TbAgEqEHJ4xTcx9otN3DrN
This environment can push this branch but not tag refs, and the workflow-dispatch API is unavailable to it, so release.yml's tag-push trigger can never fire from here. This push-triggered one-shot creates the v1.3.0 tag at the merged main commit and publishes the same changelog-backed release. Idempotent; remove after the release is live. https://claude.ai/code/session_01TbAgEqEHJ4xTcx9otN3DrN
v1.3.0 was tagged and published by its single run; the file documents its own removal once done. The reusable path for future releases from restricted environments is release.yml's new workflow_dispatch input. https://claude.ai/code/session_01TbAgEqEHJ4xTcx9otN3DrN
…atform The write-back contract was prose: every model on every harness had to hand-format paths, dates, and frontmatter, and weaker models got it wrong in ways lint catches only after the fact. Make it executable: - `memory-hive log "<what you did>" [--agent <id>]` appends the dated line to the agent's silo log. - `memory-hive learn "<imperative rule>" --context "<one line>" [--kind pattern|win|mistake|insight] [--confidence low|medium|high] [--agent <id>] [--body <file>|-]` writes the raw learning to the canonical learnings/raw/<id>/YYYY-MM-DD-<slug>.md path with frontmatter that is lint-valid by construction, scaffolds the body from context + title when none is given, dodges slug collisions, and runs lint on the new file as a receipt. - The managed boot block (all 17 auto-inject platforms: Codex, Hermes, Cursor, Gemini CLI, Goose, Warp, Amp, OpenCode, ...) now instructs agents to RUN the verbs instead of hand-writing files; the guide's Workflow 3 leads with them; the Claude Stop hook's nudge cites the exact command. - CI smokes both verbs end to end and asserts the generated learning passes lint with zero warnings. https://claude.ai/code/session_01TbAgEqEHJ4xTcx9otN3DrN
Promote the Unreleased section (log/learn verbs, verb-first boot block and guide, stop-hook nudge, release workflow dispatch path) to 1.4.0. https://claude.ai/code/session_01TbAgEqEHJ4xTcx9otN3DrN
Same pattern that published v1.3.0; idempotent, removed once live. https://claude.ai/code/session_01TbAgEqEHJ4xTcx9otN3DrN
Bring the two aspects of ambient-memory products (pieces.app) that memory-hive lacked, built local-first in the existing dependency envelope: - MCP server (`memory-hive mcp`): stdio JSON-RPC, stdlib-python only. Any MCP client — Claude Desktop/Code, Cursor, Goose, Copilot — gets native tools with no boot block: ask_hive (HyperRecall retrieval with query fallback), hive_log, hive_learn, hive_capture, hive_guide. Mirrors the ask/create tool split (ask_pieces_ltm / create_pieces_memory) while keeping writes lane-correct by routing every call through the CLI verbs. `mcp --config` prints the client snippet with real paths. Ships as memory_hive_mcp.py; doctor 4e. - Ambient workstream capture: `memory-hive capture "<event>" [--source <name>] [--agent <id>]` appends timestamped events to hive/raw/<source>/YYYY-MM-DD.md per the existing Tier-1 convention — searchable by query/recall immediately, curator-distillable later. - New Claude Code SessionEnd hook feeds hive/raw/sessions/ automatically (reason + cwd), so a trace of every session exists even when the model never ran the ritual. Same fail-open, marker-tagged settings.json merge; doctor and CI cover all three hooks. - CI: capture + session-end smoke, MCP initialize/list/call over real stdio with a lint-clean learning written through the server. https://claude.ai/code/session_01TbAgEqEHJ4xTcx9otN3DrN
Same pattern that published v1.3.0 and v1.4.0; idempotent, removed once live. https://claude.ai/code/session_01TbAgEqEHJ4xTcx9otN3DrN
Claude Code was the only platform with mechanical enforcement; Cursor has a beta hooks system (~/.cursor/hooks.json, version 1) that maps to it almost one-to-one, so wire the same two-hook layer: - cursor-stop.sh (`stop` event): when a completed conversation has no fresh dated line in the agent's log.md, reply once with a followup_message citing the exact `memory-hive log` / `memory-hive learn` commands. Cursor's own loop_count is the loop guard (nudge only at 0); aborted/error runs and short transcripts are exempt; every failure path exits 0 silently. - cursor-session-end.sh (`sessionEnd` event): ambient capture — append a timestamped session-ended event (model, first workspace root) to hive/raw/sessions/ via `memory-hive capture`. - install.sh merges both into ~/.cursor/hooks.json via python3: ownership is matched by the distinctive hooks/cursor-*.sh script paths (Cursor may argv-split commands, so the settings.json-style trailing-comment marker is not safe here); user entries are never touched, malformed files are refused with a warning. New platform record id `cursor-hooks`; MEMORY_HIVE_SKIP_CURSOR_HOOKS=1 skips the hooks alone, MEMORY_HIVE_SKIP_CURSOR=1 skips all Cursor wiring, MEMORY_HIVE_HOOKS_DISABLE=1 mutes at runtime. - doctor 4f checks scripts + hooks.json wiring; CI smokes the merge (idempotency, user-entry preservation, version field) and all four stop-hook paths plus sessionEnd capture; opt-out step covers the skip var. https://claude.ai/code/session_01TbAgEqEHJ4xTcx9otN3DrN
Same pattern as v1.3.0-v1.5.0; idempotent, removed once live. https://claude.ai/code/session_01TbAgEqEHJ4xTcx9otN3DrN
`memory-hive update` executes $INSTALL_DIR/install.sh, which copied install.sh and memory-hive over themselves in place (the PATH shim is a symlink to the same inode). The running interpreter then read the new, longer file at old byte offsets and died with phantom syntax errors, leaving a half-applied update. The v1.3.0-v1.6.0 releases grew both files by hundreds of lines, making the corruption near-deterministic. - helper installs and hook renders now stage to a temp file and mv into place: rename() swaps the directory entry, the old inode stays readable for running processes - update.sh runs the installed installer from a temp copy, never from the path being refreshed - new CI step reproduces the scenario (self-update from an upstream copy padded by thousands of bytes) and asserts a clean run, applied update, working CLI — for both the direct and wrapper paths Verified locally: the released v1.6.0 tree crashes in this scenario (Syntax error: "}" unexpected); the fixed tree passes all paths. https://claude.ai/code/session_01TbAgEqEHJ4xTcx9otN3DrN
…1.7.0) The lifecycle had install/update/doctor but leaving meant hand-editing 19 files. Every managed artifact is marker-tagged, so removal is deterministic: - strips the managed block from all 17 platform config files; user content outside the markers is preserved, files that contained only our block are removed - removes memory-hive entries from ~/.claude/settings.json and ~/.cursor/hooks.json, preserving user-authored hooks and dropping empty wrappers; malformed JSON is left alone with a by-hand hint - removes the Agent Skill dir and PATH shims that point at this install - dry-run by default, --apply to execute, idempotent; hive data and the install dir are never touched (receipt ends with the manual rm for a full purge) - CI smoke: dry-run inertness, user-content + user-hook preservation, wholly-ours file removal, shim removal, hive untouched, idempotency https://claude.ai/code/session_01TbAgEqEHJ4xTcx9otN3DrN
"What's been happening?" now includes passive capture: digest ends with a Workstream section listing each hive/raw/<source>/YYYY-MM-DD.md file touched in the window (event count + newest event), renders it even when the window holds only ambient activity (previously the empty agent-records early-return hid it), and excludes raw stream files from the per-agent loop so events are not reported twice through the "ingester" pseudo-agent. CI asserts the section and the sessions stream line after the capture smoke. https://claude.ai/code/session_01TbAgEqEHJ4xTcx9otN3DrN
memory-hive sync setup|push|pull|status: the hive becomes its own git repo (never nested into another — dev checkouts refused), append-only surfaces carry merge=union attributes so concurrent machines merge without conflicts, a joining machine integrates an existing remote via an unrelated-histories merge with the remote hive as canon, pull checkpoints first and runs quiet maintenance after, and machine-local artifacts (recall index, checkpoints, maintenance timestamp) never sync. Repo-local git identity fallback covers fresh boxes without a global git config. Breaking-ish: `sync` no longer aliases `update` (update/upgrade are unchanged). CI: full two-machine round trip — setup, join, concurrent writes, union convergence, checkpoints-stay-local, nested-repo refusal. https://claude.ai/code/session_01TbAgEqEHJ4xTcx9otN3DrN
dodges pipefail macOS tempdirs (and any symlinked hive path) broke every sync push: git rev-parse --show-toplevel prints the resolved physical path while $HIVE_DIR held the logical one, so the own-repo string comparison false-negatived and push/pull died with "not its own git repo". Compare `pwd -P` of both sides instead. Also fix the CI nested-refusal assertion: the probed command exits 1 by design, and piping it into grep under the step's pipefail reported failure even on a match — capture first, then grep. https://claude.ai/code/session_01TbAgEqEHJ4xTcx9otN3DrN
doctor gains a sync section on synced hives: OK line with remote and ahead/behind, warning (exit 1) with a `sync pull` hint when the local hive is behind its upstream — other machines pushed memory this box has not seen. Offline check (local refs only), silent when sync is not configured. The guide's Health section and INTEGRATION.md document the cross-machine workflow; CI asserts the doctor receipt in the sync smoke. https://claude.ai/code/session_01TbAgEqEHJ4xTcx9otN3DrN
resources/list + resources/read expose hive://index, hive://guide (rendered via the CLI), and every knowledge/ and learnings/distilled/ file, scanned fresh per call so curator promotions appear without a server restart. Only registered URIs resolve (basename + fixed roots — no traversal surface). Capability advertised in initialize; CI smokes listing, index and rendered-guide reads, and traversal rejection. https://claude.ai/code/session_01TbAgEqEHJ4xTcx9otN3DrN
grep -q exits at first match; doctor then dies on SIGPIPE printing its remaining sections and pipefail reports the pipeline as failed even though the receipt was present. Same lesson digest already documents. https://claude.ai/code/session_01TbAgEqEHJ4xTcx9otN3DrN
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
v1.9.0 — the loop's final batch (iterations 4 + 5):
MCP resources — mount the hive canon in any MCP client
resources/list+resources/readexposehive://index,hive://guide(rendered with real paths via the CLI), everyhive://knowledge/*.md, and everyhive://distilled/*.mdinitializeDoctor sync receipt
sync pullhint when the local hive is behind upstream — other machines pushed memory this box hasn't seenVerification
https://claude.ai/code/session_01TbAgEqEHJ4xTcx9otN3DrN
Generated by Claude Code