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

> Learn the syntax for writing rules in Hivemind. Understand structure, validation, and CLI usage for effective rule management. Get started with Hivemind rules today.

- Repository: [Activeloop/hivemind](https://github.com/activeloopai/hivemind)
- Tags: how-to-guide
- Published: 2026-06-11

---

**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`](https://github.com/activeloopai/hivemind/blob/main/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`](https://github.com/activeloopai/hivemind/blob/main/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`](https://github.com/activeloopai/hivemind/blob/main/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`](https://github.com/activeloopai/hivemind/blob/main/src/commands/rules.ts) provides direct access to the write operations. All commands automatically populate the `assigned_by` field from your authentication context.

```bash

# 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`](https://github.com/activeloopai/hivemind/blob/main/src/rules/write.ts) and instantiate a `DeeplakeApi` client from [`src/deeplake-api.ts`](https://github.com/activeloopai/hivemind/blob/main/src/deeplake-api.ts).

```typescript
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`](https://github.com/activeloopai/hivemind/blob/main/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`](https://github.com/activeloopai/hivemind/blob/main/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.