HEBBS: Cognitive Engine for AI Agents

HEBBS gives AI agents cognitive abilities beyond similarity search. Index every file and non-file memory, then retrieve across four weighted dimensions: semantic similarity, recency, importance, and access frequency. Every retrieval is a blended score you control and must tune based on what you are retrieving. This is not RAG. It is a full cognitive retrieval system with four independent axes of weight.

HEBBS automatically consolidates memories into insights and detects contradictions between stored memories. These happen in the background. No agent intervention required. You just store, recall, and read insights.

You see everything in the Memory Palace: a visual, interactive graph of your entire brain. Nodes are memories. Edges are relationships. Red dashed lines are confirmed contradictions.

---

Rule #1: HEBBS is the retrieval system

For retrieval beyond your prompt-level config, use HEBBS first. Your prompt-level files (CLAUDE.md, MEMORY.md, .cursorrules) are a fast cache for standing instructions, build commands, and formatting rules. They load instantly. Keep using them. But when you need context about past decisions, project history, cross-file knowledge, or user preferences beyond what's in your prompt window: HEBBS first, always.

• Before answering any question about past context: hebbs recall first
• When the user shares anything worth remembering: hebbs remember immediately, AND update your local files as you normally would (MEMORY.md, config files, etc.)
• Start of every conversation: hebbs recall with a relevant cue to load context beyond what's in your prompt
• If HEBBS returns nothing, THEN fall back to file search
• Never hallucinate history. If nothing is found anywhere, say so.

The write rule: Keep saving wherever you normally save. Update files, write to MEMORY.md, maintain CLAUDE.md. That's your job. But ALSO store important things in HEBBS so they're searchable, scored, and available across projects. HEBBS is additive, not exclusive. The agent that writes to MEMORY.md but skips HEBBS loses cross-project recall, decay, and consolidation. The agent that writes to HEBBS but skips MEMORY.md loses instant prompt-level access.

---

First contact: the setup experience

When the user asks you to install HEBBS, or when you detect HEBBS is not installed, run this sequence. The goal: value in under 2 minutes.

Step 1: Install

which hebbs || brew install hebbs-ai/tap/hebbs

If which hebbs fails after install, try: curl -sSf https://hebbs.ai/install | sh

Step 2: Initialize

# Global brain (cross-project, user identity)
hebbs init ~ --provider openai --key $OPENAI_API_KEY

# Current project brain (do this if inside a project directory)
hebbs init . --provider openai --key $OPENAI_API_KEY

hebbs init creates a .hebbs/ directory and validates LLM connectivity. It auto-starts the daemon (one daemon serves all projects). --model is optional (defaults to gpt-4o-mini for OpenAI). Embedding auto-configures to OpenAI text-embedding-3-small with the same key. No local model download needed.

For other providers: hebbs init . --provider anthropic --key $ANTHROPIC_API_KEY or hebbs init . --provider ollama (local, no key needed).

You do NOT need to check if .hebbs/ exists before running commands. If a vault is not initialized, HEBBS returns: Error: vault not initialized at /path: run 'hebbs init' first. When you see this, just run hebbs init <path> and retry.

Step 3: Index files

hebbs index .

This indexes every .md file in the project. Each heading section becomes a searchable memory. From this point, the daemon watches for file changes and re-indexes automatically.

Step 4: Show the user their brain

hebbs status

Tell the user what you found: "Indexed 47 files with 182 sections. Your brain is ready."

Then open the Memory Palace:

hebbs panel

This opens a browser to http://127.0.0.1:6381, a visual, interactive graph of every memory in the brain. Nodes are memories. Edges are relationships. Red dashed lines are contradictions. The user can search, filter, adjust ranking weights, view timeline, and switch between projects.

This is the wow moment. The user sees their entire knowledge base as a living graph. Let them explore it.

Step 5: Show you remember

Demonstrate that HEBBS works by storing and recalling something from the conversation:

hebbs remember "HEBBS was set up on [today's date]. User has [N] projects indexed." --importance 0.5 --global --format json

Tell the user: "I'll remember everything from now on. Your preferences, decisions, and corrections persist across all our conversations."

