hermitcrab-ai 0.1.0b4

A lightweight, memory-first, Nostr-primary personal AI assistant

🦀 HermitCrab

Your local, private AI companion that actually remembers - and gets better over time

Current release line: beta

HermitCrab is usable, local-first, and already good for real daily workflows, with identity-scoped memory, modern Nostr routing, clearer operator diagnostics, and stronger permission/audit surfaces.

What is HermitCrab, really?

HermitCrab is a personal AI agent you run on your own machine.
It’s not another cloud wrapper, not a bloated framework, not yet another SaaS subscription trap.

It’s lean, readable, auditable, and built around one simple idea:
Your AI should remember what matters to you - forever - without turning into a black box.

Think of it as a second brain you can carry in your pocket (or copy to a new laptop/VPS in seconds).
Back up ~/.hermitcrab/ and you have the config, system guidance, identities, memory, sessions, and routines.

Why people may be drawn to it

• Supports fully offline operation with local models (native Ollama or OpenAI-compatible local routes)
• Remembers things in plain, human-readable Markdown files (Obsidian compatible, git-friendly)
• Can distill conversations into facts, tasks, decisions, goals, and reflections when that optional background pass is enabled
• Reflects on itself - spots patterns, mistakes, contradictions, and suggests improvements
• Talks via Nostr (primary), Telegram, email, or plain CLI - your choice
• Stays tiny, fast, and cheap - no 100k+ line monolith
• Aims to stay powerful for operators while still being approachable for normal household use

Same crab, new shell.
Move your HermitCrab root anywhere. The agent picks up exactly where it left off.

Quick Start

Easy install

This avoids global pip and installs HermitCrab into its own virtual environment under ~/.local/share/hermitcrab:

curl -fsSL https://raw.githubusercontent.com/talvasconcelos/hermitcrab/main/scripts/install.sh | bash

Optional: also install and enable a user-level gateway service:

curl -fsSL https://raw.githubusercontent.com/talvasconcelos/hermitcrab/main/scripts/install.sh | bash -s -- --systemd-user --enable-service --start-service

The service runs hermitcrab gateway via systemd --user, which is the right long-running mode for channels, reminders, and heartbeat-driven work. The installer itself is meant to be generic for Unix-like systems; the systemd --user service step is Linux-specific.

Manual install (3 commands)

1. Install

   pip install hermitcrab-ai
   

2. Set up your workspace & config

   hermitcrab onboard
   

   (creates ~/.hermitcrab/ with config, system state, and the owner identity)

3. Pick a model & run

   Option A: Local Ollama (recommended for privacy & free)

   a. Install Ollama:

   # macOS
   brew install ollama
   
   # Linux
   curl -fsSL https://ollama.com/install.sh | sh
   
   # Start Ollama (runs in background)
   ollama serve
   

   b. Pull a model:

   ollama pull llama3.2:3b  # Fast general-purpose local model
   # Or: ollama pull llama3.1:8b      # General purpose
   # Or: ollama pull qwen2.5-coder:7b # Coding specialist
   

   c. Edit ~/.hermitcrab/config.json:

   {
     "providers": {
       "ollama": {
         "apiKey": "",
         "apiBase": "http://localhost:11434"
       }
     },
     "models": {
       "main": {
         "model": "ollama/llama3.2:3b"
       },
       "localCoder": {
         "model": "ollama/qwen2.5-coder:7b"
       }
     },
     "agents": {
       "modelAliases": {
         "coder": "localCoder"
       },
       "defaults": {
         "model": "main",
         "jobModels": {
           "subagent": "localCoder"
         }
       }
     }
   }
   

   Advanced local Ollama example with named models, cloud-routed models, and optional shorthand aliases:

   {
     "providers": {
       "ollama": {
         "apiKey": "",
         "apiBase": "http://localhost:11434"
       }
     },
     "models": {
       "main": {
         "model": "ollama/glm-5:cloud"
       },
       "coder": {
         "model": "ollama/qwen2.5-coder:7b"
       },
       "fast": {
         "model": "ollama/llama3.2:3b",
         "reasoningEffort": "medium"
       }
     },
     "agents": {
       "modelAliases": {
         "code": "coder"
       },
       "defaults": {
         "model": "main",
         "jobModels": {
           "subagent": "coder",
           "reflection": "fast",
           "reasoningEffort": "medium"
         }
       }
     }
   }
   

   Notes:

   • For Ollama, use the dedicated ollama provider.
   • Set providers.ollama.apiBase to your Ollama server root, typically http://localhost:11434 with no /v1 suffix.
   • Use ollama/... model IDs for local Ollama models and Ollama-routed cloud models.
   • Prefer the top-level models section as the canonical place for model definitions.
   • Per-model providerOptions can be used to tune Ollama behavior such as num_ctx, temperature, max_tokens, and related runtime settings.
   • agents.modelAliases is optional shorthand for runtime ergonomics; it is not required if your named model keys are already concise.
   • Subagents can use named models directly, or aliases when you want shorter operator-facing names.

   Option B: Cloud model (OpenRouter)

   Set your OpenRouter key in an environment variable or secret manager, then configure a named model:

   hermitcrab model add main anthropic/claude-sonnet-4 --provider openrouter --api-key-env HERMITCRAB_OPENROUTER_API_KEY
   hermitcrab model set-default main
   

   Then run:

   hermitcrab agent
   

   Notes:

   • OpenRouter should be configured under providers.openrouter, not providers.custom.
   • Recommended model forms are anthropic/..., openai/..., google/..., and similar upstream model IDs.
   • openrouter/anthropic/... also works if you want to be explicit.
   • If OpenRouter is your only configured provider, HermitCrab will still route the default anthropic/claude-opus-4-5 model through OpenRouter.

