waggle-os/docs/briefs/2026-04-25-mvp-shim-package-layouts.md

MVP Shim Package Layouts — 3 Targets, Architecture Only

Date: 2026-04-25 Author: claude-opus-4-7 (PM Cowork) Status: Architecture sketches ready for CC-1 implementation when Marko ratifies Universal Silent Capture strategy Companion: briefs/2026-04-25-universal-silent-capture-strategy.md Scope: 3 MVP shim packages — @hive-mind/claude-code-hooks, @hive-mind/cursor-hooks, @hive-mind/hermes-hooks

This brief is architecture-only, not implementation. CC-1 receives this when Marko ratifies repo creation. No code writing without ratification.

---

§0 Common foundation — @hive-mind/shim-core

Zero-th package u monorepo: shared utilities used by all 3 MVP shims (and Phase 2 + 3 shims later).

Folder structure

packages/shim-core/
├── src/
│   ├── frame-encoder.ts          # I/P/B frame encoding helpers
│   ├── workspace-resolver.ts     # CWD → workspace.mind file mapping
│   ├── cli-bridge.ts             # npx @hive-mind/cli wrapper sa typed I/O
│   ├── hook-event-types.ts       # canonical hook event interface
│   ├── importance-classifier.ts  # rules za temporary/important/critical importance
│   ├── prompt-summarizer.ts      # turn → summary text reducer (no LLM call)
│   ├── retry-bridge.ts           # CLI bridge sa retry + timeout handling
│   ├── logger.ts                 # shared structured logger
│   └── index.ts                  # barrel export
├── tests/
│   ├── frame-encoder.test.ts
│   ├── workspace-resolver.test.ts
│   └── cli-bridge.test.ts
├── package.json                  # @hive-mind/shim-core
├── tsconfig.json
└── README.md                     # consumer guide

Public API surface

// frame-encoder.ts
export interface HookFrame {
  content: string;
  importance: 'temporary' | 'important' | 'critical';
  scope: string;          // session-id or workspace
  source: 'claude-code' | 'cursor' | 'hermes' | 'codex' | 'opencode' | 'openclaw';
  parent?: string;        // link to user-prompt frame
  metadata: {
    project?: string;
    cwd: string;
    timestamp_iso: string;
    target_version?: string;
  };
}
export function encodeFrame(input: HookEvent): HookFrame;

// workspace-resolver.ts
export interface Workspace {
  path: string;            // absolute path to .mind file
  cwd: string;             // origin CWD that resolved here
  mode: 'global' | 'per-project';
}
export function resolveWorkspace(cwd?: string): Promise<Workspace>;

// cli-bridge.ts
export interface CliBridge {
  saveMemory(frame: HookFrame): Promise<{ id: string; success: boolean }>;
  recallMemory(query: string, opts?: { limit?: number }): Promise<HookFrame[]>;
  switchWorkspace(path: string): Promise<{ active: string }>;
  compactMemory(scope?: string): Promise<{ merged: number }>;
}
export function createCliBridge(opts?: { cli_path?: string; timeout_ms?: number }): CliBridge;

Dependency footprint

• node:fs/promises, node:path, node:child_process — no external runtime deps for core
• DevDeps: vitest, typescript, @types/node
• Target: Node 20+ (LTS)

---

§1 @hive-mind/claude-code-hooks — Anthropic Claude Code

Pre-existing context (per research §03)

Marko-vov primary daily driver. Claude Code već fires hooks u session-start.js + session-end.js + gsd-context-monitor.js + gsd-phase-boundary.sh + output-discipline.js. Niti jedan ne talks to hive-mind.

Memory file at ~/.claude/projects/<slug>/memory/MEMORY.md is parallel system. Strategy: shim handles episodic layer (actual conversation content u hive-mind frames), MEMORY.md ostaje semantic layer (distilled rules + user profile).

Per research/2026-04-22-hive-mind-positioning/00-SYNTHESIS.md §5: "do NOT run silent hive-mind on top of the existing file-based MEMORY.md system without a split."

Folder structure

packages/claude-code-hooks/
├── src/
│   ├── hooks/
│   │   ├── session-start.ts      # SessionStart event handler
│   │   ├── user-prompt-submit.ts # UserPromptSubmit event handler
│   │   ├── stop.ts               # Stop event handler (post-response)
│   │   └── pre-compact.ts        # PreCompact event handler
│   ├── install.ts                # patches ~/.claude/settings.json
│   ├── uninstall.ts              # reverses install
│   ├── verify.ts                 # post-install smoke test
│   └── index.ts                  # public exports
├── bin/
│   └── claude-code-hooks         # CLI entry: install/uninstall/verify
├── tests/
│   ├── session-start.test.ts
│   ├── stop.test.ts
│   └── install-flow.test.ts
├── package.json                  # @hive-mind/claude-code-hooks
└── README.md                     # one-line install + troubleshooting

