nima-core

Category: Data & AI | Uploader: lilubot | Downloads: 0 | Version: v1.0（Latest）

Noosphere Integrated Memory Architecture — Complete cognitive stack for AI agents: persistent memory, emotional intelligence, dream consolidation, hive mind, precognitive recall, and lucid moments. 4 embedding providers, LadybugDB graph backend, zero-config install. nima-core.ai

Changelog: Source: GitHub https://github.com/lilubot/nima-core

Directory Structure

Current level: Root

📁 .auto-claude/
- 📁 specs/
  - 📁 010-adopt-connection-pool-in-storage-scorers/
    
    📄 implementation_plan.json 7.7 KB
📁 nima_core/
- 📁 cli/
  - 📄 memory_audit.py 6.7 KB
- 📁 cognition/
  - 📄 __init__.py 4.1 KB
  - 📄 affect_correlation.py 10.0 KB
  - 📄 affect_history.py 12.3 KB
  - 📄 affect_interactions.py 5.8 KB
  - 📄 archetypes.py 5.8 KB
  - 📄 consciousness_workspace.py 24.7 KB
  - 📄 dynamic_affect.py 26.2 KB
  - 📄 emotion_detection.py 7.6 KB
  - 📄 exceptions.py 2.6 KB
  - 📄 personality_profiles.py 20.2 KB
  - 📄 phi_estimator.py 15.7 KB
  - 📄 precog_actions.py 28.3 KB
  - 📄 response_modulator_v2.py 11.4 KB
  - 📄 schema_extractor.py 25.3 KB
  - 📄 sparse_block_memory.py 69.4 KB
  - 📄 sparse_block_vsa.py 10.3 KB
  - 📄 sparse_retrieval.py 29.2 KB
  - 📄 theory_of_mind.py 23.7 KB
- 📁 dream/
  - 📄 __init__.py 11.9 KB
  - 📄 CODE_REVIEW.md 8.1 KB
  - 📄 consolidator.py 20.3 KB
  - 📄 db_operations.py 5.9 KB
  - 📄 domain_classifier.py 2.5 KB
  - 📄 insight_generator.py 7.4 KB
  - 📄 models.py 3.2 KB
  - 📄 narrative_generator.py 4.3 KB
  - 📄 pattern_detector.py 14.2 KB
  - 📄 vsa_blender.py 2.4 KB
- 📁 scripts/
  - 📄 migrate_themes.py 3.3 KB
- 📁 storage/
  - 📁 data/
    
    📄 memory_graph.db 44.0 KB
  - 📄 __init__.py 3.4 KB
  - 📄 bayesian_scorer.py 11.9 KB
  - 📄 hebbian_updater.py 16.4 KB
  - 📄 hybrid_search.py 15.9 KB
  - 📄 hyperbolic_memory.py 23.8 KB
  - 📄 ladybug_guard.py 8.3 KB
  - 📄 memory_graph.py 14.4 KB
  - 📄 memory_manager.py 13.0 KB
  - 📄 migration_manager.py 17.7 KB
  - 📄 persistent_memory.py 23.0 KB
  - 📄 process_guard.py 6.9 KB
  - 📄 protocol_store.py 18.5 KB
  - 📄 temporal_decay.py 14.1 KB
- 📄 __init__.py 3.5 KB
- 📄 connection_pool.py 5.3 KB
- 📄 darwinism.py 13.7 KB
- 📄 dream_consolidation.py 4.4 KB
- 📄 dream_db_sync.py 24.9 KB
- 📄 hive_mind.py 32.1 KB
- 📄 logging_config.py 4.1 KB
- 📄 lucid_moments.py 18.0 KB
- 📄 memory_git.py 8.5 KB
- 📄 memory_pruner.py 20.1 KB
- 📄 metrics.py 6.2 KB
- 📄 precognition.py 15.7 KB
📁 openclaw_hooks/
- 📁 nima-affect/
  - 📄 emotion-lexicon.js 20.5 KB
  - 📄 index.js 34.0 KB
  - 📄 openclaw.plugin.json 1.1 KB
  - 📄 package.json 92 B
  - 📄 vader-affect.js 16.9 KB
- 📁 nima-memory/
  - 📄 backfill.py 8.9 KB
  - 📄 embeddings.py 16.3 KB
  - 📄 faiss_index.py 13.7 KB
  - 📄 health_check.py 6.6 KB
  - 📄 index.js 62.2 KB
  - 📄 ladybug_store.py 14.9 KB
  - 📄 migrate_to_ladybug.py 33.1 KB
  - 📄 openclaw.plugin.json 3.7 KB
  - 📄 package.json 92 B
  - 📄 voyage_cache.py 19.3 KB