You're now talking to your own persistent, memory-aware agent.

What's current

• Nostr can use modern NIP-17 direct-message handling alongside legacy NIP-04 DMs
• Gateway routing can map allowed Nostr senders into isolated identities
• hermitcrab user, status, doctor, and audit expose more operator-visible runtime state
• Tool permission denials produce structured hints and durable audit events
• The owner identity remains the default CLI/operator surface

Useful first commands

hermitcrab agent      # interactive local chat
hermitcrab status     # quick runtime and config status
hermitcrab doctor     # diagnose config/provider issues
hermitcrab gateway    # run configured channels

How the agent actually thinks & remembers

HermitCrab is not a stateless chat loop.
Every session follows a clean lifecycle:

1. You talk → agent responds → tools run if needed
2. Session ends (you exit, or 30 min of silence)
3. Journal synthesis - narrative summary of what happened (cheap model)
4. Optional distillation - proposes fallback facts, tasks, goals, and decisions when enabled
5. Reflection - looks for mistakes, contradictions, patterns (smarter model)
6. Scratchpad archival - per-session transient notes are archived on session end

All extracted knowledge lands as tiny, atomic Markdown notes in the active identity's memory/:

~/.hermitcrab/identities/owner/
├── memory/
│   ├── facts/          # preferences, hard truths
│   ├── decisions/      # choices & reasoning (immutable)
│   ├── goals/          # long-term objectives
│   ├── tasks/          # things to do (with deadlines & status)
│   └── reflections/    # self-analysis, cleanups
├── knowledge/          # reference library (articles, docs, notes)
├── journal/            # narrative session summaries
├── scratchpads/        # per-session transient working notes
└── sessions/           # raw chat logs (for debugging)

Everything is:

• Human-readable & editable (open in Obsidian, Vim, Notepad)
• Structured with YAML frontmatter
• Wikilink-friendly
• Deterministic - Python, not the LLM, writes the files

No vector databases. No silent embeddings. No hidden state corruption.

Distillation is conservative and optional by design. Explicit memory writes remain authoritative.

Scratchpad and channel prompts

• Every session has a dedicated scratchpad file at identities/<name>/scratchpads/<session>.md.
• Scratchpad is transient by design: it is archived to identities/<name>/scratchpads/archive/ on session end.
• Scratchpad traces are excluded from distillation so transient reasoning doesn't pollute long-term memory.
• Optional per-channel prompt overlays:
  • identities/<name>/prompts/<channel>.md
  • identities/<name>/prompts/<channel>/<chat_id>.md

Channels - where you talk to your crab

• Nostr (default / primary) - encrypted DMs via NIP-04 or modern NIP-17
• Telegram - classic bot
• Email - IMAP/SMTP
• CLI - quick local chats

The gateway can route channel traffic to isolated identities. CLI and config.json remain owner/operator surfaces.

Tools - what the agent can actually do

Tool	What it does
read_file	Peek at files in workspace
write_file	Create / overwrite files
edit_file	Precise replacements
list_dir	Browse directories
exec	Run permission-gated shell commands
web_search	DuckDuckGo search (no API key needed)
web_fetch	Fetch & extract URL content (sanitized)
knowledge_search	Search your knowledge library
knowledge_ingest	Save articles/docs to library
message	Reply to you on the active channel
spawn	Launch sub-agents
cron	Schedule recurring jobs

