neurovault 0.3.1

The Human Brain's Digital Twin - passive ingestion, consolidation, and predictive memory

NEUROVAULT

The Human Brain's Digital Twin

Persistent AI memory engine with consolidation, graph intelligence, and proactive recall

NEUROVAULT is the cognitive memory layer for AI systems. It continuously ingests events, structures memory, consolidates related knowledge, and serves high-quality recall through multi-signal search.

CHRONOS and NEUROVAULT are complementary:

• CHRONOS: memory protocol, versioning, and synchronization substrate
• NEUROVAULT: memory understanding, consolidation, prediction, and retrieval intelligence

Table of Contents

• Why NEUROVAULT
• Feature Cards
• Architecture
• Quick Start
• Python SDK
• CLI Overview
• REST API
• Port Map
• API Reference
• Guides
• Project Structure
• Security and Privacy
• Development
• Contributing
• License

Why NEUROVAULT

Most AI assistants are stateless between sessions and shallow during retrieval. NEUROVAULT adds a persistent cognitive layer that behaves more like working memory plus long-term memory:

• Captures structured and unstructured signals
• Extracts entities and relationships continuously
• Builds and traverses a connected memory graph
• Runs consolidation cycles (cluster, insight, promote, decay)
• Performs multi-signal recall (keyword, semantic, graph, temporal)
• Surfaces relevant memory proactively through prediction

Feature Cards

Memory Ingestion CLI, sensors, and API pipelines capture live context with privacy filtering before persistence.	Knowledge Graph Entities, relationships, and memory links create a traversable cognitive network.	Consolidation Engine Transforms raw traces into durable insights via clustering, synthesis, promotion, and decay.
Multi-Signal Search Fuses keyword, semantic, graph, and temporal evidence for high-precision recall.	Prediction Layer Proactively surfaces likely-relevant memory before explicit user prompts.	Security by Default RBAC, audit trail, encryption support, loopback-safe services, and hardened API checks.

Architecture

flowchart TD
    A["Sensors / API / CLI Input"] --> B["Ingestion + Privacy Filter"]
    B --> C["Memory Store"]
    C --> D["Entity + Relationship Extraction"]
    D --> E["Knowledge Graph"]
    C --> F["Consolidation Strategy"]
    F --> G["Clusters + Insights + Promotion/Decay"]
    C --> H["Multi-Signal Search"]
    E --> H
    G --> H
    H --> I["Recall Results"]
    H --> J["Prediction Engine"]
    J --> K["Proactive Suggestions"]
    C --> L["Federation / Sync Layer"]

Quick Start

1) Install

# from repo root
pip install -e ".[dev]"

2) Initialize a vault

neurovault init my-brain

3) Ingest and recall

neurovault ingest "User prefers dark mode and uses vim"
neurovault ingest "Roadmap deadline is March 30" --source notes
neurovault recall "user preferences" --mode multi

4) Consolidate and inspect

neurovault consolidate
neurovault entities
neurovault status

5) Run daemon or API server

# background memory daemon
neurovault start

# REST API (default: 127.0.0.1:8787)
neurovault serve --host 127.0.0.1 --port 8787

Python SDK

from neurovault import NeurovaultConfig, NeurovaultEngine

cfg = NeurovaultConfig.load()
engine = NeurovaultEngine.init("assistant-memory", description="Personal AI memory")

engine.ingest("Alice works on distributed AI systems", source="chat", importance=0.8)
engine.ingest("Team sync every Monday at 10am", source="calendar", importance=0.7)

results = engine.recall("when is team sync", mode="multi", limit=5)
for hit in results:
    print(hit.memory.content, hit.score)

report = engine.consolidate(force=True)
print(report.insights_generated)

CLI Overview

Domain	Commands
Vault lifecycle	init, status, stats
Memory operations	ingest, recall, review, forget, reinforce
Knowledge graph	entities, relations, graph, insights
Consolidation	consolidate, decay
Operations	start, stop, serve, dashboard
Security	access *, encrypt *, audit, audit-log, verify
CHRONOS-native surfaces	chronos-graph *, persona *, merge, checkpoint, log, diff, revert, sync *, keys generate

Use neurovault --help and neurovault <command> --help for full options.

REST API

When running neurovault serve, key endpoints include:

• GET /api/v1/health
• POST /api/v1/ingest
• POST /api/v1/recall
• POST /api/v1/consolidate
• GET /api/v1/entities
• GET /api/v1/insights
• GET /api/v1/status
• GET /metrics (Prometheus)

Port Map

Port	Service	Notes
8080	REST API container port	Main HTTP API in container/deploy contexts
9473	Federation server	Peer sync transport (disabled unless configured)
9474	Mobile API	Companion/mobile access surface
9475	WebSocket stream	Real-time event streaming
8501	Streamlit dashboard	Optional local dashboard UI

API Reference

Detailed request/response schemas: API_REFERENCE.md

Guides

• Quickstart
• Sensors

Project Structure

src/
  neurovault/
    engine.py              # Core cognitive engine API
    api.py                 # FastAPI service
    bridge.py              # CHRONOS bridge + fallback
    storage.py             # SQLite + FTS5 + graph persistence
    cognitive/             # consolidation, prediction, extraction
    search/                # multi-signal retrieval + HNSW
    network/               # federation/sync primitives
    sensors/               # passive capture integrations
    security/              # RBAC, audit, encryption

monitoring/                # Prometheus + Grafana provisioning
k8s/                       # Kubernetes manifests (kustomize-ready)
deploy/                    # container + systemd deployment assets
tests/                     # unit + integration + property + benchmark

CHRONOS runtime support is provided through the external chronos-memory dependency.

Security and Privacy

• Local-first by default
• Privacy/content filtering before persistence
• Token-based RBAC plus device tokens plus audit trail
• Encryption support for vault storage
• Loopback-safe defaults for local services

Security policy and reporting: SECURITY.md

Development

# run tests
pytest -q

# lint + type check
ruff check src/
ruff format --check src/
mypy src/neurovault/ --ignore-missing-imports

Contributing

Please read CONTRIBUTING.md before opening pull requests.

License

MIT - see LICENSE.