- 📁 nima-recall-live/
  - 📄 build_embedding_index.py 6.1 KB
  - 📄 index.js 33.5 KB
  - 📄 ladybug_recall.py 16.7 KB
  - 📄 lazy_recall.py 9.6 KB
  - 📄 openclaw.plugin.json 1.5 KB
  - 📄 package.json 261 B
  - 📄 process_guard.js 3.4 KB
  - 📄 query_precognitions.py 2.5 KB
  - 📄 quick_recall.py 2.2 KB
  - 📄 RECALL_VERSIONS.md 2.0 KB
- 📁 skill-router/
  - 📄 index.js 5.0 KB
  - 📄 openclaw.plugin.json 1000 B
  - 📄 package.json 176 B
📁 scripts/
- 📄 init_db.py 9.6 KB
- 📄 init_ladybug.py 8.4 KB
- 📄 migrate_to_3_2_0.py 13.7 KB
- 📄 migrate_to_3_3_0.py 6.0 KB
- 📄 nima_sync.sh 2.8 KB
📁 tests/
- 📄 test_cypher_security.py 16.0 KB
- 📄 test_persistent_memory_security.py 14.7 KB
📄 .auto-claude-security.json 2.5 KB
📄 .auto-claude-status 467 B
📄 .claude_settings.json 2.3 KB
📄 .clawhubignore 246 B
📄 .env.example 654 B
📄 .gitignore 571 B
📄 .nimaignore 940 B
📄 CHANGELOG.md 20.0 KB
📄 doctor.sh 12.9 KB
📄 INSTALL.md 14.1 KB
📄 install.sh 4.6 KB
📄 LICENSE 1.0 KB
📄 llms-full.txt 32.7 KB
📄 QUICKSTART.md 379 B
📄 README.md 26.3 KB
📄 requirements.txt 210 B
📄 SECURITY.md 9.2 KB
📄 setup.py 1.2 KB
📄 SKILL.md 14.3 KB
📄 test_error_handling.py 8.4 KB
📄 update.sh 2.6 KB
📄 upgrade.sh 9.7 KB
📄 verify_security_e2e.py 7.7 KB

SKILL.md

---
name: nima-core
description: "Noosphere Integrated Memory Architecture — Complete cognitive stack for AI agents: persistent memory, emotional intelligence, dream consolidation, hive mind, precognitive recall, and lucid moments. 4 embedding providers, LadybugDB graph backend, zero-config install. nima-core.ai"
version: 3.3.3
metadata:
  {
    "openclaw": {
      "emoji": "🧠",
      "source": "https://github.com/lilubot/nima-core",
      "homepage": "https://nima-core.ai",
      "requires": { "bins": ["python3", "node"] },
      "install": [
        {
          "id": "shell",
          "kind": "shell",
          "script": "install.sh",
          "label": "Install NIMA Core (creates ~/.nima, pip-installs dependencies, copies OpenClaw hooks)"
        }
      ],
      "permissions": {
        "reads":   ["~/.nima/", "~/.openclaw/extensions/nima-*/"],
        "writes":  ["~/.nima/", "~/.openclaw/extensions/nima-*/"],
        "network": [
          "voyage.ai (only if NIMA_EMBEDDER=voyage)",
          "openai.com (only if NIMA_EMBEDDER=openai or ANTHROPIC_API_KEY set)",
          "anthropic.com (only if ANTHROPIC_API_KEY set — memory pruner)"
        ]
      },
      "optional_env": {
        "NIMA_DATA_DIR":         "Override default ~/.nima data directory",
        "NIMA_EMBEDDER":         "voyage|openai|ollama|local (default: local — zero external calls)",
        "VOYAGE_API_KEY":        "Required when NIMA_EMBEDDER=voyage",
        "OPENAI_API_KEY":        "Required when NIMA_EMBEDDER=openai",
        "NIMA_OLLAMA_MODEL":     "Model name when NIMA_EMBEDDER=ollama",
        "NIMA_VOICE_TRANSCRIBER":"whisper|local (for voice notes)",
        "WHISPER_MODEL":         "tiny|base|small|medium|large",
        "ANTHROPIC_API_KEY":     "For memory pruner LLM distillation (opt-in only)",
        "HIVE_ENABLED":          "1 to enable multi-agent memory sharing via shared DB",
        "HIVE_REDIS_URL":        "Redis URL for real-time hive pub/sub (optional, HIVE_ENABLED=1)"
      },
      "external_calls": "All external API calls are opt-in via explicit env vars. Default mode uses local embeddings with zero network calls. install.sh does pip install nima-core and optional real-ladybug; review before running in shared/production environments."
    }
  }
