moving

2026-09-02 10:10:29 +02:00
commit 0c3e2ead3b
3841 changed files with 970576 additions and 0 deletions
--- a/docs/briefs/2026-04-25-mvp-shim-package-layouts.md
+++ b/docs/briefs/2026-04-25-mvp-shim-package-layouts.md
@@ -0,0 +1,398 @@
+# 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
+
+```ts
+// 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
+
+```bash
+$ 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
+
+```bash
+$ 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
+
+```bash
+$ 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.