Hook event → hive-mind action mapping

Claude Code event	shim action	hive-mind CLI call	importance
SessionStart	resolve CWD workspace, fetch top-20 frames, inject as briefing	switch_workspace + recall_memory --limit 20	n/a (read)
UserPromptSubmit	encode user message as temporary frame	save_memory --importance temporary --scope <session-id>	temporary (decays unless promoted)
Stop	summarize turn, save as important frame, link to user-prompt	save_memory --importance important --scope <session-id> --parent <prompt-id>	important
PreCompact	trigger memory compaction before context truncation	compact_memory --scope <session-id>	n/a (maintenance)

Install command UX

$ npx @hive-mind/claude-code-hooks install
✔ Detected Claude Code config at ~/.claude/settings.json
✔ Detected hive-mind CLI v0.x.x available via npx
✔ Patched 4 hook entries (session-start, user-prompt-submit, stop, pre-compact)
✔ Created backup at ~/.claude/settings.json.bak.2026-04-26T10-30-00Z
✔ Verified hive-mind ↔ Claude Code communication (test save + recall round-trip 87ms)

Done. New Claude Code sessions will silently capture to hive-mind.
Workspace: ~/.hive-mind/global.mind (default)
Run "claude-code-hooks status" to inspect.
Run "claude-code-hooks uninstall" to revert.

MEMORY.md split strategy (per research §5 recommendation)

• MEMORY.md stays — file-based, distilled semantic facts (rules, preferences, user profile). Marko continues authoring entries manually as needed.
• hive-mind frames — episodic, automatic capture of conversation content. Searchable via MCP tools recall_memory, search_entities.

Bridge mechanism (optional for v1.1, not v1.0): periodic cron job extracts high-importance frames from hive-mind, distills into MEMORY.md candidates, prompts Marko-side review before write.

Acceptance criteria

• One-line install completes in <30s
• Backup of settings.json created before any modification
• Uninstall fully reverses install (settings.json restored from backup)
• Round-trip save+recall test in install verifies hive-mind responsive
• All 4 hooks fire on real Claude Code session without errors
• No interference with existing hooks (session-start.js, gsd-context-monitor.js, etc. continue to run)

Risks

• Claude Code hook spec changes — shim must version-pin against tested Claude Code versions, refuse install on unknown version unless --force flag
• MEMORY.md double-writes — install MUST NOT auto-replace existing MEMORY.md briefing logic; coexistence enforced
• npx @hive-mind/cli not installed — install detects + offers to npm install -g @hive-mind/cli first

---

§2 @hive-mind/cursor-hooks — Cursor IDE

Pre-existing context (per WebSearch April 2026)

Cursor 3.1.15 ima sessionStart hook + marketplace listing. Hooks 10-20x faster post Jan 2026. CLI release Jan 8 2026 added MCP management commands. ~40 active tools ceiling per session combined across all MCP servers.

Memory MCP servers postoje u Cursor marketplace (Memory Bank MCP Server, Memory MCP, Pieces). Native silent capture doesn't exist yet — Cursor support za auto-capture limited to chat history.

Folder structure

packages/cursor-hooks/
├── src/
│   ├── hooks/
│   │   ├── session-start.ts      # Cursor sessionStart event
│   │   └── stop.ts               # Cursor post-response (if event exists in 2026 spec)
│   ├── marketplace/
│   │   ├── manifest.json         # Cursor hook marketplace listing manifest
│   │   ├── icon.svg              # 512x512 listing icon
│   │   └── screenshots/          # marketplace screenshots
│   ├── install.ts                # CLI-based install via cursor CLI
│   ├── uninstall.ts
│   ├── verify.ts
│   └── index.ts
├── bin/
│   └── cursor-hooks
├── tests/
│   ├── session-start.test.ts
│   └── install-flow.test.ts
├── package.json                  # @hive-mind/cursor-hooks
└── README.md

Hook event → hive-mind action mapping

Cursor event	shim action	hive-mind CLI call	importance
sessionStart	resolve workspace, optional inject top-N frames into Cursor agent context	switch_workspace + recall_memory --limit 10	n/a (read)
post-response (if Stop equivalent in 2026 spec)	summarize + save	save_memory --importance important	important

Note on event surface: Cursor's hook surface u April 2026 is narrower than Claude Code's. SessionStart is confirmed; UserPromptSubmit + Stop equivalents may require workaround via Cursor's CLI watch mode or MCP tool wrapping.

Install command UX

$ npx @hive-mind/cursor-hooks install
✔ Detected Cursor 3.1.x at /Applications/Cursor.app
✔ Detected Cursor CLI installed (v0.x)
✔ Verified ~40-tool MCP ceiling — current Cursor MCP usage: 12 tools used → 28 available
✔ Registered hive-mind hook in Cursor settings (sessionStart)
✔ Marketplace listing: optional. Run "cursor-hooks publish" to submit if you maintain a fork.