---

# NIMA Core 3.2

**Noosphere Integrated Memory Architecture** — A complete cognitive stack for AI agents: persistent memory, emotional intelligence, dream consolidation, hive mind, and precognitive recall.

**Website:** https://nima-core.ai · **GitHub:** https://github.com/lilubot/nima-core

## Quick Start

```bash
pip install nima-core && nima-core
```

Your bot now has persistent memory. Zero config needed.

## What's New in v3.0

### Complete Cognitive Stack

NIMA evolved from a memory plugin into a full cognitive architecture:

| Module | What It Does | Version |
|--------|-------------|---------|
| **Memory Capture** | 3-layer capture (input/contemplation/output), 4-phase noise filtering | v2.0 |
| **Semantic Recall** | Vector + text hybrid search, ecology scoring, token-budgeted injection | v2.0 |
| **Dynamic Affect** | Panksepp 7-affect emotional state (SEEKING, RAGE, FEAR, LUST, CARE, PANIC, PLAY) | v2.1 |
| **VADER Analyzer** | Contextual sentiment — caps boost, negation, idioms, degree modifiers | v2.2 |
| **Memory Pruner** | LLM distillation of old conversations → semantic gists, 30-day suppression limbo | v2.3 |
| **Dream Consolidation** | Nightly synthesis — extracts insights and patterns from episodic memory | v2.4 |
| **Hive Mind** | Multi-agent memory sharing via shared DB + optional Redis pub/sub | v2.5 |
| **Precognition** | Temporal pattern mining → predictive memory pre-loading | v2.5 |
| **Lucid Moments** | Spontaneous surfacing of emotionally-resonant memories | v2.5 |
| **Darwinian Memory** | Clusters similar memories, ghosts duplicates via cosine + LLM verification | v3.0 |
| **Installer** | One-command setup — LadybugDB, hooks, directories, embedder config | v3.0 |

### v3.0 Highlights
- All cognitive modules unified under a single package
- Installer (`install.sh`) for zero-friction setup
- All OpenClaw hooks bundled and ready to drop in
- README rewritten, all versions aligned to `3.0.4`

## Architecture

```text
OPENCLAW HOOKS
├── nima-memory/          Capture hook (3-layer, 4-phase noise filter)
│   ├── index.js          Hook entry point
│   ├── ladybug_store.py  LadybugDB storage backend
│   ├── embeddings.py     Multi-provider embedding (Voyage/OpenAI/Ollama/local)
│   ├── backfill.py       Historical transcript import
│   └── health_check.py   DB integrity checks
├── nima-recall-live/     Recall hook (before_agent_start)
│   ├── lazy_recall.py    Current recall engine
│   └── ladybug_recall.py LadybugDB-native recall
├── nima-affect/          Affect hook (message_received)
│   ├── vader-affect.js   VADER sentiment analyzer
│   └── emotion-lexicon.js Emotion keyword lexicon
└── shared/               Resilient wrappers, error handling

PYTHON CORE (nima_core/)
├── cognition/
│   ├── dynamic_affect.py         Panksepp 7-affect system
│   ├── emotion_detection.py      Text emotion extraction
│   ├── affect_correlation.py     Cross-affect analysis
│   ├── affect_history.py         Temporal affect tracking
│   ├── affect_interactions.py    Affect coupling dynamics
│   ├── archetypes.py             Personality baselines (Guardian, Explorer, etc.)
│   ├── personality_profiles.py   JSON personality configs
│   └── response_modulator_v2.py  Affect → response modulation
├── dream_consolidation.py        Nightly memory synthesis engine
├── memory_pruner.py              Episodic distillation + suppression
├── hive_mind.py                  Multi-agent memory sharing
├── precognition.py               Temporal pattern mining
├── lucid_moments.py              Spontaneous memory surfacing
├── connection_pool.py            SQLite pool (WAL, thread-safe)
├── logging_config.py             Singleton logger
└── metrics.py                    Thread-safe counters/timings
```

## Privacy & Permissions

- ✅ All data stored locally in `~/.nima/`
- ✅ Default: local embeddings = **zero external calls**
- ✅ No NIMA-owned servers, no proprietary tracking, no analytics sent to external services
- ⚠️ Opt-in networking: HiveMind (Redis pub/sub), Precognition (LLM endpoints), LadybugDB migrations — see Optional Features below
- 🔒 Embedding API calls only when explicitly enabling (VOYAGE_API_KEY, OPENAI_API_KEY, etc.)

