<p align="center">
  <img src="https://raw.githubusercontent.com/myProjectsRavi/neuroVault/main/assets/readme/neurovault-banner.svg" alt="NEUROVAULT banner" width="100%" />
</p>

<div align="center">

# NEUROVAULT

### The Human Brain's Digital Twin

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

[![CI](https://img.shields.io/badge/CI-passing-brightgreen)](#development)
[![Coverage](https://img.shields.io/badge/Tests-96%20passing-blue)](#development)
[![Version](https://img.shields.io/badge/version-0.3.1-blue)](https://pypi.org/project/neurovault/)
[![License](https://img.shields.io/badge/license-MIT-green.svg)](https://github.com/myProjectsRavi/neuroVault/blob/main/LICENSE)

<p>
  <a href="#quick-start"><img src="https://img.shields.io/badge/Quick_Start-Get_running_in_minutes-1f6feb?style=flat-square" alt="Quick Start" /></a>
  <a href="#architecture"><img src="https://img.shields.io/badge/Architecture-Cognitive_memory_pipeline-0d8b6f?style=flat-square" alt="Architecture" /></a>
  <a href="#python-sdk"><img src="https://img.shields.io/badge/Python_SDK-Integration_surface-6f42c1?style=flat-square" alt="Python SDK" /></a>
  <a href="#security-and-privacy"><img src="https://img.shields.io/badge/Security-Local_first_and_hardened-b60205?style=flat-square" alt="Security" /></a>
</p>

</div>

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

<p align="center">
  <img src="https://raw.githubusercontent.com/myProjectsRavi/neuroVault/main/assets/readme/section-divider.svg" alt="section divider" width="100%" />
</p>

## Table of Contents

- [Why NEUROVAULT](#why-neurovault)
- [Feature Cards](#feature-cards)
- [Architecture](#architecture)
- [Quick Start](#quick-start)
- [Python SDK](#python-sdk)
- [CLI Overview](#cli-overview)
- [REST API](#rest-api)
- [Port Map](#port-map)
- [API Reference](#api-reference)
- [Guides](#guides)
- [Project Structure](#project-structure)
- [Security and Privacy](#security-and-privacy)
- [Development](#development)
- [Contributing](#contributing)
- [License](#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

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

<p align="center">
  <img src="https://raw.githubusercontent.com/myProjectsRavi/neuroVault/main/assets/readme/section-divider.svg" alt="section divider" width="100%" />
</p>

## Architecture

```mermaid
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

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

### 2) Initialize a vault

```bash
neurovault init my-brain
```

### 3) Ingest and recall

```bash
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

```bash
neurovault consolidate
neurovault entities
neurovault status
```

### 5) Run daemon or API server

```bash
# background memory daemon
neurovault start

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

<p align="center">
  <img src="assets/readme/section-divider.svg" alt="section divider" width="100%" />
</p>

## Python SDK

```python
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](https://github.com/myProjectsRavi/neuroVault/blob/main/API_REFERENCE.md)

## Guides

- [Quickstart](https://github.com/myProjectsRavi/neuroVault/blob/main/Docs/quickstart.md)
- [Sensors](https://github.com/myProjectsRavi/neuroVault/blob/main/Docs/sensors.md)

## Project Structure

```text
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](https://github.com/myProjectsRavi/neuroVault/blob/main/SECURITY.md)

## Development

```bash
# 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](https://github.com/myProjectsRavi/neuroVault/blob/main/CONTRIBUTING.md) before opening pull requests.

## License

MIT - see [LICENSE](https://github.com/myProjectsRavi/neuroVault/blob/main/LICENSE).