Done. New Cursor sessions will silently capture to hive-mind.

Marketplace listing strategy

cursor-hooks publish (optional command for fork maintainers) packages the listing manifest + icon + screenshots and submits to Cursor's hook marketplace. Marko-vova decision (per Universal Silent Capture brief §11 question 5): submit official listing as part of MVP launch ili sequential post-public-release.

Acceptance criteria

• Install detects Cursor version + warns on unknown
• 40-tool ceiling check before install — refuses install if would exceed without --force
• Marketplace listing manifest valid per Cursor 2026 schema
• Round-trip test sa hive-mind backend

Risks

• ~40-tool ceiling silent failure mode (per WebSearch Cursor 2026 docs) — install MUST verify pre-install
• Cursor proprietary spec breakage — shim version-pinned, install refuses on incompatible Cursor
• Marketplace review timeline (typically 1-3 weeks) — official listing not on critical path for MVP launch; can ship npm-only first

---

§3 @hive-mind/hermes-hooks — Nous Research Hermes Agent

Pre-existing context (per WebSearch April 2026)

64,200+ GitHub stars, MIT license. v0.10.0 released April 16, 2026. MCP out of the box. Hooks: pre_llm_call, post_llm_call, on_session_start, on_session_end. Auto-injects MEMORY.md + USER.md u system prompt at session start. Self-improving loop sa skill documents stored u persistent memory.

MiniMax partnership announcement (per Hermes April 2026 article — same MiniMax as our judge). Strategically meaningful; Nous Research koalicija sa MiniMax ekosistemom is friendly territory za hive-mind.

Folder structure

packages/hermes-hooks/
├── src/
│   ├── hooks/
│   │   ├── pre_llm_call.py       # Hermes pre_llm_call hook
│   │   ├── post_llm_call.py      # Hermes post_llm_call hook
│   │   ├── on_session_start.py   # Hermes on_session_start hook
│   │   └── on_session_end.py     # Hermes on_session_end hook
│   ├── memory_md_bridge.py       # Hermes MEMORY.md ↔ hive-mind frames bridge
│   ├── install.py                # registers in Hermes config (~/.hermes/config.json or similar)
│   ├── uninstall.py
│   ├── verify.py
│   └── __init__.py
├── pyproject.toml                # PyPI package metadata (Python target — Hermes is Python-first)
├── tests/
│   ├── test_pre_llm_call.py
│   ├── test_memory_md_bridge.py
│   └── test_install_flow.py
├── package.json                  # NPM mirror (optional for Node-runtime users)
└── README.md

Language note

Hermes Agent is Python-first (per Nous Research codebase). Shim package primary target je PyPI, sa optional NPM mirror za Node-runtime context. CC-1 should produce Python implementation; cli-bridge.ts (Node) is replaced sa cli_bridge.py (Python) for this shim.

Hook event → hive-mind action mapping

Hermes event	shim action	hive-mind CLI call (via subprocess)	importance
on_session_start	resolve workspace, sync MEMORY.md ↔ hive-mind, inject brief	switch_workspace + recall_memory --limit 15 + memory_md_bridge sync	n/a (read+sync)
pre_llm_call	encode user input + hint context as temporary frame	save_memory --importance temporary	temporary
post_llm_call	summarize + capture skill emergence (if any)	save_memory --importance important + skill_extract	important; skills marked critical if novel
on_session_end	flush GOP boundary, schedule maintenance	compact_memory + cognify --light	n/a (maintenance)

MEMORY.md ↔ hive-mind bidirectional bridge

Hermes auto-injects MEMORY.md at on_session_start. Shim provides bidirectional bridge:

• At session start: read existing MEMORY.md content, parse into hive-mind frames (importance=critical), update hive-mind reflecting user-curated state
• During session: hive-mind frames continue capturing episodic content
• At session end: optionally extract high-importance frames + propose MEMORY.md edits for user review (NOT auto-write)

Default: bridge is read-only at session-start (sync MEMORY.md → hive-mind). Auto-write to MEMORY.md is opt-in flag (--enable-md-writeback) given user-curated semantic file.

Skill emergence integration

Hermes' signature feature: agent writes reusable skill documents from experience. Shim captures emerged skills as critical-importance hive-mind frames sa special metadata { frame_type: 'skill', skill_id, skill_lineage }. Cross-IDE benefit: skill emerged in Hermes session becomes recallable u Claude Code session via shared workspace.

Install command UX

