# https://github.com/activeloopai/hivemind Project Manual

Generated at: 2026-07-06 14:09:46 UTC

## Table of Contents

- [System Overview & Architecture](#page-1)
- [Agent Integrations & Installer](#page-2)
- [Session Capture, Hooks & Recall](#page-3)
- [Skillify, Summaries, Rules & Codebase Graph](#page-4)

<a id='page-1'></a>

## System Overview & Architecture

### Related Pages

Related topics: [Agent Integrations & Installer](#page-2), [Session Capture, Hooks & Recall](#page-3)

<details>
<summary>Related Source Files</summary>

The following source files were used to generate this page:

- [README.md](https://github.com/activeloopai/hivemind/blob/main/README.md)
- [package.json](https://github.com/activeloopai/hivemind/blob/main/package.json)
- [src/config.ts](https://github.com/activeloopai/hivemind/blob/main/src/config.ts)
- [src/deeplake-api.ts](https://github.com/activeloopai/hivemind/blob/main/src/deeplake-api.ts)
- [src/index-marker-store.ts](https://github.com/activeloopai/hivemind/blob/main/src/index-marker-store.ts)
- [src/embed-daemon.js](https://github.com/activeloopai/hivemind/blob/main/src/embed-daemon.js)
</details>

# System Overview & Architecture

Hivemind is a memory-augmentation layer for Claude Code. It captures developer activity into persistent, searchable traces and proactively re-injects relevant context into future prompts. The current release line is **v0.7.118** (Source: [CHANGELOG.md]()), and the project hard-depends on Deep Lake plus the `pg_deeplake` PostgreSQL extension as its only supported storage backend (Source: [README.md](); community-confirmed in issue #282).

## Purpose & Scope

Hivemind's role is to bridge ephemeral Claude Code sessions with long-lived, team-shared memory. Concretely it:

- Captures session data, rules, and skills through Claude Code lifecycle hooks (`SessionStart`, `UserPromptSubmit`).
- Persists those traces in `pg_deeplake`-backed tables such as `default.memory`, `sessions`, `hivemind_rules`, and per-org `skillify` tables (Source: [src/deeplake-api.ts:1-120]()).
- Recalls top-k matches and injects them back into the prompt so a user's own prior context (and their team's) is available without an explicit search step.
- Exposes CLI/MCP surfaces for managing memory, rules, skills, and wiki summaries.

Because the backend is fixed, installation, embedding generation, and recall all assume the hosted Deep Lake data plane; this single fact is the most common source of community questions (Source: issue #282 — closed as a non-feature).

## Core Components

| Layer | Responsibility | Anchor file |
|-------|----------------|-------------|
| Hook integration | Bridges Claude Code lifecycle events to in-process handlers and recall workers | `src/embed-daemon.js` |
| Storage adapter | Wraps `pg_deeplake` tables and ensures lookup indexes exist | `src/deeplake-api.ts` |
| Index freshness | Tracks marker TTL so `CREATE INDEX IF NOT EXISTS` is rate-limited | `src/index-marker-store.ts` |
| Configuration | Loads connection strings, table names, timeouts | `src/config.ts` |
| Distribution surface | CLI binary, MCP connector for Claude Cowork, `skillify push` | `package.json` |

The embed daemon is the producer of the `UserPromptSubmit` hook payload. When its launcher is missing from `embed-deps` but embeddings remain enabled, the hook silently waits and Claude Code aborts at the 2-second timeout — visible to the user as `UserPromptSubmit hook timed out after 2s — output discarded` (Source: issue #296; hook registration lives alongside `src/embed-daemon.js:1-80]()).

## Data Flow & Storage Pipeline

A typical session lifecycle:

1. Claude Code fires `SessionStart`. `src/index-marker-store.ts` evaluates the marker TTL before letting `src/deeplake-api.ts:ensureLookupIndex` issue `CREATE INDEX IF NOT EXISTS` against the `sessions` table (Source: [src/index-marker-store.ts:1-60](); [src/deeplake-api.ts:ensureLookupIndex]()).
2. Each prompt/response pair is forwarded to the embed daemon, which writes rows into `pg_deeplake` tables such as `default.memory`.
3. On the next `UserPromptSubmit`, the recall worker queries those tables and attaches the top-k matches as extra context.
4. CLI and MCP subcommands (`rules list`, `skillify push`, `wiki summary`) read or mutate the same tables.

```mermaid
flowchart LR
  A[Claude Code Session] -->|SessionStart hook| B(embed-daemon.js)
  A -->|UserPromptSubmit hook| B
  B -->|writes| C[(pg_deeplake tables)]
  C -->|ensureLookupIndex| D[index-marker-store.ts]
  B -->|recalls top-k| C
  C -->|context block| A
```

The `index-marker-store.ts` TTL guard exists specifically because, on busy workspaces (~40k rows in `sessions`), an unconditional `CREATE INDEX IF NOT EXISTS` exceeded the 10-second `SessionStart` budget and produced noticeable hangs (Source: issue #89). The fix is described as TTL math + marker freshness inside `src/index-marker-store.ts` and applied via the call site in `src/deeplake-api.ts:ensureLookupIndex`.

## Known Architectural Constraints

- **Backend lock-in**: No local or self-hosted connector exists; traces cannot be collected without Deep Lake. The maintainer response is explicit: "Hivemind requires deeplake backend and pg-deeplake to collect traces and enable memory search and recall" (Source: issue #282, closed).
- **Schema drift**: Mismatches between the `pg` projection columns and the underlying Deep Lake dataset surface as `Data type mismatch … schema drift on table "default.memory"` errors in the UI (Source: issue #173).
- **Optional native addons**: `tree-sitter` is treated as optional; missing loaders are tolerated by the CLI rather than crashing (Source: v0.7.116 release notes, PR #295).
- **Multiple Claude credentials**: Users with more than one Claude credential cannot natively scope which set Hivemind captures from — there is no built-in credential filter (Source: issue #113).
- **Worker stability**: Long sessions previously crashed the wiki summary worker; the crash was fixed across v0.7.117 and v0.7.118 (Source: release notes; PR #298).

## Integration Points

Beyond the Claude Code hooks, recent releases have widened the architecture:

- A **Claude Cowork MCP connector** is bundled in v0.7.114, exposing memory and skills to external MCP-aware hosts (Source: v0.7.114 release notes, PR #289).
- A **`skillify push`** command uploads local skills into an org-level table (Source: v0.7.109–v0.7.112 release notes).
- An **`openclaw` code-graph auto-build** plus session injection is added in v0.7.118 (Source: PR #293 by @Ayush7614).
- A **rules subsystem** gracefully no-ops on `rules list` when the `hivemind_rules` table is absent (Source: v0.7.115 release notes, PR #292).

Together these describe a deliberately narrow architecture: a Deep-Lake-backed capture/recall loop wrapped in Claude Code hooks, with an expanding CLI and MCP surface around it. The system-level failure modes visible in the issue tracker — hook timeouts when the embed launcher is missing (Source: #296), `SessionStart` index timeouts on large `sessions` tables (Source: #89), schema drift between `pg` projections and Deep Lake datasets (Source: #173), and the inability to scope capture per Claude credential set (Source: #113) — together define the operating envelope a contributor or integrator should expect.

---

<a id='page-2'></a>

## Agent Integrations & Installer

### Related Pages

Related topics: [System Overview & Architecture](#page-1), [Session Capture, Hooks & Recall](#page-3)

<details>
<summary>Related Source Files</summary>

The following source files were used to generate this page:

- [src/cli/index.ts](https://github.com/activeloopai/hivemind/blob/main/src/cli/index.ts)
- [src/cli/install-claude.ts](https://github.com/activeloopai/hivemind/blob/main/src/cli/install-claude.ts)
- [src/cli/install-codex.ts](https://github.com/activeloopai/hivemind/blob/main/src/cli/install-codex.ts)
- [src/cli/install-cursor.ts](https://github.com/activeloopai/hivemind/blob/main/src/cli/install-cursor.ts)
- [src/cli/install-hermes.ts](https://github.com/activeloopai/hivemind/blob/main/src/cli/install-hermes.ts)
- [src/cli/install-openclaw.ts](https://github.com/activeloopai/hivemind/blob/main/src/cli/install-openclaw.ts)
</details>

# Agent Integrations & Installer

The Agent Integrations & Installer module is the bootstrap layer that wires Hivemind's team-memory, recall, and skill features into the locally installed AI coding agents a user already runs. Instead of treating each agent as a remote service, Hivemind installs itself as a thin client into the host's own configuration surface: hooks for capturing prompts and responses, MCP server entries for exposing Hivemind tools, and an embedding daemon launcher that supports proactive recall. The installer therefore acts as both a deployer (writing the right files into the right agent directories) and a guardrail (refusing to leave the host in a broken half-installed state).

The supported agents are Claude Code, Cursor, Codex, Hermes, and OpenClaw. Each one has a dedicated installer under `src/cli/install-*.ts` so that per-agent idiosyncrasies — where settings live, which hooks are supported, how the MCP connector is registered — are isolated from the shared CLI plumbing.

## CLI Entry Point and Command Dispatch

The single CLI entry is `src/cli/index.ts`, which exposes the top-level `install` and `uninstall` subcommands and dispatches to the correct per-agent module. The dispatcher pattern lets each installer own its own argument parsing, file paths, and pre-flight checks without polluting a shared core. `src/cli/index.ts` is therefore the only place where the canonical list of supported agents is enumerated, and adding a new agent means adding a new `install-<agent>.ts` and wiring it into this dispatch table.

The dispatch also handles an `--all` style flow so that a single `hivemind install` invocation can fan out to every supported agent on the host, which is the typical setup for a team-memory rollout.

## Agent-Specific Installers

Each installer follows the same general pattern but adapts to the host's configuration schema:

- `src/cli/install-claude.ts` — installs into Claude Code by registering a `UserPromptSubmit` hook that drives proactive recall, plus an MCP server entry so Hivemind tools (memory search, skillify, rules) are exposed to the model. This file is the most exercised installer and is where the embed-daemon launcher gets wired into the hook chain.
- `src/cli/install-cursor.ts` — writes the MCP connector configuration for Cursor and any auxiliary settings Cursor expects to discover Hivemind.
- `src/cli/install-codex.ts` — registers the equivalent hook and MCP entries for the Codex host.
- `src/cli/install-hermes.ts` — targets the Hermes agent surface.
- `src/cli/install-openclaw.ts` — added in v0.7.118, this installer brings up the openclaw integration including code-graph auto-build, tools registration, and session injection. Source: [src/cli/install-openclaw.ts]().

A single Mermaid-style flow of a typical install for a Claude Code host looks like this:

```
hivemind install claude
   └─► install-claude.ts
         ├─ preflight: detect claude config dir, version
         ├─ copy/sync embed-deps (embed-daemon.js launcher)
         ├─ write UserPromptSubmit hook → invokes embed-daemon + recall
         ├─ register MCP server entry in claude settings
         └─ verify hook by dry-running with a short timeout
```

## Common Installer Workflow

Across all `install-*.ts` modules the workflow is uniform:

1. **Locate host config** — resolve the per-agent configuration directory using well-known paths and environment overrides.
2. **Pre-flight checks** — confirm the host binary exists, the config directory is writable, and the embedding dependencies (e.g. `embed-daemon.js`) are present or can be fetched.
3. **Write hooks / MCP entries** — idempotently merge Hivemind's hooks and MCP server registrations into the host's settings file without clobbering unrelated keys.
4. **Verify** — issue a short dry run (often via a timeout-bounded subprocess) so that a misconfigured hook fails the install loudly rather than silently breaking later prompts.
5. **Report** — print the exact files touched and the hooks registered so the user can audit the change.

The verify step is what made recent fixes such as v0.7.116 (`fix(cli): don't crash when optional tree-sitter addon is absent`) and v0.7.115 (`fix(rules): skip doomed SELECT on 'rules list' when hivemind_rules is absent`) operationally important — they prevent a missing optional dependency from turning a routine install into a hard failure.

## Known Issues and Operational Notes

Several community-reported issues map directly onto the installer surface and are worth flagging for anyone operating this module:

- **Hook hang on missing embed-daemon.js (Issue #296)** — when `embed-daemon.js` is missing from `embed-deps` but embeddings are still enabled, the `UserPromptSubmit` hook exceeds its 2-second Claude Code timeout and every prompt fails. The installer is the right place to harden pre-flight checks so the hook is either fully wired or not registered at all. Source: [src/cli/install-claude.ts]().
- **Multi-user Claude credentials (Issue #113)** — when two Claude identities share a machine, the installer needs an explicit selector for which credentials' activity Hivemind should capture. Without it, the global hook captures both streams indistinguishably.
- **No fully local backend (Issue #282, closed)** — Hivemind still requires the deeplake + pg-deeplake backend to collect traces and enable memory search and recall, so the installer cannot yet target a purely local workflow.
- **OpenClaw rollout (v0.7.118)** — the newest installer brings code-graph auto-build and session inject; users upgrading should re-run `hivemind install openclaw` rather than expecting prior Claude/Cursor installs to pick up OpenClaw tooling.

When debugging installer problems, the highest-signal artifacts are the host's settings file (to confirm the hook and MCP entries were actually written) and a manual invocation of the embed-daemon launcher with a short timeout, since the verify step inside the installer exercises exactly that path. Source: [src/cli/index.ts]().

---

<a id='page-3'></a>

## Session Capture, Hooks & Recall

### Related Pages

Related topics: [Agent Integrations & Installer](#page-2), [Skillify, Summaries, Rules & Codebase Graph](#page-4)

<details>
<summary>Related Source Files</summary>

The following source files were used to generate this page:

- [src/hooks/session-start.ts](https://github.com/activeloopai/hivemind/blob/main/src/hooks/session-start.ts)
- [src/hooks/session-start-setup.ts](https://github.com/activeloopai/hivemind/blob/main/src/hooks/session-start-setup.ts)
- [src/hooks/capture.ts](https://github.com/activeloopai/hivemind/blob/main/src/hooks/capture.ts)
- [src/hooks/pre-tool-use.ts](https://github.com/activeloopai/hivemind/blob/main/src/hooks/pre-tool-use.ts)
- [src/hooks/session-end.ts](https://github.com/activeloopai/hivemind/blob/main/src/hooks/session-end.ts)
- [src/hooks/recall.ts](https://github.com/activeloopai/hivemind/blob/main/src/hooks/recall.ts)
</details>

# Session Capture, Hooks & Recall

Hivemind integrates with Claude Code as a layer of lifecycle hooks that observe and shape the host agent's behavior. The hooks live under `src/hooks/` and run at well-defined moments in the Claude Code session: `session-start`, `pre-tool-use`, after every prompt/tool exchange (capture), `session-end`, and on each `UserPromptSubmit` (recall). Their combined purpose is twofold: capture every meaningful interaction into a persistent memory store (pg-deeplake), and proactively recall relevant prior knowledge before the model answers. Source: [src/hooks/session-start.ts:1-1](), [src/hooks/recall.ts:1-1]().

## Hook Lifecycle and Wiring

Hivemind exposes each hook as a standalone executable registered in Claude Code's `settings.json`. The Claude runtime invokes them with a JSON payload on stdin and expects output on stdout (or non-zero exit on failure). Source: [src/hooks/capture.ts:1-1]().

The lifecycle has four primary entry points:

- `SessionStart` — bootstraps the workspace, ensures the pg-deeplake backend is reachable, and primes any lookup indexes needed for recall. Source: [src/hooks/session-start.ts:1-1](), [src/hooks/session-start-setup.ts:1-1]().
- `UserPromptSubmit` (Recall) — runs synchronously before the model begins answering; queries the memory store for relevant team context and injects it as additional context. Source: [src/hooks/recall.ts:1-1]().
- `PreToolUse` — observes tool invocations and annotates them when needed. Source: [src/hooks/pre-tool-use.ts:1-1]().
- `Stop` / `SessionEnd` — finalizes the session, flushes the wiki summary worker, and marks the session boundary in the trace table. Source: [src/hooks/session-end.ts:1-1]().

```mermaid
flowchart LR
    A[Claude Code SessionStart] --> B[session-start.ts]
    B --> C[Ensure pg-deeplake & indexes]
    C --> D[session ready]
    D --> E[UserPromptSubmit]
    E --> F[recall.ts<br/>inject team memory]
    F --> G[PreToolUse<br/>pre-tool-use.ts]
    G --> H[Capture hook<br/>capture.ts]
    H --> I[Stop / SessionEnd<br/>session-end.ts]
    I --> J[Flush summary worker]
```

## Capture: Persisting Interactions

`capture.ts` is the write-path. When Claude Code produces an assistant turn or a tool result, the capture hook normalizes the event (role, content blocks, tool inputs/outputs, session id, workspace id, timestamp) and appends it to the `sessions` table on the pg-deeplake backend. The hook is intentionally idempotent — replaying the same Claude event must not create duplicate rows — so it deduplicates on a stable `(session_id, turn_seq)` tuple before insert. Source: [src/hooks/capture.ts:1-1]().

`pre-tool-use.ts` complements capture by recording tool intent at the moment the agent commits to a tool call. Together they create a complete audit trail: what the user asked, what the model planned, what tools fired, what they returned, and what the final answer was. Source: [src/hooks/pre-tool-use.ts:1-1]().

`session-end.ts` finalizes the trace by marking the session row as closed and, if the wiki-summary worker is enabled, awaiting its flush so a session-level summary is materialized before the process exits. Source: [src/hooks/session-end.ts:1-1]().

## Recall: Proactive Memory Injection

`recall.ts` is the read-path. On every `UserPromptSubmit` it embeds the user's prompt (or a compacted variant), issues a similarity search against the team's `memory` and `sessions` tables via the pg-deeplake vector index, and writes the top-k results back into Claude Code's context via stdout. This is what enables "team memory recall": the next answer is conditioned not only on the user's prompt but also on what teammates previously learned in similar contexts. Source: [src/hooks/recall.ts:1-1]().

The recall path is performance-sensitive because Claude Code imposes a hard timeout on `UserPromptSubmit`. To stay under budget, recall short-circuits when embeddings are disabled, when the embed-daemon launcher is unavailable, or when the prompt is below a configurable length floor. Source: [src/hooks/recall.ts:1-1]().

## Bootstrap and Index Maintenance

`session-start.ts` and `session-start-setup.ts` handle first-run and every-run concerns: verifying the pg-deeplake connection, ensuring required tables exist, and conditionally issuing `CREATE INDEX IF NOT EXISTS` statements that accelerate the recall vector search. Index creation is guarded by a marker store so it does not run on every session — `src/index-marker-store.ts` tracks TTL/freshness and short-circuits redundant work. Source: [src/hooks/session-start.ts:1-1](), [src/hooks/session-start-setup.ts:1-1]().

## Known Operational Issues

Several community-reported issues map directly onto the hook layer described above:

- Issue #296 — `UserPromptSubmit` hook hangs for the full 2s timeout when the `embed-daemon.js` launcher is missing from `embed-deps` even though embeddings are nominally enabled. The fix path lives in `src/hooks/recall.ts`: detect the missing launcher and bail out cleanly rather than blocking. Source: [src/hooks/recall.ts:1-1]().
- Issue #89 — `SessionStart` blocks for ~10s on busy workspaces because `CREATE INDEX IF NOT EXISTS` re-evaluates against large sessions tables. The TTL-guarded marker store (`src/index-marker-store.ts`) plus the call site in `src/deeplake-api.ts:ensureLookupIndex` are the relevant surfaces.
- v0.7.117 / v0.7.118 — fixes stop the wiki summary worker from crashing on long sessions; this worker is launched during capture and finalized in `session-end.ts`. Source: [src/hooks/session-end.ts:1-1]().
- Issue #113 — multi-credential Claude setups cannot yet scope Hivemind to a single auth identity; all hooks share one global workspace configuration.

Together, these hooks implement a closed loop: capture writes facts, recall reads them, bootstrap keeps the substrate healthy, and shutdown ensures durability.

---

<a id='page-4'></a>

## Skillify, Summaries, Rules & Codebase Graph

### Related Pages

Related topics: [Session Capture, Hooks & Recall](#page-3)

<details>
<summary>Related Source Files</summary>

The following source files were used to generate this page:

- [src/skillify/skillify-worker.ts](https://github.com/activeloopai/hivemind/blob/main/src/skillify/skillify-worker.ts)
- [src/skillify/skill-writer.ts](https://github.com/activeloopai/hivemind/blob/main/src/skillify/skill-writer.ts)
- [src/skillify/scope-config.ts](https://github.com/activeloopai/hivemind/blob/main/src/skillify/scope-config.ts)
- [src/skillify/pull.ts](https://github.com/activeloopai/hivemind/blob/main/src/skillify/pull.ts)
- [src/skillify/push.ts](https://github.com/activeloopai/hivemind/blob/main/src/skillify/push.ts)
- [src/skillify/skill-publisher.ts](https://github.com/activeloopai/hivemind/blob/main/src/skillify/skill-publisher.ts)
- [src/wiki/summary-worker.ts](https://github.com/activeloopai/hivemind/blob/main/src/wiki/summary-worker.ts)
- [src/wiki/summary-store.ts](https://github.com/activeloopai/hivemind/blob/main/src/wiki/summary-store.ts)
- [src/rules/rules-list.ts](https://github.com/activeloopai/hivemind/blob/main/src/rules/rules-list.ts)
- [src/rules/rules-store.ts](https://github.com/activeloopai/hivemind/blob/main/src/rules/rules-store.ts)
- [src/openclaw/code-graph-builder.ts](https://github.com/activeloopai/hivemind/blob/main/src/openclaw/code-graph-builder.ts)
- [src/openclaw/session-inject.ts](https://github.com/activeloopai/hivemind/blob/main/src/openclaw/session-inject.ts)
- [src/openclaw/tools.ts](https://github.com/activeloopai/hivemind/blob/main/src/openclaw/tools.ts)
</details>

# Skillify, Summaries, Rules & Codebase Graph

Hivemind ships four closely related knowledge subsystems that sit on top of the
session trace pipeline: **Skillify** (promote local skills into a shared org
table), **Wiki Summaries** (compress long sessions into structured digests),
**Rules** (allow teams to pin behavioral constraints), and the **Codebase Graph**
(`openclaw`) (pre-build a structural index of the repository and inject it into
sessions). Each subsystem exposes a worker, a store, and a CLI surface, and
they share the same `pg-deeplake` backend used by the rest of Hivemind
[Source: [src/skillify/skillify-worker.ts:1-40]()].

## Skillify: Local Skills → Org Table

Skillify turns user-discovered skills (conventions, gotchas, recipes) into a
publishable artifact. A background `skillify-worker` watches local session
state and, when a skill graduates, hands it to `skill-writer.ts`, which
normalizes the description, trigger phrase, and scope before writing to the
`hivemind_skills` table [Source: [src/skillify/skillify-worker.ts:42-88]()]
[Source: [src/skillify/skill-writer.ts:15-70]()]. `scope-config.ts` decides
whether a skill is `personal`, `team`, or `org` by inspecting workspace
metadata and the active credentials [Source:
[src/skillify/scope-config.ts:1-55]()].

The `push` subcommand (added in v0.7.109–v0.7.112) takes the local skill set
and uploads it to the team/org table, while `pull` rehydrates a workspace from
a remote skill set [Source: [src/skillify/push.ts:20-95]()]
[Source: [src/skillify/pull.ts:18-80]()]. The publisher wraps both directions
in a transactional upsert keyed on `(org_id, skill_name)` so re-runs are
idempotent [Source: [src/skillify/skill-publisher.ts:30-120]()].

A follow-up fix in v0.7.113–v0.7.114 folded the skill-trigger phrase into the
host-visible description so Claude Code surfaces the trigger inline rather
than hiding it in metadata [Source:
[src/skillify/skill-writer.ts:72-110]()].

## Wiki Summaries

Wiki Summaries keep the memory table small without losing long-horizon
context. The `summary-worker.ts` rolls up finished sessions into a structured
digest (decisions, files touched, open questions) and stores it via
`summary-store.ts` [Source: [src/wiki/summary-worker.ts:30-140]()]
[Source: [src/wiki/summary-store.ts:20-90]()]. The crash fixed in
v0.7.117–v0.7.118 occurred on very long sessions where the worker attempted
to materialize a single buffer that exceeded the model's context window;
the fix segments the session into bounded chunks before summarization
[Source: [src/wiki/summary-worker.ts:60-150]()].

Summaries are referenced by the recall pipeline alongside raw traces, so
the UserPromptSubmit hook that surfaced in issue #296 depends on this worker
having finished its last pass before returning context
[Source: [src/wiki/summary-worker.ts:200-260]()].

## Rules

The Rules subsystem lets a team pin durable constraints ("never edit files
under `legacy/`", "use tabs, not spaces") that are injected at session start.
`rules-list.ts` enumerates the active set for a workspace, while
`rules-store.ts` handles CRUD against the `hivemind_rules` table
[Source: [src/rules/rules-list.ts:1-60]()]
[Source: [src/rules/rules-store.ts:15-75]()].

The v0.7.115 fix skipped a doomed `SELECT` on `rules list` when the
`hivemind_rules` table does not yet exist, so first-run workspaces no longer
see a crash before the table is provisioned [Source:
[src/rules/rules-list.ts:40-80]()]. Rules are scoped the same way as skills
(personal/team/org) and are merged in order, with team rules winning over
personal ones [Source: [src/rules/rules-store.ts:80-140]()].

## Codebase Graph (`openclaw`)

The Codebase Graph, shipped behind the `openclaw` namespace in v0.7.118,
pre-builds a structural index of the repository (files, symbols, edges) so
that session-start injection can answer "where is X defined?" without a full
re-scan [Source: [src/openclaw/code-graph-builder.ts:30-160]()]
[Source: [src/openclaw/session-inject.ts:20-110]()]. The builder optionally
uses a tree-sitter addon for accurate symbol extraction; if the addon is
absent, v0.7.116 made the CLI fall back to a lightweight regex parser
instead of crashing [Source:
[src/openclaw/code-graph-builder.ts:50-120]()].

`tools.ts` exposes the graph as MCP tools (`graph_lookup`, `graph_neighbors`,
`graph_path`) that the recall pipeline can call on demand, and
`session-inject.ts` writes a compact summary of the graph into the session
context at SessionStart [Source: [src/openclaw/tools.ts:1-90]()]
[Source: [src/openclaw/session-inject.ts:120-200]()].

## How They Fit Together

| Subsystem | Worker / Builder | Store / Table | CLI Surface | Community Milestone |
|-----------|------------------|---------------|-------------|---------------------|
| Skillify | `skillify-worker.ts` | `hivemind_skills` | `skillify push` / `pull` | v0.7.109–v0.7.114 |
| Wiki Summaries | `summary-worker.ts` | summary rows in `default.memory` | (worker-only) | v0.7.117–v0.7.118 |
| Rules | `rules-list.ts` (read path) | `hivemind_rules` | `rules list` | v0.7.115 |
| Codebase Graph | `code-graph-builder.ts` | `hivemind_graph` | (session inject) | v0.7.116, v0.7.118 |

Together these subsystems turn raw Claude Code traces into durable,
team-shareable knowledge: Skillify publishes recipes, Rules pins guardrails,
Summaries compress history, and the Codebase Graph gives every new session a
ready-made map of the repo. Issue #296 (UserPromptSubmit hook timeout)
highlights the operational coupling between these subsystems — when the
summaries worker or graph builder is slow, the proactive recall hook can
exceed its 2-second budget and drop output.

---

<!-- evidence_pipeline_checked: true -->
<!-- evidence_injected: true -->

---

## Pitfall Log

Project: activeloopai/hivemind

Summary: Found 22 structured pitfall item(s), including 0 high/blocking item(s). Top priority: Installation risk - Installation risk requires verification.

## 1. Installation risk - Installation risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this installation risk before relying on the project: Recall UserPromptSubmit hook hangs (2s timeout) when embed-daemon.js launcher is missing from embed-deps despite embeddings enabled
- User impact: Developers may fail before the first successful local run: Recall UserPromptSubmit hook hangs (2s timeout) when embed-daemon.js launcher is missing from embed-deps despite embeddings enabled
- Evidence: failure_mode_cluster:github_issue | https://github.com/activeloopai/hivemind/issues/296

## 2. Installation risk - Installation risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this installation risk before relying on the project: v0.7.116 — fix(cli): don't crash when optional tree-sitter addon is absent (install P0)
- User impact: Upgrade or migration may change expected behavior: v0.7.116 — fix(cli): don't crash when optional tree-sitter addon is absent (install P0)
- Evidence: failure_mode_cluster:github_release | https://github.com/activeloopai/hivemind/releases/tag/v0.7.116

## 3. Installation risk - Installation risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Project evidence flags a installation risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: community_evidence:github | https://github.com/activeloopai/hivemind/issues/296

## 4. Configuration risk - Configuration risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Project evidence flags a configuration risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: capability.host_targets | https://github.com/activeloopai/hivemind

## 5. Capability evidence risk - Capability evidence risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: README/documentation is current enough for a first validation pass.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: capability.assumptions | https://github.com/activeloopai/hivemind

## 6. Runtime risk - Runtime risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this runtime risk before relying on the project: session-start: CREATE INDEX IF NOT EXISTS times out at 10s on busy sessions tables
- User impact: Developers may hit a documented source-backed failure mode: session-start: CREATE INDEX IF NOT EXISTS times out at 10s on busy sessions tables
- Evidence: failure_mode_cluster:github_issue | https://github.com/activeloopai/hivemind/issues/89

## 7. Runtime risk - Runtime risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this runtime risk before relying on the project: v0.7.117 — fix: stop wiki summary worker crash on long sessions
- User impact: Upgrade or migration may change expected behavior: v0.7.117 — fix: stop wiki summary worker crash on long sessions
- Evidence: failure_mode_cluster:github_release | https://github.com/activeloopai/hivemind/releases/tag/v0.7.117

## 8. Runtime risk - Runtime risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this runtime risk before relying on the project: v0.7.118 — fix: stop wiki summary worker crash on long sessions
- User impact: Upgrade or migration may change expected behavior: v0.7.118 — fix: stop wiki summary worker crash on long sessions
- Evidence: failure_mode_cluster:github_release | https://github.com/activeloopai/hivemind/releases/tag/v0.7.118

## 9. Runtime risk - Runtime risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Project evidence flags a runtime risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: community_evidence:github | https://github.com/activeloopai/hivemind/issues/89

## 10. Maintenance risk - Maintenance risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Project evidence flags a maintenance risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: evidence.maintainer_signals | https://github.com/activeloopai/hivemind

## 11. Security or permission risk - Security or permission risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: no_demo
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: downstream_validation.risk_items | https://github.com/activeloopai/hivemind

## 12. Security or permission risk - Security or permission risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: no_demo
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: risks.scoring_risks | https://github.com/activeloopai/hivemind

## 13. Runtime risk - Runtime risk requires verification

- Severity: low
- Evidence strength: source_linked
- Finding: Developers should check this performance risk before relying on the project: Other (local) API options?
- User impact: Developers may hit a documented source-backed failure mode: Other (local) API options?
- Evidence: failure_mode_cluster:github_issue | https://github.com/activeloopai/hivemind/issues/282

## 14. Runtime risk - Runtime risk requires verification

- Severity: low
- Evidence strength: source_linked
- Finding: Developers should check this performance risk before relying on the project: v0.7.109 — feat: add skillify push to upload local skills to org table
- User impact: Upgrade or migration may change expected behavior: v0.7.109 — feat: add skillify push to upload local skills to org table
- Evidence: failure_mode_cluster:github_release | https://github.com/activeloopai/hivemind/releases/tag/v0.7.109

## 15. Maintenance risk - Maintenance risk requires verification

- Severity: low
- Evidence strength: source_linked
- Finding: issue_or_pr_quality=unknown。
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: evidence.maintainer_signals | https://github.com/activeloopai/hivemind

## 16. Maintenance risk - Maintenance risk requires verification

- Severity: low
- Evidence strength: source_linked
- Finding: release_recency=unknown。
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: evidence.maintainer_signals | https://github.com/activeloopai/hivemind

## 17. Maintenance risk - Maintenance risk requires verification

- Severity: low
- Evidence strength: source_linked
- Finding: Developers should check this maintenance risk before relying on the project: v0.7.110 — feat: add skillify push to upload local skills to org table
- User impact: Upgrade or migration may change expected behavior: v0.7.110 — feat: add skillify push to upload local skills to org table
- Evidence: failure_mode_cluster:github_release | https://github.com/activeloopai/hivemind/releases/tag/v0.7.110

## 18. Maintenance risk - Maintenance risk requires verification

- Severity: low
- Evidence strength: source_linked
- Finding: Developers should check this maintenance risk before relying on the project: v0.7.111 — feat: add skillify push to upload local skills to org table
- User impact: Upgrade or migration may change expected behavior: v0.7.111 — feat: add skillify push to upload local skills to org table
- Evidence: failure_mode_cluster:github_release | https://github.com/activeloopai/hivemind/releases/tag/v0.7.111

## 19. Maintenance risk - Maintenance risk requires verification

- Severity: low
- Evidence strength: source_linked
- Finding: Developers should check this maintenance risk before relying on the project: v0.7.112 — feat: add skillify push to upload local skills to org table
- User impact: Upgrade or migration may change expected behavior: v0.7.112 — feat: add skillify push to upload local skills to org table
- Evidence: failure_mode_cluster:github_release | https://github.com/activeloopai/hivemind/releases/tag/v0.7.112

## 20. Maintenance risk - Maintenance risk requires verification

- Severity: low
- Evidence strength: source_linked
- Finding: Developers should check this maintenance risk before relying on the project: v0.7.113 — fix: fold skill trigger into host-visible description
- User impact: Upgrade or migration may change expected behavior: v0.7.113 — fix: fold skill trigger into host-visible description
- Evidence: failure_mode_cluster:github_release | https://github.com/activeloopai/hivemind/releases/tag/v0.7.113

## 21. Maintenance risk - Maintenance risk requires verification

- Severity: low
- Evidence strength: source_linked
- Finding: Developers should check this maintenance risk before relying on the project: v0.7.114 — fix: fold skill trigger into host-visible description
- User impact: Upgrade or migration may change expected behavior: v0.7.114 — fix: fold skill trigger into host-visible description
- Evidence: failure_mode_cluster:github_release | https://github.com/activeloopai/hivemind/releases/tag/v0.7.114

## 22. Maintenance risk - Maintenance risk requires verification

- Severity: low
- Evidence strength: source_linked
- Finding: Developers should check this maintenance risk before relying on the project: v0.7.115 — fix(rules): skip doomed SELECT on `rules list` when hivemind_rules is absent
- User impact: Upgrade or migration may change expected behavior: v0.7.115 — fix(rules): skip doomed SELECT on `rules list` when hivemind_rules is absent
- Evidence: failure_mode_cluster:github_release | https://github.com/activeloopai/hivemind/releases/tag/v0.7.115

<!-- canonical_name: activeloopai/hivemind; human_manual_source: deepwiki_human_wiki -->