### Optional Features with Network Access

| Feature | Env Var | Network Calls To | Default |
|---------|----------|------------------|---------|
| Cloud embeddings | `NIMA_EMBEDDER=voyage` | voyage.ai | Off |
| Cloud embeddings | `NIMA_EMBEDDER=openai` | openai.com | Off |
| Memory pruner | `ANTHROPIC_API_KEY` set | anthropic.com | Off |
| Ollama embeddings | `NIMA_EMBEDDER=ollama` | localhost:11434 | Off |
| HiveMind | `HIVE_ENABLED=true` | Redis pub/sub | Off |
| Precognition | Using external LLM | Configured endpoint | Off |

## Security

### What Gets Installed

| Component | Location | Purpose |
|-----------|----------|---------|
| Python core (`nima_core/`) | `~/.nima/` | Memory, affect, cognition |
| OpenClaw hooks | `~/.openclaw/extensions/nima-*/` | Capture, recall, affect |
| SQLite database | `~/.nima/memory/graph.sqlite` | Persistent storage |
| Logs | `~/.nima/logs/` | Debug logs (optional) |

### Credential Handling

| Env Var | Required? | Network Calls? | Purpose |
|---------|-----------|----------------|---------|
| `NIMA_EMBEDDER=local` | No | ❌ | Default — offline embeddings |
| `VOYAGE_API_KEY` | Only if using Voyage | ✅ voyage.ai | Cloud embeddings |
| `OPENAI_API_KEY` | Only if using OpenAI | ✅ openai.com | Cloud embeddings |
| `ANTHROPIC_API_KEY` | Only if using pruner | ✅ anthropic.com | Memory distillation |
| `NIMA_OLLAMA_MODEL` | Only if using Ollama | ❌ (localhost) | Local GPU embeddings |

**Recommendation:** Start with `NIMA_EMBEDDER=local` (default). Only enable cloud providers when you need better embedding quality.

### Safety Features

- **Input filtering** — System messages, heartbeats, and duplicates are filtered before capture
- **FTS5 injection prevention** — Parameterized queries prevent SQL injection
- **Path traversal protection** — All file paths are sanitized
- **Temp file cleanup** — Automatic cleanup of temporary files
- **API timeouts** — Network calls have reasonable timeouts (30s Voyage, 10s local)

### Best Practices

1. **Review before installing** — Inspect `install.sh` and hook files before running
2. **Backup config** — Backup `~/.openclaw/openclaw.json` before adding hooks
3. **Don't run as root** — Installation writes to user home directories
4. **Use containerized envs** — Test in a VM or container first if unsure
5. **Rotate API keys** — If using cloud embeddings, rotate keys periodically
6. **Monitor logs** — Check `~/.nima/logs/` for suspicious activity

### Data Locations

```text
~/.nima/
├── memory/
│   ├── graph.sqlite       # SQLite backend (default)
│   ├── ladybug.lbug       # LadybugDB backend (optional)
│   ├── embedding_cache.db # Cached embeddings
│   └── embedding_index.npy# Vector index
├── affect/
│   └── affect_state.json  # Current emotional state
└── logs/                  # Debug logs (if enabled)

~/.openclaw/extensions/
├── nima-memory/           # Capture hook
├── nima-recall-live/     # Recall hook
└── nima-affect/          # Affect hook
```

**Controls:**
```json
{
  "plugins": {
    "entries": {
      "nima-memory": {
        "skip_subagents": true,
        "skip_heartbeats": true,
        "noise_filtering": { "filter_system_noise": true }
      }
    }
  }
}
```

## Configuration

### Embedding Providers

| Provider | Setup | Dims | Cost |
|----------|-------|------|------|
| **Local** (default) | `NIMA_EMBEDDER=local` | 384 | Free |
| **Voyage AI** | `NIMA_EMBEDDER=voyage` + `VOYAGE_API_KEY` | 1024 | $0.12/1M tok |
| **OpenAI** | `NIMA_EMBEDDER=openai` + `OPENAI_API_KEY` | 1536 | $0.13/1M tok |
| **Ollama** | `NIMA_EMBEDDER=ollama` + `NIMA_OLLAMA_MODEL` | 768 | Free |

### Database Backend

| | SQLite (default) | LadybugDB (recommended) |
|--|-----------------|------------------------|
| Text Search | 31ms | **9ms** (3.4x faster) |
| Vector Search | External | **Native HNSW** (18ms) |
| Graph Queries | SQL JOINs | **Native Cypher** |
| DB Size | ~91 MB | **~50 MB** (44% smaller) |