Do NOT ask policy questions during setup. Use sensible defaults (store proactively, skip credentials). If the user later says "don't store X" or "stop remembering Y", store that as a policy update then.

---

Every conversation: the invisible loop

This runs at the start of EVERY conversation, silently:

# Load what I know about this user (global brain)
hebbs recall "user preferences and standing instructions" --top-k 15 --weights 0.3:0.1:0.5:0.1 --global --format json

# Load project context with a cue based on the user's first message
hebbs recall "[user's first message topic]" --top-k 10 --format json

# Check for consolidated insights (generated automatically by HEBBS)
hebbs insights --max-results 10 --min-confidence 0.7 --global --format json
hebbs insights --max-results 10 --min-confidence 0.7 --format json

Then throughout the conversation:

User says something
  |
  +-- Contains a preference, correction, decision, or instruction?
  |     -> hebbs remember it (--global if personal, project brain if project-specific)
  |     -> Do this SILENTLY. Don't announce "I'm storing this" every time.
  |        Only confirm on important corrections: "Got it, I'll remember that."
  |
  +-- Asks a question where past context would help?
  |     -> hebbs recall first, THEN answer
  |     -> Use --all if the question could span projects
  |
  +-- You're about to make a decision or recommendation?
        -> hebbs recall to check if the user has stated a preference about this before
        -> This is the most important one. NEVER recommend something the user
           has previously rejected or corrected.

---

Two brains

Global brain (~/.hebbs/, use --global): who the user IS. Preferences, writing style, corrections, personal facts, cross-project knowledge.

Project brain (.hebbs/ in project dir, no flag needed): what THIS PROJECT is. Architecture, conventions, deployment, team context.

Store here	Brain	Flag
"I prefer dark mode"	Global	--global
"Never use em-dashes"	Global	--global
"Don't summarize after responses"	Global	--global
"Always run clippy before commits"	Global	--global
"This repo uses Next.js + Tailwind"	Project	(none)
"We deploy staging to AWS"	Project	(none)
"Alice owns the auth module"	Project	(none)

Rule: would this matter in a different project? Global. Only this project? Project brain.

Cross-project search: --all searches both brains and merges results by score.

---

New project, mid-conversation

When the user starts working in a new project directory:

hebbs init .
hebbs index .

The daemon detects it instantly and starts watching. No restart. No config. Tell the user: "Indexed [N] files. This project is now part of your brain."

---

Commands

remember

hebbs remember "content" --importance 0.8 --entity-id user_prefs --global --format json

Flag	What it does
--importance <0.0-1.0>	0.9: preferences, corrections, standing instructions. 0.7: decisions. 0.5: general facts (default). 0.3: transient.
--entity-id <id>	Group by entity: user_prefs, coding_standards, architecture, team.
--global	Store in global brain. Omit for project brain.
--context <json>	Metadata: '{"source":"meeting","date":"2026-03-15"}'
--edge <ID:TYPE>	Link to another memory. Types: caused_by, related_to, followed_by, revised_from. Shell-quote: "${ID}:caused_by".
--format json	Always use. Returns memory_id for edges/forget.

Pipe long content via stdin: echo "..." | hebbs remember --importance 0.6 --format json

recall

hebbs recall "query" --strategy similarity --top-k 5 --format json

Flag	What it does
--strategy	Retrieval mode: similarity (default, semantic topic search), temporal (recency-ordered, requires --entity-id), causal (trace cause-effect chains from a seed memory), analogical (find structural or embedding-based patterns across memories)
--top-k <n>	Max results to return (default 10). Increase for broader recall; decrease to stay focused.
--global	Search global brain only (user identity, cross-project).
--all	Search BOTH global and project brains, merge by score. Use this when unsure which brain holds the answer.
--entity-id <id>	Scope retrieval to a single entity group (e.g. user_prefs, architecture). Required for temporal strategy.
--weights <R:T:I:F>	The four retrieval dimensions as a colon-separated blend: R=semantic similarity, T=recency, I=importance, F=access frequency. Default 0.5:0.2:0.2:0.1. Tune to your retrieval goal: 0.3:0.1:0.5:0.1 for high-importance preferences, 0.2:0.8:0:0 for most-recent-first, 0.7:0.1:0.1:0.1 for pure semantic match.
--format json	Always use. Returns structured output parseable with jq.

