← Back to AI & LLMs
AI & LLMs by @dmdorta1111

nima-core

Biologically-inspired cognitive memory for AI agents

0
Source Code

NIMA Core 2.0

Neural Integrated Memory Architecture β€” A complete memory system for AI agents with emotional intelligence.

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

πŸš€ Quick Start

# Install
pip install nima-core

# Or with LadybugDB (recommended for production)
pip install nima-core[vector]

# Set embedding provider
export NIMA_EMBEDDER=voyage
export VOYAGE_API_KEY=your-key

# Install hooks
./install.sh --with-ladybug

# Restart OpenClaw
openclaw restart

πŸ”’ Privacy & Permissions

Data Access:

  • βœ… Reads session transcripts from ~/.openclaw/agents/*/sessions/*.jsonl
  • βœ… Writes to local storage at ~/.nima/ (databases, affect history, embeddings)

Network Calls (conditional on embedder choice):

  • 🌐 Voyage API β€” Only when NIMA_EMBEDDER=voyage (sends text for embeddings)
  • 🌐 OpenAI API β€” Only when NIMA_EMBEDDER=openai (sends text for embeddings)
  • πŸ”’ Local embeddings β€” Default (NIMA_EMBEDDER=local), no external API calls

Opt-in Controls:

// openclaw.json
{
  "plugins": {
    "entries": {
      "nima-memory": {
        "enabled": true,
        "skip_subagents": true,      // Exclude subagent sessions (default)
        "skip_heartbeats": true,      // Exclude heartbeat checks (default)
        "noise_filtering": {
          "filter_heartbeat_mechanics": true,
          "filter_system_noise": true
        }
      }
    }
  }
}

Privacy Defaults:

  • Subagent sessions excluded
  • Heartbeat/system noise filtered
  • Local embeddings (no external calls)
  • All data stored locally

To disable: Remove nima-memory from plugins.allow in openclaw.json

What's New in 2.0

LadybugDB Backend

  • 3.4x faster text search (9ms vs 31ms)
  • Native vector search with HNSW (18ms)
  • 44% smaller database (50MB vs 91MB)
  • Graph traversal with Cypher queries

Security Hardened

  • Query sanitization (FTS5, SQL injection prevention)
  • Path traversal protection
  • Temp file cleanup
  • Error handling throughout

Thread Safe

  • Singleton pattern with double-checked locking
  • API timeouts (30s Voyage, 10s LadybugDB)
  • Connection pooling ready

348 Tests

  • Full unit test coverage
  • Thread safety verified
  • Edge cases covered

Architecture

OPENCLAW HOOKS
β”œβ”€β”€ nima-memory      β€” Three-layer capture (input/contemplation/output)
β”œβ”€β”€ nima-recall-live β€” Lazy recall injection (before_agent_start)
└── nima-affect      β€” Real-time emotion detection

PYTHON CORE
β”œβ”€β”€ nima_core/cognition/
β”‚   β”œβ”€β”€ dynamic_affect.py     β€” Panksepp 7-affect system
β”‚   β”œβ”€β”€ personality_profiles.py β€” JSON personality configs
β”‚   β”œβ”€β”€ emotion_detection.py  β€” Lexicon-based emotionβ†’affect mapping
β”‚   └── archetypes.py         β€” Baseline affect profiles
└── scripts/
    β”œβ”€β”€ nima_ladybug_backend.py β€” LadybugDB CLI
    └── ladybug_parallel.py    β€” Parallel migration

DATABASE (SQLite or LadybugDB)
β”œβ”€β”€ memory_nodes   β€” Messages with embeddings
β”œβ”€β”€ memory_edges   β€” Graph relationships
└── memory_turns   β€” Conversation turns

Performance

Metric SQLite LadybugDB
Text Search 31ms 9ms (3.4x)
Vector Search External 18ms (native)
Database Size 91MB 50MB (44% smaller)
Context Tokens ~180 ~30 (6x smaller)

API

from nima_core import DynamicAffectSystem, get_affect_system

# Get singleton instance (thread-safe)
affect = get_affect_system(identity_name="lilu")

# Process input and get affect state
state = affect.process_input("I'm so excited about this project!")
print(state.current)  # {"SEEKING": 0.72, "PLAY": 0.65, ...}

# Recall memories (via hooks - automatic)
# Or manually via CLI:
# nima-query who_search "David" --limit 5
# nima-query text_search "project" --limit 5

Configuration

Variable Default Description
NIMA_DATA_DIR ~/.nima Memory storage path
NIMA_EMBEDDER voyage voyage, openai, or local
VOYAGE_API_KEY β€” Required for Voyage
NIMA_LADYBUG 0 Set 1 for LadybugDB backend

Hooks

nima-memory (Capture)

  • Captures input, contemplation, output on every turn
  • Stores to SQLite or LadybugDB
  • Computes and stores embeddings

nima-recall-live (Recall)

  • Injects relevant memories before agent starts
  • Lazy loading β€” only top N results
  • Deduplicates with injected context

nima-affect (Emotion)

  • Real-time emotion detection from text
  • Maintains Panksepp 7-affect state
  • Modulates response style

Installation Options

SQLite (Development)

pip install nima-core
./install.sh

LadybugDB (Production)

pip install nima-core[vector]
./install.sh --with-ladybug

Documentation

Guide Description
README.md Full system overview
SETUP_GUIDE.md Step-by-step installation
docs/DATABASE_OPTIONS.md SQLite vs LadybugDB
docs/EMBEDDING_PROVIDERS.md Voyage, OpenAI, Local
MIGRATION_GUIDE.md Migrate from old versions

Security & Privacy

Data Access

This plugin accesses:

  • ~/.openclaw/agents/.../*.jsonl β€” Session transcripts (for memory capture)
  • ~/.nima/ β€” Local memory database (SQLite or LadybugDB)
  • ~/.openclaw/extensions/ β€” Hook installation

Network Calls

Embeddings are sent to external APIs:

  • Voyage AI (api.voyageai.com) β€” Default embedding provider
  • OpenAI (api.openai.com) β€” Optional embedding provider
  • Local β€” No external calls when using sentence-transformers

Required Environment Variables

Variable Purpose Required
NIMA_EMBEDDER voyage, openai, or local No (default: voyage)
VOYAGE_API_KEY Voyage AI authentication If using Voyage
OPENAI_API_KEY OpenAI authentication If using OpenAI
NIMA_DATA_DIR Memory storage path No (default: ~/.nima)
NIMA_LADYBUG Use LadybugDB backend No (default: 0)

Installation Script

The install.sh script:

  1. Checks for Python 3 and Node.js
  2. Creates ~/.nima/ directories
  3. Installs Python packages via pip
  4. Copies hooks to ~/.openclaw/extensions/

No external downloads. All packages come from PyPI.

Changelog

v2.0.3 β€” Security Hardening (Feb 15, 2026)

  • Security: Fixed path traversal vulnerability in affect_history.py (CRITICAL)
  • Security: Fixed temp file resource leaks in 3 files (HIGH)
  • Fixed: Corrected non-existent json.JSONEncodeError β†’ TypeError/ValueError
  • Improved: Exception handling - replaced 5 generic catches with specific types
  • Quality: Better error visibility and debugging throughout

v2.0.1 β€” Thread Safety + Metadata

  • Fixed: Thread-safe singleton with double-checked locking
  • Security: Clarified metadata requirements (Node.js, env vars)
  • Docs: Added security disclosure for API key usage

v2.0.0 β€” LadybugDB + Security

  • Added: LadybugDB backend with HNSW vector search
  • Added: Native graph traversal with Cypher
  • Added: nima-query CLI for unified queries
  • Security: SQL/FTS5 injection prevention
  • Security: Path traversal protection
  • Security: Temp file cleanup
  • Fixed: Thread-safe singleton initialization
  • Fixed: API timeouts (Voyage 30s, LadybugDB 10s)
  • Tests: 348 tests passing
  • Performance: 3.4x faster text search, 44% smaller DB

v1.2.1 β€” Consciousness Architecture

  • Added: 8 consciousness systems (Ξ¦, Global Workspace, self-awareness)
  • Added: Sparse Block VSA memory
  • Added: ConsciousnessCore unified interface

v1.1.9 β€” Hook Efficiency Fix

  • Fixed: nima-recall hook spawning new Python process every bootstrap
  • Performance: ~50-250x faster hook recall

v1.2.0 β€” Affective Response Engines

  • Added: 4 Layer-2 composite affect engines
  • Added: Async affective processing
  • Added: Voyage AI embedding support