Upgrade: `pip install real-ladybug && python -c "from nima_core.storage import migrate; migrate()"`

### All Environment Variables

```bash
# Embedding (default: local)
NIMA_EMBEDDER=local|voyage|openai|ollama
VOYAGE_API_KEY=pa-xxx
OPENAI_API_KEY=sk-xxx
NIMA_OLLAMA_MODEL=nomic-embed-text

# Data paths
NIMA_DATA_DIR=~/.nima
NIMA_DB_PATH=~/.nima/memory/ladybug.lbug

# Memory pruner
NIMA_DISTILL_MODEL=claude-haiku-4-5
ANTHROPIC_API_KEY=sk-ant-xxx

# Logging
NIMA_LOG_LEVEL=INFO
NIMA_DEBUG_RECALL=1
```

## Hooks

| Hook | Fires | Does |
|------|-------|------|
| `nima-memory` | After save | Captures 3 layers → filters noise → stores in graph DB |
| `nima-recall-live` | Before LLM | Searches memories → scores by ecology → injects as context (3000 token budget) |
| `nima-affect` | On message | VADER sentiment → Panksepp 7-affect state → archetype modulation |

### Installation

```bash
./install.sh
openclaw gateway restart
```

Or manual:
```bash
cp -r openclaw_hooks/nima-memory ~/.openclaw/extensions/
cp -r openclaw_hooks/nima-recall-live ~/.openclaw/extensions/
cp -r openclaw_hooks/nima-affect ~/.openclaw/extensions/
```

## Advanced Features

### Dream Consolidation
Nightly synthesis extracts insights and patterns from episodic memory:
```bash
python -m nima_core.dream_consolidation
# Or schedule via OpenClaw cron at 2 AM
```

### Memory Pruner
Distills old conversations into semantic gists, suppresses raw noise:
```bash
python -m nima_core.memory_pruner --min-age 14 --live
python -m nima_core.memory_pruner --restore 12345  # undo within 30 days
```

### Hive Mind
Multi-agent memory sharing:
```python
from nima_core import HiveMind
hive = HiveMind(db_path="~/.nima/memory/ladybug.lbug")
context = hive.build_agent_context("research task", max_memories=8)
hive.capture_agent_result("agent-1", "result summary", "model-name")
```

### Precognition
Temporal pattern mining → predictive memory pre-loading:
```python
from nima_core import NimaPrecognition
precog = NimaPrecognition(db_path="~/.nima/memory/ladybug.lbug")
precog.run_mining_cycle()
```

### Lucid Moments
Spontaneous surfacing of emotionally-resonant memories (with safety: trauma filtering, quiet hours, daily caps):
```python
from nima_core import LucidMoments
lucid = LucidMoments(db_path="~/.nima/memory/ladybug.lbug")
moment = lucid.surface_moment()
```

### Affect System
Panksepp 7-affect emotional intelligence with personality archetypes:
```python
from nima_core import DynamicAffectSystem
affect = DynamicAffectSystem(identity_name="my_bot", baseline="guardian")
state = affect.process_input("I'm excited about this!")
# Archetypes: guardian, explorer, trickster, empath, sage
```

## API

```python
from nima_core import (
    DynamicAffectSystem,
    get_affect_system,
    HiveMind,
    NimaPrecognition,
    LucidMoments,
)

# Affect (thread-safe singleton)
affect = get_affect_system(identity_name="lilu")
state = affect.process_input("Hello!")

# Hive Mind
hive = HiveMind()
context = hive.build_agent_context("task description")

# Precognition
precog = NimaPrecognition()
precog.run_mining_cycle()

# Lucid Moments
lucid = LucidMoments()
moment = lucid.surface_moment()
```

## Changelog

See [CHANGELOG.md](./CHANGELOG.md) for full version history.

### Recent Releases
- **v3.0.4** (Feb 23, 2026) — Darwinian memory engine, new CLIs, installer, bug fixes
- **v2.5.0** (Feb 21, 2026) — Hive Mind, Precognition, Lucid Moments
- **v2.4.0** (Feb 20, 2026) — Dream Consolidation engine
- **v2.3.0** (Feb 19, 2026) — Memory Pruner, connection pool, Ollama support
- **v2.2.0** (Feb 19, 2026) — VADER Affect, 4-phase noise remediation, ecology scoring
- **v2.0.0** (Feb 13, 2026) — LadybugDB backend, security hardening, 348 tests

## License

MIT — free for any AI agent, commercial or personal.

Comments 0

Latest | Hot

Please login before commenting.

No comments yet. Be the first one!

nima-core

Directory Structure

SKILL.md

Report

Notice