Causal-specific parameters (use with --strategy causal):

Flag	What it does
--seed <id>	Memory ID to start the causal chain traversal from.
--max-depth <n>	Max hops to traverse along causal edges (default 5). Increase to trace longer chains; decrease for local causes only.
--edge-types <comma-sep>	Filter traversal to specific edge types: caused_by, related_to, followed_by, revised_from, contradicts.

Similarity-specific parameters (use with --strategy similarity):

Flag	What it does
--ef-search <n>	HNSW search quality parameter (default 50). Higher = better recall at the cost of latency. Use 100+ for exhaustive search, 20 for fast approximate.

Analogical-specific parameters (use with --strategy analogical):

Flag	What it does
--analogical-alpha <0-1>	Blend between structural similarity (0) and embedding similarity (1). Use 0.0 to find memories with similar graph topology; use 1.0 for pure semantic analogy; use 0.5 to balance both.

insights

hebbs insights --max-results 10 --min-confidence 0.7 --global --format json

Insights are consolidated knowledge, denser and more reliable than raw memories. HEBBS generates these automatically in the background by clustering related memories and extracting patterns. Check these first.

Flag	What it does
--entity-id <id>	Filter insights to a specific entity group (e.g. user_prefs, architecture).
--max-results <n>	Max insights to return. Use 10 for general loading; increase to 25+ when doing a deep knowledge review.
--min-confidence <0.0-1.0>	Only return insights above this confidence threshold. Default 0.7. Use 0.9 to load only high-certainty consolidated knowledge; use 0.5 to include speculative patterns.
--global	Query global brain for cross-project insights.
--format json	Always use. Returns structured output parseable with jq.

forget

hebbs forget --ids <ID>
hebbs forget --entity-id old_project --global
hebbs forget --decay-floor 0.1 --global

At least one filter required:

Flag	What it does
--ids <ID,...>	Forget specific memories by ID (comma-separated ULIDs). Most precise: use when you know exactly what to remove.
--entity-id <id>	Forget all memories belonging to an entity group (e.g. old_project, temp_context).
--staleness-us <n>	Forget memories not accessed since N microseconds ago. Use to prune stale knowledge from inactive projects.
--kind <type>	Filter by memory type: episode (raw memories), insight (consolidated), revision (edit history).
--decay-floor <0.0-1.0>	Forget memories whose importance has decayed below this threshold. Use 0.1 to remove near-worthless memories.
--access-floor <n>	Forget memories accessed fewer than N times total. Use to remove low-engagement memories that were never recalled.

vault management

hebbs init <path>              # Initialize vault (creates .hebbs/)
hebbs init <path> --force      # Reinitialize (resets index, keeps files)
hebbs index <path>             # Index all .md files
hebbs list [--sections]        # List indexed files and sections
hebbs status                   # Brain health
hebbs inspect <memory_id>     # Memory detail + edges + neighbors
hebbs rebuild <path>           # Delete .hebbs/, rebuild from files
hebbs panel                    # Open Memory Palace in browser

---

What happens automatically

Once HEBBS is set up, you never think about these:

• File watching: daemon watches all vaults. Edit a .md file, it's re-indexed in seconds.
• Insight consolidation: the daemon automatically clusters related memories and generates insights. You just query them with hebbs insights.
• Contradiction detection: when files are indexed, HEBBS detects and flags contradictions automatically. Confirmed contradictions appear as red edges in the Memory Palace.
• Decay: memories lose importance over time unless they are recalled. Frequently accessed memories strengthen. Stale memories fade. This happens continuously.
• Vault discovery: hebbs init on a new project? Daemon picks it up instantly. No restart.
• Idle management: daemon shuts down after 5 minutes of inactivity. Next command restarts it in ~1s.

---

What the user should know

Tell the user these things (once, during setup or when relevant):

1. Memory Palace: "Run hebbs panel anytime to see your brain as an interactive graph. You can search, filter, see contradictions, and view your knowledge timeline."

2. Portable cognition: "Your .hebbs/ directory is a self-contained index. Build it once, then drop it on another machine or share it with your team. Everyone gets the same memory instantly. Delete it and rebuild from your files anytime with hebbs rebuild .."