Security: Web content is automatically sanitized to remove prompt injection attacks, hidden instructions, and encoded payloads.

Execution is always gated by Python - the LLM can only propose.

Self-Improvement - the part that actually matters

HermitCrab gets smarter over time by:

• Distilling conversations → new facts/tasks/goals/reflections
• Reflecting on patterns → mistakes, contradictions, model misbehavior
• Routing jobs to the right model:
  • Interactive replies → strong model (Claude, GPT-4o, etc.)
  • Journal + distillation → cheap local (Llama 3.2 3B, Phi-3-mini)
  • Reflection → medium model

This keeps costs low while letting the agent learn without constant supervision.

Subagents and models

HermitCrab can delegate longer-running or specialized work to subagents while the main agent stays responsive.

• Define reusable models in top-level models
• Set a dedicated subagent model in agents.defaults.jobModels.subagent
• Optionally add short aliases in agents.modelAliases for runtime convenience
• The agent can use either named models or aliases when spawning delegated work

Example use cases:

• "Build a simple website for X, use the coder subagent"
• "Investigate this bug in the background and report back"

Architecture at a glance

HermitCrab is intentionally kept lean enough to read, debug, and adapt without inheriting a giant framework.

hermitcrab/
├── agent/         # loop, tools, memory handling
├── channels/      # Nostr, Telegram, email, CLI
├── providers/     # LLM abstraction (litellm + fallbacks)
├── config/        # typed config loading
├── cli/           # typer-based interface
└── utils/         # helpers

Design rules we live by:

• Python is the source of truth - LLM is untrusted
• Memory is deterministic & auditable
• Local-first by default
• Small enough to read in a weekend
• Hackable, understandable

Runtime safety defaults

Production-minded defaults are in hermitcrab/config/schema.py and are written into ~/.hermitcrab/config.json on hermitcrab onboard.

• LLM retries with exponential backoff
• Max response loop time cap
• Repeated tool-cycle detection (loop break)
• Bounded memory context injection
• Reflection auto-promotion disabled by default (safer file integrity)

Comparison - why this feels different

Aspect	HermitCrab	Typical AI Framework / Chatbot
Core code size	Lean Python codebase	50k–300k+ lines
Memory	Atomic Markdown	Vector DB or forgotten
Portability	Copy HermitCrab root → works	Cloud account locked
Transparency	Fully auditable	Opaque internals
Cost	Local models cheap	API calls add up fast
Self-improvement	Built-in distillation & reflection	Rare or manual

Current focus

• modern Nostr direct-message reliability
• owner-managed identity routing
• clearer diagnostics, audit trails, and operator recovery paths
• safer permission UX without arbitrary dead ends
• keeping the default owner identity experience simple and intact

Why I built this

Most AI tools today are:

• Tied to someone else’s cloud
• Forget everything after 4k tokens
• Impossible to truly understand or audit
• Expensive to run 24/7

HermitCrab exists to prove a quieter truth:

A personal AI can be small, local, private, deterministic, and still grow with you - without turning into a 200k-line monster or a subscription bill.

Keep it yours. Keep it local. Keep it simple. 🦀

Get started

curl -fsSL https://raw.githubusercontent.com/talvasconcelos/hermitcrab/main/scripts/install.sh | bash
hermitcrab doctor
hermitcrab agent

Welcome to your own second brain. Let's make it remember everything that matters.

Nostr

HermitCrab's primary channel is Nostr, using encrypted DMs for private conversations. It supports both legacy NIP-04 and modern NIP-17 DM handling for compatibility with a wide range of clients.

Check out more about Nostr here, and consider using a dedicated Nostr chat client to interact with your HermitCrab agent.

Docker

Dockerfile and docker-compose.yml build/run HermitCrab directly.

• Build: docker compose build
• Run gateway: docker compose up -d hermitcrab-gateway

Persisted data lives at ~/.hermitcrab and can be mounted into containers when you use Docker.

🤝 Acknowledgments

HermitCrab started as a fork of nanobot by HKUDS.

We stand on the shoulders of giants:

• Original nanobot architecture © HKUDS (MIT License)
• Inspired by OpenClaw

Thank you to the nanobot team for creating the foundation that made HermitCrab possible.