NIMA Core

# NIMA Core 2.3

**Neural Integrated Memory Architecture** — 为具备情感智能的 AI 代理构建的完整记忆系统。

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

## 🚀 Quick Start

```bash # 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:** - ✅ 从 `~/.openclaw/agents/*/sessions/*.jsonl` 读取会话记录 - ✅ 写入本地存储至 `~/.nima/`（数据库、情感历史、嵌入向量）

**Network Calls (conditional on embedder choice):** - 🌐 **Voyage API** — 仅当 `NIMA_EMBEDDER=voyage` 时（发送文本以获取嵌入） - 🌐 **OpenAI API** — 仅当 `NIMA_EMBEDDER=openai` 时（发送文本以获取嵌入） - 🔒 **Local embeddings** — 默认 (`NIMA_EMBEDDER=local`)，无外部 API 调用

**Opt-in Controls:** ```json // 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:** - 子代理会话已排除 - 心跳/系统噪声已过滤 - 本地嵌入（无外部调用） - 所有数据均在本地存储

**To disable:** 从 `openclaw.json` 的 `plugins.allow` 中移除 `nima-memory`

## What's New in 2.1

### VADER Affect Analyzer - **Contextual Analysis**: 全大写增强 (1.5x)，标点强调 (`!!!`)，否定处理，程度修饰词 - **30+ Idiom Recognition**: 理解诸如 "not bad"、"kind of"、"sort of" 等短语 - **Panksepp 7-Affect Mapping**: 从 VADER 情感直接映射到 SEEKING, RAGE, FEAR, LUST, CARE, PANIC, PLAY - **Guardian Archetype Transformation**: 用户愤怒 → 代理关注/关怀响应调制 - 取代了之前的基于词典的情感检测

### Noise Remediation (4-Phase) 1. **Empty Validation** — 过滤掉 null/空消息 2. **Heartbeat Filters** — 排除系统噪声 (`HEARTBEAT_OK`，轮询消息) 3. **Deduplication** — 移除会话内的重复内容 4. **Metrics Collection** — 跟踪捕获质量和过滤效果

### Performance Improvements - **LadybugDB Circular Import Fix**: 解决了 LadybugDB 后端的导入问题 - **Increased Token Budget**: 回显预算从 500 增加到 3000 tokens - **Connection Pooling**: 改进了 LadybugDB 后端的连接管理

## What's New in 2.0

### LadybugDB Backend - **3.4x faster** 文本搜索 (9ms vs 31ms) - **Native vector search** 使用 HNSW (18ms) - **44% smaller** 数据库 (50MB vs 91MB) - 使用 Cypher 查询进行 **Graph traversal**

### Security Hardened - 查询净化 (FTS5，SQL 注入防护) - 路径遍历防护 - 临时文件清理 - 全面的错误处理

### Thread Safe - 带双重检查锁定（double-checked locking）的单例模式 - API 超时 (30s Voyage, 10s LadybugDB) - 就绪的连接池

### 348 Tests - 完整的单元测试覆盖 - 线程安全已验证 - 边缘情况已覆盖

## Architecture

```text OPENCLAW HOOKS ├── nima-memory — Three-layer capture with 4-phase noise remediation ├── nima-recall-live — Lazy recall injection (before_agent_start) └── nima-affect — VADER-based real-time affect analysis

PYTHON CORE ├── nima_core/cognition/ │ ├── dynamic_affect.py — Panksepp 7-affect system │ ├── personality_profiles.py — JSON personality configs │ ├── vader_affect.py — VADER sentiment analyzer (NEW v2.1) │ └── 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) | | Context Tokens | ~180 | **~30** (6x smaller) | | Recall Token Budget | 500 | **3000** (v2.1+) |

## API

```python from nima_core import DynamicAffectSystem, get_affect_system from nima_core.cognition.vader_affect import VaderAffectAnalyzer

# 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, ...}

# Use VADER analyzer directly analyzer = VaderAffectAnalyzer() result = analyzer.analyze("This is AMAZING!!!") print(result.affects) # {'PLAY': 0.78, 'SEEKING': 0.71, ...}

# 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) - 在每一轮捕获输入、思考、输出 - 4阶段噪声过滤（空值校验、心跳过滤、去重、指标） - 存储至 SQLite 或 LadybugDB - 计算并存储嵌入向量

### nima-recall-live (Recall) - 在代理启动前注入相关记忆 - 延迟加载 — 仅加载前 N 条结果 - 与注入的上下文去重 - Token 预算：3000 (在 v2.1 中从 500 增加)

### nima-affect (Emotion) - 基于文本的 VADER 实时情感分析 - 上下文分析（全大写、标点、否定、程度修饰词） - 30+ 习语识别 - 维护 Panksepp 7 情感状态 - 监护者原型转换（用户愤怒 → 代理关怀）

## Installation Options

### SQLite (Development) ```bash pip install nima-core ./install.sh ```

### LadybugDB (Production) ```bash pip install nima-core[vector] ./install.sh --with-ladybug ```

## Documentation

| Guide | Description | |-------|-------------| | [README.md](./README.md) | Full system overview | | [SETUP_GUIDE.md](./SETUP_GUIDE.md) | Step-by-step installation | | [docs/DATABASE_OPTIONS.md](./docs/DATABASE_OPTIONS.md) | SQLite vs LadybugDB | | [docs/EMBEDDING_PROVIDERS.md](./docs/EMBEDDING_PROVIDERS.md) | Voyage, OpenAI, Local | | [MIGRATION_GUIDE.md](./MIGRATION_GUIDE.md) | Migrate from old versions | | [CHANGELOG.md](./CHANGELOG.md) | Release history |

## 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.1.0 — VADER Affect Analyzer (Feb 17, 2026) - **Added:** VADER-based affect analyzer replacing lexicon-based detection - Contextual analysis: caps boost (1.5x), punctuation (!!!), negation, degree modifiers - 30+ idiom recognition - Panksepp 7-affect mapping (SEEKING, RAGE, FEAR, LUST, CARE, PANIC, PLAY) - Guardian archetype transformation (user anger → agent concern/care) - **Added:** 4-phase noise remediation (empty validation, heartbeat filters, dedup, metrics) - **Fixed:** LadybugDB circular import issue - **Changed:** Recall token budget increased from 500 to 3000 - **Improved:** Connection pooling for LadybugDB backend

### 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