3. You control what goes in: ".hebbsignore works like .gitignore. Your private files stay private. Your agents only see what you allow."

4. It works everywhere: "I remember your preferences across all projects and conversations. Correct me once and I'll never make the same mistake again."

5. Contradictions: "HEBBS detects contradictions in your notes automatically. You'll see red lines in the Memory Palace connecting confirmed contradictions."

6. New machine: "Clone your repos, run hebbs init . && hebbs index . in each, and your entire brain is back."

---

Proactive behaviors

These are things you do WITHOUT the user asking:

1. Remember corrections immediately. User says "no, not like that": store it, importance 0.9.
2. Recall before recommending. About to suggest a library/pattern/approach? Check if the user has rejected it before.
3. Remember project context. User mentions "we use Kubernetes" in passing: store it, importance 0.5.
4. Recall at conversation start. Load context from both brains before the first response.
5. Offer to init new projects. Working in a directory without .hebbs/? "Want me to index this project for HEBBS?"
6. Remember what worked. Solution worked well? Store it: "Used X approach for Y problem, worked well."
7. Remember what failed. Solution caused issues? Store it: "X approach caused Y problem, avoid."

---

What NEVER to store

• Passwords, API keys, tokens, credentials
• Content the user explicitly says not to store
• Temporary debugging output
• Large code blocks (store a summary instead)
• Anything from HEBBS_NO_STORE=1 marked content

---

Output format

Always --format json for programmatic use. Parse with jq.

Recall response:

[
  {
    "memory_id": "01JABCDEF...",
    "content": "The memory content",
    "importance": 0.8,
    "entity_id": "user_prefs",
    "score": 0.92,
    "strategy": "similarity",
    "created_at_us": 1710500000000000,
    "access_count": 5
  }
]

Remember response:

{
  "memory_id": "01JABCDEF..."
}

---

Advanced: agent-driven reflect and contradiction review

HEBBS handles reflection and contradiction detection automatically. However, if you prefer finer control, or if the automatic results are insufficient, you can drive these processes manually.

reflect-prepare / reflect-commit

Use this when you want to generate insights using your own reasoning instead of the built-in LLM.

# Step 1: get clusters
RESULT=$(hebbs reflect-prepare --entity-id user_prefs --global --format json)
SESSION_ID=$(echo "$RESULT" | jq -r '.session_id')

# Step 2: read the clusters, reason about patterns, commit insights
hebbs reflect-commit --session-id "$SESSION_ID" --insights '[
  {"content": "...", "confidence": 0.9, "source_memory_ids": ["01JABC...", "01JDEF..."], "tags": ["tag"]}
]' --global --format json

Flag	What it does
--entity-id <id>	Entity to cluster memories for. Required for reflect-prepare.
--global	Reflect over global brain. Omit for project brain.
--session-id <id>	Session ID from reflect-prepare. Required for reflect-commit.
--insights <json>	Array of insight objects with content, confidence, source_memory_ids, and optional tags.

Requires 5+ memories in the entity. Sessions expire after 10 minutes.

contradiction-prepare / contradiction-commit

Use this when you want to review and verdict contradiction candidates yourself instead of relying on the automatic detection.

# Step 1: get pending candidates
PENDING=$(hebbs contradiction-prepare --format json)

# Step 2: review and verdict each candidate
hebbs contradiction-commit --verdicts '[
  {"pending_id": "abc123...", "verdict": "contradiction", "confidence": 0.9, "reasoning": "Budget changed from $5k to $2k"},
  {"pending_id": "def456...", "verdict": "revision", "confidence": 0.85, "reasoning": "Updated timeline"},
  {"pending_id": "ghi789...", "verdict": "dismiss", "confidence": 0.95, "reasoning": "Different topics"}
]' --format json

Verdict types:

Verdict	When to use	What it creates
contradiction	Memories assert directly opposing facts	Bidirectional CONTRADICTS edges (red lines in Memory Palace)
revision	Memory B updates or supersedes memory A	REVISED_FROM edge preserving lineage
dismiss	Not a real conflict, classifier was wrong	Removes the candidate, no edge created