Commands Reference

Global Flags

Flag	Env Var	Default	Description
--endpoint	HEBBS_ENDPOINT	(from login)	Server URL
--api-key	HEBBS_API_KEY	(from login)	API key for authentication
--workspace	HEBBS_WORKSPACE	(from config)	Workspace slug to route requests to
--format		human	Output format: human, json, raw
--color		auto	Color: always, never, auto
-v / -vv		off	Verbose / trace logging

When --workspace is set, data-plane requests (recall, remember, forget, push, etc.) route to /v1/workspaces/<slug>/... instead of /v1/.... This lets an admin key target any workspace without switching keys.

Precedence: --workspace flag > HEBBS_WORKSPACE env var > saved default (from workspaces switch).

---

Connection

login

Connect to a HEBBS server. Saves endpoint and API key for subsequent commands.

hebbs login --endpoint http://your-server:8080 --api-key hb_live_sk_...

Flag	Required	Description
--endpoint	Yes	Server URL
--api-key	No	API key (can also use HEBBS_API_KEY env var)

status

Check server health.

hebbs status

---

File Upload

push

Upload files to the server for indexing.

hebbs push ./your-docs              # upload a directory
hebbs push ./notes/meeting.md       # upload a single file

Finds all .md, .txt, and .pdf files recursively (skips hidden files). Unchanged files are skipped on the server via checksum comparison.

---

Memory Commands

remember

Store a new memory.

hebbs remember "Customer prefers email over phone" \
  --importance 0.8 \
  --entity-id customer-42

Flag	Short	Default	Description
content (positional)			Memory content text
--importance	-i	0.5	Importance score (0.0 to 1.0)
--entity-id	-e		Entity scope
--context	-c		Metadata as JSON (e.g. '{"source":"email"}')
--edge			Graph edge (repeatable). Format: TARGET_ID:EDGE_TYPE[:CONFIDENCE]

recall

Search for relevant memories.

hebbs recall "How does the customer prefer to be contacted?" \
  --strategy similarity \
  --top-k 5

Core Flags

Flag	Short	Default	Description
cue (positional)			Natural language query
--strategy	-s	similarity	similarity, temporal, causal, analogical
--top-k	-k	10	Maximum results
--entity-id	-e		Entity scope (required for temporal)
--weights	-w	0.5:0.2:0.2:0.1	Composite scoring: Relevance:Recency:Importance:Reinforcement

Strategy-Specific Flags

Flag	Strategy	Default	Description
--ef-search	similarity	50	HNSW candidate count
--time-range	temporal	unbounded	Bounds as START_US:END_US (microsecond timestamps)
--seed	causal	auto	Starting memory ID for graph traversal
--max-depth	causal	5	Maximum hops from seed
--edge-types	causal	all	Edge types to follow: caused_by, followed_by, related_to, revised_from, insight_from
--analogical-alpha	analogical	0.5	0.0 = structural, 1.0 = embedding similarity

Composite Scoring (--weights)

Every result has a composite score blending four signals:

Signal	Position	What it measures
Relevance	1st	Cosine similarity between query and memory
Recency	2nd	How recently the memory was created
Importance	3rd	Memory’s importance value
Reinforcement	4th	How often the memory has been recalled

hebbs recall "Acme meeting" --weights 1:0:0:0       # pure semantic
hebbs recall "Acme meeting" --weights 0.2:0.6:0.1:0.1  # recency-biased
hebbs recall "contract" --weights 0.3:0.1:0.5:0.1      # importance-biased

get

Retrieve a single memory by ID.

hebbs get 01KK3S0KXYE22EFF489YRTH559

revise

Update an existing memory with lineage tracking.

hebbs revise 01KK3S0KXYE22EFF489YRTH559 \
  --content "Customer now prefers Slack over email" \
  --importance 0.9

Flag	Short	Description
id (positional)		Memory ID to revise
--content	-C	Updated content
--importance	-i	Updated importance
--entity-id	-e	Updated entity ID

forget

Remove memories matching criteria.

hebbs forget --entity-id customer-42                # all memories for an entity
hebbs forget --ids 01KK3S0KXYE22EFF489YRTH559      # specific memory
hebbs forget --staleness-us 2592000000000           # older than 30 days
hebbs forget --decay-floor 0.1                      # low-value memories

Flag	Short	Description
--ids	-i	Specific memory IDs (repeatable)
--entity-id	-e	Entity scope
--staleness-us		Remove memories older than N microseconds
--decay-floor		Remove memories with decay score below this

At least one filter must be provided.

prime

Pre-load context for an entity.

hebbs prime acme-corp --max-memories 20

Flag	Short	Description
entity_id (positional)		Entity ID to prime
--max-memories	-m	Maximum memories to return
--similarity-cue		Text cue for similarity-based selection

reflect

Trigger a reflection cycle: clustering, insight generation, validation.

hebbs reflect --entity-id customer-42

Flag	Short	Description
--entity-id	-e	Entity scope (omit for global)

insights

Retrieve consolidated insights from reflection.

hebbs insights --entity-id customer-42 --max-results 5 --min-confidence 0.7

Flag	Short	Description
--entity-id	-e	Filter by entity
--min-confidence	-c	Minimum confidence threshold
--max-results	-k	Maximum results

---

Workspace Management

workspaces

List, create, or switch workspaces.

hebbs workspaces list
hebbs workspaces create --name "sales-team"
hebbs workspaces switch sales-team

workspaces switch saves the workspace slug to your CLI config (~/.config/hebbs/cli.toml). All subsequent commands will route to that workspace unless overridden with --workspace.

Use --workspace on any command to target a specific workspace without switching:

hebbs recall "latest deals" --workspace sales-team
hebbs push ./legal-docs --workspace enterprise-legal

keys

Manage API keys.

hebbs keys list
hebbs keys create --label "ci-pipeline"
hebbs keys revoke <key-id>

---

Real-time

subscribe

Open a real-time subscription stream.

hebbs subscribe --entity-id customer-42 --confidence 0.7

Type text and press Enter to feed context. Press Ctrl+C to close.

feed

Feed text to an active subscription (from a separate terminal).

hebbs feed 1 "Customer asked about dark mode preferences."