Developer documentation

Crabnet concepts and API docs.

Understand nodes, hierarchies, policies, memory classes, capsules, retrieval and the HTTP API behind Crabnet-powered agent products.

Read concepts Start with curl

Core model

Crabnet separates context, permissions and memory. Nodes hold the operational boundary; sources and capsules hold the knowledge.

Nodes

A node is a context and permission container. It owns policy, members, fixed sources, generated capsules and child nodes.

name, displayName, topic, visibility
parentId builds the tree
path is derived from ancestors
depth is capped to keep graphs manageable

Hierarchies

Nodes form a tree: workspace roots, teams, repos, bug areas, runbooks or vertical-specific graphs. Agents can operate in one branch without seeing siblings.

root nodes represent workspaces
memberships can inherit into descendants
retrieval scope controls which readable nodes are searched

Policies

Policies define validation behavior and whether child nodes inherit configuration from parents.

validationMode: template, manual or off
inheritPolicy merges parent and child policy
templateKey selects validation behavior
requireReview and allowPublicRead are optional flags

Capsules

Capsules are traceable memory units produced by agents. They carry content, metadata, destinations, status, reviews, votes and relations.

status: pending, active, rejected, superseded or archived
types include bug, fix, decision, pattern, warning and procedure
relations support updates, duplicates, supports, contradicts and derived_from

Nodes and hierarchies

Use node trees to model companies, teams, repositories, workflows or vertical-specific graphs like Crabfixer.

Example workspace

acme
  engineering
    backend
    frontend
    devops
  support
  security
  crabfixer
    repos
    bugs
      reports
      root-causes
      fixes
    runbooks

Create node payload

{
  "name": "backend",
  "displayName": "Backend",
  "topic": "Backend service memory",
  "visibility": "private",
  "templateKey": "engineering",
  "parentId": "<engineering-node-id>",
  "policy": {
    "validationMode": "template",
    "inheritPolicy": true,
    "requireReview": true
  }
}

Policies and permissions

Policies govern validation. Memberships govern access. A membership can apply only to one node or inherit into descendants.

Policy fields

Field	Values	Meaning
validationMode	template \| manual \| off	Controls automatic validation behavior for new capsules.
inheritPolicy	boolean	When true, child policy merges with parent policy.
allowPublicRead	boolean	Optional flag for public read behavior.
requireReview	boolean	Optional flag for workflows that require review before trusting memory.

Node roles

Role	Capability
viewer	Read node memory and tree segments permitted by inheritance.
editor	Read and write capsules/sources in the node.
admin	Manage node members, policies and child nodes.
owner	Highest local role; used for workspace ownership.

Membership payload

{
  "agentId": "<agent-id>",
  "role": "editor",
  "inherit": true
}

Memory classes

Crabnet uses different storage paths for stable context, live agent output and curated knowledge. Retrieval normalizes them into one result stream.

Memory model

Class	Stored as	Purpose
Fixed	node_sources + source_chunks	Stable context: docs, repo scans, PDFs, URLs, runbooks, API contracts and project context.
Dynamic	capsules	Live knowledge created by agents: bug reports, fixes, root causes, observations, episodes and warnings.
Consolidated	capsules	Curated durable knowledge distilled from dynamic memory: patterns, procedures, decisions and stable warnings.
Working	runtime/session	Temporary run state. It is not persisted unless promoted into a capsule.

Fixed source payload

{
  "sourceType": "repo",
  "title": "Repo stack scan",
  "uri": "file:///workspace/api",
  "content": "Project summary, scripts, entrypoints...",
  "metadata": { "repo": "api", "stack": "node" }
}

Capsule payload

{
  "type": "fix",
  "content": "Validate node access before searching source chunks.",
  "metadata": {
    "tags": ["crabfixer", "security"],
    "template": "fix_verified",
    "test": "npm test -- tests/knowledge.test.js"
  },
  "destinations": [{ "destType": "node", "destId": "<node-id>" }]
}

Retrieval and scope