$ pip install hive-mind-hermes-hooks
$ hive-mind-hermes-hooks install
✔ Detected Hermes Agent v0.10.x at ~/.hermes/
✔ Detected hive-mind CLI v0.x.x via subprocess test
✔ Patched 4 hook registrations in ~/.hermes/config.json
✔ Created backup at ~/.hermes/config.json.bak.<timestamp>
✔ Synced MEMORY.md (3 entries) → hive-mind workspace ~/.hive-mind/global.mind
✔ Verified round-trip save + recall via Hermes hook test (54ms)

Done. New Hermes sessions will:
  1. Sync MEMORY.md to hive-mind at session start
  2. Capture episodic content during session
  3. Capture emerged skills as critical-importance frames
  4. Propose MEMORY.md edits at session end (review required)

Acceptance criteria

• Install completes in <60s including MEMORY.md initial sync
• Bridge read-only by default; writeback opt-in via flag
• Skill emergence frames carry metadata for cross-IDE replay
• Hermes config backup before modification
• Smoke test: spawn Hermes session, verify hooks fire, verify hive-mind frames written

Risks

• Hermes config schema changes — version-pin against tested versions
• MEMORY.md auto-writeback can clobber user-curated content — opt-in only, dry-run preview by default
• MiniMax partnership context — Nous Research may have own preferred memory layer; positioning as "complementary not competitive"
• Subprocess overhead per hook event — keep shim hooks under 50ms execution for hot path (pre_llm_call, post_llm_call)

Strategic note — Hermes coalition opportunity

Per Universal Silent Capture brief §11 question 4: aktivni outreach Nous Research vs silent ship + organic discovery?

Recommend active outreach because:

• 64k stars sa MiniMax partnership = Nous Research is an ecosystem builder, will likely welcome OSS shim if narrative is "complementary not competitive"
• Co-authored blog post potential ("Hermes Agent + hive-mind: Memory at scale") provides distribution to both audiences
• Inclusion u Nous Research Discord + community calls = developer adoption flywheel

Outreach path: GitHub issue na nousresearch/hermes-agent proposing collaboration, plus DM to maintainers via X/Discord. Pre-public release ako moguće, ali bez forcing — silent ship is fallback.

---

§4 Cross-shim conventions

Versioning

• Each shim follows semver
• Major version pin to hive-mind core minor version (1.x shim → 1.x hive-mind core)
• Breaking changes u hive-mind core trigger major bumps u all shims simultaneously

Telemetry

• Default off. No phone-home, no analytics by default per Apache 2.0 + privacy stance.
• Opt-in --anonymous-usage flag enables aggregate metrics (install count, version, OS) — explicit opt-in only.

Config storage

• Shim-side config lives sa target IDE's existing config (e.g., ~/.claude/settings.json for Claude Code, ~/.hermes/config.json for Hermes).
• hive-mind state lives at ~/.hive-mind/ (per-user) or workspace-specific <project>/.hive-mind/ if user opts in.

Logging

• Default log level: info
• Shim logs to ~/.hive-mind/logs/<shim-name>.log rotated daily, max 7 days kept
• Errors surface to target IDE's existing log surface where possible

Error handling

• Shim errors NEVER propagate to user-facing IDE error message. Hooks catch + log + continue silently.
• Repeated errors (3+ within 60s) trigger one-time warning toast/log, no further user interruption.
• Hard failure (hive-mind CLI not responding) auto-disables shim for that session with logged warning.

---

§5 Implementation sequence (CC-1 dispatch order)

When Marko ratifies and CC-1 starts:

Sprint 1 (3-5 days): shim-core + claude-code-hooks + smoke tests + basic CI Sprint 2 (2-3 days): cursor-hooks (sa marketplace manifest deferred to post-public listing) Sprint 3 (4-6 days): hermes-hooks (Python target + bridge implementation) Sprint 4 (2 days): monorepo polish, README cross-references, npm publish workflow, PyPI publish workflow, final smoke tests

Total estimated: 2-3 weeks for 3 MVP shims. Phase 2 shims (Codex + OpenCode + OpenClaw) follow with similar cadence; Phase 3 generic MCP fallback packages are template-driven, faster.

---

§6 What this brief is NOT

• NOT implementation. CC-1 generates code based on these architectures only after Marko ratification.
• NOT exhaustive — schema may evolve based on first implementation discovery (e.g., Cursor hook event surface in 2026 spec may be richer than current research suggests; Hermes hook event surface may have additions in v0.11).
• NOT a launch blocker — these shims ship 1-2 weeks AFTER hive-mind core public release. MVP shim availability sa hive-mind public is the goal but if shims slip, hive-mind launches without them and shims roll out 1 week each.

---

§7 Authorized by

PM (claude-opus-4-7) authoring 2026-04-25 dok agentic cell radi. Marko ratifies after final halt ping + Universal Silent Capture strategy ratification, then CC-1 dispatched per Sprint 1-4 sequence.