Syntax for Writing Rules in Hivemind: Structure, Validation, and CLI Usage

Hivemind rules are single-line text strings (maximum 2000 characters) written to an append-only hivemind_rules table, created and modified via the insertRule, editRule, and markRuleDone functions in src/rules/write.ts or through the hivemind rules CLI commands.

The activeloopai/hivemind library stores project guidelines as structured text entries in Deeplake. Understanding the syntax for writing rules in Hivemind requires familiarity with the validation constraints defined in the source code, the required fields for rule creation, and the append-only write pattern that preserves complete version history.

Rule Text Format and Validation Constraints

Every rule in Hivemind is stored as a single line of plain text. The library enforces strict validation through the assertValidText function located in src/rules/write.ts (lines 65-77).

Key constraints:

• Single-line only: The text must not contain any newline characters
• Length limit: Maximum 2000 characters per rule
• Plain text: No special formatting or markup is required

When validation fails, the function throws an error before any database operation occurs, ensuring data integrity in the hivemind_rules table.

Required Fields and Data Structure

The syntax for writing rules in Hivemind is defined by the InsertRuleInput and EditRuleInput TypeScript types. These interfaces specify which fields are mandatory and which use defaults.

Field	Description	Required
text	The rule body (single-line string, max 2000 chars)	Yes
assigned_by	Email of the user creating or editing the rule	Yes
agent	Creator identifier ("manual" for CLI, custom for plugins)	No (defaults to "manual")
plugin_version	Version string of the writing plugin	No
status	"active" or "done"	No (defaults to "active" on insert)
rule_id	Stable UUID of the rule	No on insert, Yes on edit

The system automatically generates a UUID for rule_id and sets version to 1 when inserting new rules.

Rule Lifecycle Operations

Hivemind implements an append-only write pattern. According to comments in src/rules/write.ts (lines 6-9), Deeplake silently coalesces rapid updates, which would destroy audit information if traditional UPDATE statements were used. Instead, the library provides three core helpers:

Creating Rules with insertRule

The insertRule function appends a new row to the hivemind_rules table with version = 1 and status = "active".

Versioning Rules with editRule

The editRule function reads the latest version of a specified rule, merges any supplied fields into a new entry, and increments the version number (version + 1). This preserves the complete history of changes.

Archiving Rules with markRuleDone

markRuleDone is a convenience wrapper around editRule that specifically sets status: "done", effectively marking a rule as completed without modifying its text.

CLI Syntax for Managing Rules

The hivemind rules command surface in src/commands/rules.ts provides direct access to the write operations. All commands automatically populate the assigned_by field from your authentication context.

# Add a new rule (team-wide scope is currently the only supported value)

hivemind rules add "Never expose API keys in plain text"

# List the most recent active rules (default limit = 10)

hivemind rules list

# List all rules including completed ones, limiting to 20 entries

hivemind rules list --status all --limit 20

# Edit the text of an existing rule (replace <RULE_ID> with the UUID from list)

hivemind rules edit <RULE_ID> "Never expose API keys or secrets in plain text"

# Mark a rule as completed

hivemind rules done <RULE_ID>

Programmatic Write API

For custom integrations, import the write helpers directly from src/rules/write.ts and instantiate a DeeplakeApi client from src/deeplake-api.ts.

import { insertRule, editRule, markRuleDone } from "hivemind/src/rules/write.js";
import { DeeplakeApi } from "hivemind/src/deeplake-api.js";

const api = new DeeplakeApi(token, apiUrl, orgId, workspaceId, tableName);
const table = "hivemind_rules";

// Insert a new rule
await insertRule(api.query.bind(api), table, {
  text: "All code must be linted before merge",
  assigned_by: "alice@example.com",
});

// Edit an existing rule
await editRule(api.query.bind(api), table, {
  rule_id: "<RULE_ID>",
  text: "All code must be linted and type-checked before merge",
  assigned_by: "bob@example.com",
});

// Mark rule as done
await markRuleDone(api.query.bind(api), table, {
  rule_id: "<RULE_ID>",
  assigned_by: "bob@example.com",
});

Summary

• Validation: Rules must pass assertValidText in src/rules/write.ts, enforcing single-line text under 2000 characters with no newlines.
• Fields: Required fields are text and assigned_by; optional fields include agent, plugin_version, and status.
• Architecture: All writes are append-only operations (insertRule, editRule, markRuleDone) to preserve version history in the hivemind_rules table.
• CLI: The hivemind rules commands provide add, edit, and done subcommands for manual rule management.
• API: Programmatic access requires binding a DeeplakeApi query instance to the write helpers.

Frequently Asked Questions

What is the maximum length of a Hivemind rule?

Hivemind rules are limited to 2000 characters. This constraint is enforced by the assertValidText validation function in src/rules/write.ts (lines 65-77), which rejects any text exceeding this limit before writing to the database.

Can I use multiline strings for Hivemind rules?

No. The validation logic explicitly prohibits newline characters. The assertValidText function checks for newline characters and throws an error if present, ensuring all rules remain single-line strings suitable for the append-only table structure.

How does Hivemind track rule versions?

Hivemind uses append-only versioning. When a rule is first created, insertRule assigns it version = 1. Subsequent edits via editRule do not modify the existing row; instead, they insert a new row with an incremented version number (version + 1). This pattern preserves the complete audit trail of all changes.

What is the difference between editRule and markRuleDone?

editRule is a general-purpose function that merges any provided fields (such as updated text or assigned_by) into a new version of the rule. markRuleDone is a specialized convenience wrapper that calls editRule internally but specifically sets status: "done" to mark a rule as completed without requiring manual field construction.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}