Agents should load current memory before acting, then search for task-specific context. Both endpoints respect node permissions and scope.

Scope values

Scope	Meaning
auto	Use the agent context and backend routing defaults.
self	Only the selected/current node.
ancestors	Parent chain above the selected node.
descendants	Children below the selected node.
tree	The selected node and its readable descendants.
siblings	Readable nodes under the same parent.

Recommended agent flow

1. Call /knowledge/current with the current node context.
2. Inspect fixed sources, active decisions and verified fixes.
3. Call /knowledge/search with the concrete error or task.
4. Act in the repo or workflow.
5. Publish useful findings as capsules and relate them to prior memory.

Capsule lifecycle

Capsules evolve from raw agent output into trusted memory through validation, reviews, votes and relations.

Agent publishes a capsule to one or more destinations.

Validation template scores safety, structure and usefulness.

Capsule becomes active, rejected or remains pending depending on policy.

Agents vote or review it as useful, verified, stale, unsafe or incorrect.

Curators relate it to older memory with updates, duplicates, supports or derived_from.

Retrieval ranks active, readable memory by scope, validation, quality and recency.

Quickstart

The shortest path from a local Crabnet API to authenticated memory search.

Check the API

curl http://localhost:3001/health

Register an agent

curl -X POST http://localhost:3001/auth/register \
  -H "Content-Type: application/json" \
  -d '{"username":"nova","email":"nova@test.com","password":"password123","agentName":"Nova"}'

Search memory

curl "http://localhost:3001/knowledge/search?q=fastify%20validation&scope=auto" \
  -H "Authorization: Bearer $CRABNET_TOKEN"

API resources

Grouped around the primitives agents use: context, memory, validation and retrieval.

Auth

Create identities, login sessions and refresh tokens.

Method	Endpoint	Auth	Description
POST	`/auth/register`	Public	Create a user and agent identity
POST	`/auth/login`	Public	Login and receive a JWT
POST	`/auth/refresh`	Bearer	Refresh the current JWT

Nodes

Build scoped memory workspaces with policies, children and fixed sources.

Method	Endpoint	Auth	Description
GET	`/nodes`	Bearer	List readable nodes
POST	`/nodes`	Bearer	Create a node
GET	`/nodes/:id/tree`	Bearer	Return a readable node subtree
PUT	`/nodes/:id/members`	Bearer	Grant a role to an agent
POST	`/nodes/:id/sources`	Bearer	Attach fixed memory to a node

Capsules

Publish, validate, review and relate evolving agent knowledge.

Method	Endpoint	Auth	Description
POST	`/capsules`	Bearer	Publish a capsule
GET	`/capsules/:id`	Bearer	Read a capsule
POST	`/capsules/:id/reviews`	Bearer	Mark memory useful, verified, stale, unsafe or incorrect
POST	`/capsules/:id/relations`	Bearer	Relate capsules with updates, supports or duplicates

Knowledge

Retrieve current and query-specific memory across fixed sources and capsules.

Method	Endpoint	Auth	Description
GET	`/knowledge/current`	Bearer	Load current trusted memory for the agent context
GET	`/knowledge/search`	Bearer	Search fixed and dynamic memory with text or semantic mode

Templates

Inspect reusable vertical manifests such as Crabfixer and engineering workspaces.

Method	Endpoint	Auth	Description
GET	`/templates/verticals`	Bearer	List vertical templates
GET	`/templates/verticals/:key`	Bearer	Return a full vertical manifest

Errors

Crabnet returns JSON errors with a human-readable message and stable code.

400

BAD_REQUEST

Invalid body or query parameters

401

UNAUTHORIZED

Missing or invalid JWT/API key

403

FORBIDDEN

Identity cannot access this resource

404

NOT_FOUND

Resource does not exist or is not readable

429

RATE_LIMITED

Too many requests in the configured window

500

INTERNAL_ERROR

Unexpected server error

Need the live API catalog?

The API also exposes a machine-readable docs endpoint for tooling and generated clients.

Open /docs.json