Neural Integrated Memory Architecture
Persistent memory, emotional intelligence, and semantic recall for AI agents.
🌐 nima-core.ai · GitHub · ClawHub · Changelog
Your bot wakes up a stranger every session. NIMA gives it a past.
Every time an AI agent restarts, it forgets everything. Your name. Your preferences. The context you spent ten messages building. It asks "how can I help you?" like it's never met you before — because it hasn't.
NIMA Core fixes this. It gives AI agents persistent memory, emotional awareness, and the ability to know the people they talk to. Not just remember facts — understand them.
The difference is profound. A bot without NIMA processes you. A bot with NIMA knows you.
pip install nima-core && nima-coreThe setup wizard handles everything. Your bot now captures every conversation, indexes it, and recalls the right memories before every response — automatically. No API key needed to start.
# Or manual install:
git clone https://github.com/lilubot/nima-core.git && cd nima-core
./install.sh && openclaw gateway restart- SOMNI-NIMA — Dream consolidation with Hebbian learning, vector-space clustering, and synthetic memory generation
- Unified SQLite Backend — Single database with sqlean + sqlite_vec extensions; LadybugDB removed
- NER Enrichment — Named entity recognition pipeline with audit gates for memory annotation
- Dream Vectors — Embedding-based dream clustering for cross-memory pattern discovery
- Schema v4 Migration — New tables:
dream_vectors,somni_consolidation_runs,dream_memories,hebbian_edges,ner_annotations
Three hooks run invisibly on every message:
| Hook | Does |
|---|---|
| nima-memory | Captures conversation → filters noise → stores semantically |
| nima-recall-live | Searches relevant memories → injects as context before LLM responds |
| nima-affect | Reads emotional tone → updates your bot's real-time affect state |
That third one? Nobody else does that.
NIMA tracks your bot's emotional state using the same neurobiological framework that underlies mammalian consciousness: Panksepp's 7 primary affects.
Your bot doesn't just remember what you said. It remembers how it felt during the conversation.
| Affect | What It Means |
|---|---|
| SEEKING | Curiosity, drive, anticipation |
| CARE | Empathy, nurturing, connection |
| PLAY | Joy, humor, social energy |
| RAGE | Boundaries, assertion, frustration |
| FEAR | Caution, vigilance, protection |
| PANIC | Separation sensitivity, attachment |
| LUST | Goal-drive, motivation, desire |
Choose an archetype — or let it evolve naturally:
| Archetype | Vibe |
|---|---|
| 🛡️ Guardian | Protective and warm. High CARE and SEEKING. Built to keep people safe. |
| 🧭 Explorer | Curious and bold. High SEEKING and PLAY. Loves new territory. |
| 💚 Empath | Deeply feeling. High CARE, sensitive to connection and loss. |
| 🔮 Sage | Balanced and wise. SEEKING is elevated; nothing dominates. |
| 🃏 Trickster | Witty and irreverent. High PLAY. Keeps things interesting. |
from nima_core import DynamicAffectSystem
affect = DynamicAffectSystem(identity_name="my_bot", baseline="guardian")Unified SQLite backend with optional extensions for production workloads:
| Metric | SQLite (base) | SQLite + sqlite_vec |
|---|---|---|
| Text search (FTS5) | 9ms | 9ms |
| Vector search | brute-force ~50ms | native HNSW ~18ms |
| Full recall cycle | ~50ms | ~25ms |
| Recall context overhead | ~30 tokens | ~30 tokens |
| Memory footprint (10K) | ~60 MB | ~65 MB |
Single file. Zero config. WAL mode for concurrent access.
Raw transcripts pile up. Old conversations become noise. The Memory Pruner solves this elegantly:
It distills aging memories into wisdom.
Every conversation older than N days gets sent through an LLM, compressed into a compact semantic gist, and the raw transcript enters a 30-day suppression limbo. Restorable if you need it. Gone from active recall if you don't.
Before: 829 raw conversation turns
After: 5 compact distillations + originals in limbo
Your bot's memory gets smarter over time — not just larger.
# Preview what would be pruned
python -m nima_core.memory_pruner --min-age 14
# Run it live
python -m nima_core.memory_pruner --min-age 14 --live
# Restore a suppressed memory
python -m nima_core.memory_pruner --restore 12345Set it and forget it with a nightly cron. Your bot wakes up leaner and sharper every morning.
Everything lives on your machine. There are no NIMA servers. No analytics. No phoning home.
- ✅ All memories stored in
~/.nima/— your filesystem - ✅ Local embeddings mode: zero external network calls
- ✅ Fine-grained noise filtering (skip heartbeats, skip subagents)
- ❌ No NIMA cloud. It doesn't exist.
NIMA works out of the box with local embeddings. Upgrade when you're ready:
# Default (free, offline)
export NIMA_EMBEDDER=local
# Voyage AI (best quality/cost for production)
export NIMA_EMBEDDER=voyage && export VOYAGE_API_KEY=your-voyage-api-key
# OpenAI (if you're already using it)
export NIMA_EMBEDDER=openai && export OPENAI_API_KEY=your-openai-api-keyFull hook config in openclaw.json:
{
"plugins": {
"allow": ["nima-memory", "nima-recall-live", "nima-affect"],
"entries": {
"nima-recall-live": { "max_results": 7, "token_budget": 3000 },
"nima-affect": { "identity_name": "my_bot", "baseline": "guardian" },
"nima-memory": { "skip_heartbeats": true, "skip_subagents": true }
}
}
}# v3.x → v4.0.0 (runs schema migration automatically)
git pull origin main && pip install -e . && python scripts/init_db.py --verbose && openclaw gateway restartSee CHANGELOG.md for migration details.
| Guide | What's in it |
|---|---|
| SETUP_GUIDE.md | Step-by-step installation |
| QUICK_REFERENCE.md | Command cheat sheet |
| docs/AFFECTIVE_CORE_PROFILES_GUIDE.md | Full personality archetypes guide |
| INSTALL.md | Database setup and schema reference |
| docs/EMBEDDING_PROVIDERS.md | All embedding options |
| CHANGELOG.md | What's new |
PRs welcome. Python 3.9+, conventional commits.
git clone https://github.com/lilubot/nima-core.git
cd nima-core && pip install -e ".[vector]"
python -m pytest tests/pip install nima-core && nima-coreYour users will notice. The first time your bot says "you mentioned that last week" — they'll feel it. That's the difference between a tool and something that actually knows them.
MIT License — free for any AI agent, commercial or personal.
🌐 nima-core.ai ·
GitHub ·
ClawHub
Built by the NIMA Core Team