• The Forgetfulness Problem
• The Cloud Problem
• The Bloat Problem
• The Markdown Solution
• Nostr-Native
• Self-Improving, Actually
• Same Crab, New Shell
• Not for Everyone
• Try It

I built (vibed…) an AI assistant that fits in a tarball.

Not a Docker container. Not a cloud service. Not a subscription.
One folder. Markdown files. ~6,000 lines of Python.

Want to move it to a new machine?
tar czvf hermit.tar.gz ~/.hermitcrab && scp hermit.tar.gz new-server:~/
That’s it. Every conversation, every memory, every preference comes with it.
The crab just picks up its shell and walks.

I call it HermitCrab.
And I’m tired of pretending the current state of AI doesn’t suck.

§The Forgetfulness Problem

Every chatbot you’ve used has the memory of a goldfish.
“Remember what we talked about yesterday?”
Sorry, that was 6,000 tokens ago. Gone. Poof.

So the industry built RAG. Vector databases. Embeddings. “Context windows.”
All fancy words for “the computer forgot, so we stapled a search engine on top.”

Here’s what nobody tells you:
Those vector DBs are black boxes.
You can’t cat them. You can’t git diff them. You can’t open them in Obsidian and see what your AI actually remembers about you.
They’re just 1,536-dimensional arrays floating in math space.
Your memories, unreadable by humans.

§The Cloud Problem

“Just use ChatGPT.”
Sure. And hand over every plan, every client name, every insecurity, every half-baked idea to a company that needs to monetize engagement.
Every interaction logged, labeled, and eventually fed into the next training run.

Your AI knows you.
Really knows you.
And it lives on someone else’s computer.

This isn’t paranoia. This is basic opsec.
You’d never store your seed phrase on Coinbase.
Why store your thoughts on OpenAI?

§The Bloat Problem

I looked at the AI frameworks.
Hundreds of thousands of lines. Dependency hell. Docker images the size of operating systems.
“Just run this one command and a container orchestrator will spin up services!”

No.
I wanted something I could read in a weekend.
Understand. Audit. Fix.
If it screws up, I want to know why line 4,237 calling the wrong function.
Not some mysterious embedding vector drifting across a million lines of infrastructure I don’t control.

Small is a feature.
Readable is a feature.
“I can fix this myself” is a feature.

§The Markdown Solution

So I built something different.

When you talk to HermitCrab, it writes this:

---
id: fact-7a3f2d8e
category: facts
created: 2026-02-27T13:15:00Z
confidence: 0.92
sources: [session-2026-02-27]
---
User prefers conciseness over verbosity. Has expressed frustration with
AI assistants that over-explain simple answers. Works in Bitcoin space.

Just Markdown. YAML frontmatter. Human-readable. Git-friendly. Obsidian-compatible.
You can:

• grep "Bitcoin" ~/.hermitcrab/memory/facts/
• Edit a file if the AI got something wrong
• git log --oneline to watch how your AI’s understanding of you evolved
• Delete something you don’t want it to remember anymore

It’s your memory. In your format. On your machine.

§Nostr-Native

Of course it talks over Nostr.
Encrypted DMs (NIP-04). Groups coming soon (NIP-17).
Your phone, laptop, VPS, any relay-connected device can message your crab.
No central server. No “the service went down.”
Just Nostr relays and cryptography.
Your AI is a person in your DM list.

§Self-Improving, Actually

HermitCrab doesn’t just store things. It reflects.

After every session it:

1. Writes a narrative journal summary
2. Distills facts, tasks, goals, decisions into atomic notes
3. Reflects on mistakes, contradictions, patterns and suggests fixes

Cheap local models handle the grunt work. Stronger models handle the deep reasoning.
It learns what you care about. Notices when you’re stuck in the same loop.
Gently tells you you might be over-engineering again (yes, it already knows about that).

And because everything is deterministic Python writing Markdown, not an LLM silently managing a vector DB, you can verify it did what it claims.

§Same Crab, New Shell

The metaphor isn’t cute. It’s literal.
Built on my laptop. Moved to a VPS. Moved back.
The crab didn’t care. Same memories. Same ongoing projects. Same personality.

Try that with ChatGPT.
“Export your data” gives you JSON and a prayer.
No real continuity. No sense that this AI knows you.
Just another session. Another context window. Another goldfish.

§Not for Everyone

Let’s be honest: this isn’t for normies.

If you want zero-config magic, use Claude. It’s great. I use it too.
HermitCrab is for people who:

• Run their own Bitcoin node
• Get why self-custody matters
• Get annoyed when a service changes ToS or raises prices
• Want an AI that remembers, not one that searches
• Believe thoughts belong on their hard drive, not in a cloud datacenter

Sound like you?

§Try It

pip install hermitcrab-ai
hermitcrab onboard
hermitcrab agent

No API keys required. Runs offline with Ollama by default.
Your AI. Your memories. Your machine.
Same crab, new shell.

GitHub: https://github.com/talvasconcelos/hermitcrab
PyPI: https://pypi.org/project/hermitcrab-ai/

Built in public. Questions welcome. Zaps appreciated if it resonates. 🦀