Metadata-Version: 2.4
Name: NWcortex
Version: 1.0.4
Summary: NeuroWeave Cortex (NWC) — Graph-first cognitive memory runtime for AI agents. Hippocampal-inspired architecture with domain routing, spreading activation, edge budget management, 4-layer compression, thermal storage, personality modeling, and 8-phase sleep consolidation.
Author-email: Thatgfsj <thatgfsj@users.noreply.github.com>
License: MIT
Project-URL: repository, https://github.com/Thatgfsj/neuroweave-cortex
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.24.0
Requires-Dist: PyYAML>=6.0
Requires-Dist: scikit-learn>=1.3.0
Provides-Extra: embeddings
Requires-Dist: sentence-transformers>=2.2.0; extra == "embeddings"
Provides-Extra: mcp
Requires-Dist: mcp>=1.0.0; extra == "mcp"
Provides-Extra: all
Requires-Dist: sentence-transformers>=2.2.0; extra == "all"
Requires-Dist: mcp>=1.0.0; extra == "all"
Dynamic: license-file

# NeuroWeave Cortex (NWC) — Cognitive Memory Runtime

An infrastructure-grade memory system for AI agents. Not a vector database. Not a graph database. A **memory runtime** — it remembers, forgets, strengthens, connects, abstracts, and evolves, the way biological memory does.

```
Anchors: 131   Edges: 211   Ghosts: 0   Schemas: 9   Abstracts: 1
Memory Stability: 0.72   Recall Plasticity: 0.58   Compression: 1.6x
```

## What makes it different

Vector databases retrieve. Graph databases traverse. NeuroWeave Cortex runs a **cognitive lifecycle**:

| Capability | Vector DB | Graph DB | NeuroWeave Cortex |
|---|---|---|---|
| Semantic retrieval | yes | no | yes |
| Graph traversal | no | yes | yes |
| Automatic forgetting (survival decay) | no | no | yes |
| Memory strengthening (rehearsal) | no | no | yes |
| Conflict detection (contradiction edges) | no | no | yes |
| Multi-strategy RRF retrieval fusion | no | no | yes |
| Cross-Encoder reranking | no | no | yes |
| Explainable reasoning paths | no | no | yes |
| Memory revision engine (sleep) | no | no | yes |
| Hot/Warm/Cold memory tiering | no | no | yes |
| Multimodal (text+image+audio) | no | no | yes |
| Fuzzy recall ("I think I remember...") | no | no | yes |
| Emergent abstraction (pattern discovery) | no | no | yes |
| Temporal context (TimeSpine-indexed) | no | no | yes |
| 8-phase sleep consolidation | no | no | yes |
| Ghost revival (savings effect) | no | no | yes |
| Autobiographical self-model | no | no | yes |

## Quick Start

```python
from star_graph import MemoryManager
from star_graph.scheduler import AgentContext

# One-line setup
mgr = MemoryManager()

# Remember things
mgr.remember("User debugs Redis connection timeout — pool was 10, fixed to 20",
             tags=["redis", "debug", "timeout"])
mgr.remember("User knows Python async programming with asyncio",
             tags=["python", "knowledge"])
mgr.remember("User prefers type hints and concise code",
             tags=["preference", "style"])

# Working memory — fast, ephemeral buffer for active context
mgr.remember_working("Currently debugging auth middleware timeout",
                     tags=["debug", "auth"])

# Context-aware recall — working memory gets retrieval priority
ctx = AgentContext(task_type="debugging", active_goals=["fix Redis connection"])
memories = mgr.recall("Redis connection pool config", context=ctx)
print(memories.memory_summary)

# System-2 deep recall for exhaustive or low-confidence queries
memories = mgr.dual_recall("list all Redis-related issues", context=ctx)

# Micro-consolidation — incremental, non-blocking
mgr.micro_consolidate()

# Let the system sleep — 8-phase consolidation
report = mgr.sleep()
print(report)

# Persist
mgr.save("agent_memory.json")
mgr.load("agent_memory.json")

# Export to editable Markdown (GBrain-aligned)
mgr.export_markdown("memories/")
```

## Architecture

Three-layer design. Each layer depends only on the one below.

```
Layer 3: Behavior    │  Cortex routing, memory gating, working memory,
    (cortex.py,      │  dual-channel retrieval, adaptive replay, autobiographical memory
     router.py,      │  "What should I recall right now, at what detail level?"
     gate.py,        │
     working_memory.py,│
     scheduler.py,   │
     autobiography.py)│
                     │
Layer 2: Cognitive   │  Hub abstraction, cascade recall, TimeSpine temporal index,
    (retriever.py,   │  sleep consolidation, evolution, ghost revival,
     sleep.py,       │  abstraction, community detection, competition,
     evolution.py,   │  conflict detection, memory revision, cross-encoder
     ghost.py,       │  "How do memories connect, strengthen, and fade?"
     abstraction.py, │
     community.py,   │
     competition.py, │
     conflict_detection.py,│
     memory_revision.py,   │
     cross_encoder.py,     │
     timespine.py,   │
     cascade.py,     │
     hub.py)         │
                     │
Layer 1: Storage     │  CRUD, persistence, ANN indexing, tiered storage,
    (graph.py,       │  BM25 keyword index, multi-level caching
     anchor.py,      │  "Where is this memory stored?"
     storage.py,     │
     sqlite_storage.py,│
     index.py,       │
     bm25.py,        │
     cognitive_cache.py,│
     tier.py)        │
```

### Core modules

| Module | Role |
|---|---|
| `manager.py` | High-level facade — `remember()`, `recall()`, `sleep()`, `save()` |
| `runtime.py` | Dependency container — manages all subsystem lifecycles |
| `retrieval_pipeline.py` | 5-layer dimensional descent (L0→L4) with automatic degradation |
| `scheduler.py` | Context-aware retrieval with memory type selection |
| `working_memory.py` | Short-term buffer (15-item, 1h TTL) — auto-promotes to long-term |
| `sleep.py` | 10-phase sleep: N1_Replay → N2_Merge → N2b_ConflictDetection → N2c_MemoryRevision → N3_Compression → N3d_SleepRebuild → REM_Emotion → N4_Prune (v1.0.4) |
| `evolution.py` | Survival-based decay (Ebbinghaus/Power-law/Exponential), belief transitions, interference |
| `retriever.py` | HybridFusion + OscillationResonance + VectorSimilarity + Personalized PageRank + explainable scores |
| `dual_channel.py` | System-1 (fast) + System-2 (deep) dual-channel retrieval with auto-trigger |
| `bm25.py` | Sparse keyword retrieval (BM25) with weighted reciprocal rank fusion for hybrid search |
| `cross_encoder.py` | Post-retrieval Cross-Encoder reranking (sentence-transformers) for precision improvement |
| `conflict_detection.py` | Semantic contradiction detection with overwrite/coexist/deprecate resolution strategies |
| `memory_revision.py` | Sleep-phase memory revision engine — surprise-prioritized, template/LLM re-summarization |
| `ghost.py` | Latent memory traces with fuzzy recall and contradiction tracking (NegativeGhost) |
| `abstraction.py` | Emergent category discovery from anchor clusters |
| `community.py` | Louvain community detection with centroid routing |
| `anchor.py` | Memory unit with 6-state lifecycle, 10-dim AnchorVector, multiplicative retention |
| `graph.py` | Star graph with RichEdge (temporal, causal, state-transition), Schema, ReflectionNode |
| `timespine.py` | Temporal index for O(days×buckets) time-scoped retrieval |
| `cascade.py` | Causal chain traversal across connected memory sequences |
| `hub.py` | Hierarchical hub-and-spoke abstraction (leaf→domain→global) |
| `cortex.py` | Partitioned memory cortices with independent sleep and retrieval |
| `cognitive_cache.py` | Multi-level cache (query/session/topic/activation) + exact-match entity lookup |
| `tier.py` | STM/MTM/LTM/Core cognitive tiering + HOT/WARM/COLD storage tiers |
| `autobiography.py` | Self-narrative formation and autobiographical memory |
| `atom_facts.py` | LLM-powered atomic fact extraction from memory clusters |
| `survival.py` | Pluggable survival functions (Ebbinghaus, Power-law, Exponential, Custom) |
| `compression.py` | Multi-level session compression (episodic/strategic/meta) |
| `resonance.py` | Phase-locked oscillation resonance for temporal-coherent retrieval |
| `streaming.py` | Streaming memory buffer with backpressure |
| `benchmark.py` | Built-in benchmark suite (5 categories) |
| `batch_vectorizer.py` | Deferred batch embedding writes (buffer >= 32 / >30s flush) with SQLite WAL crash recovery |
| `zero_llm_pipeline.py` | 7-stage zero-LLM ingestion: security → embed → dedup → entity → classify → score → link |
| `multimodal.py` | Cross-modal text/image/audio memory — CLIP image encoding, Whisper/spectrogram audio, unified embedding space |
| `forget_certificate.py` | Ed25519-signed JWS deletion certificates — GDPR Article 17 provable erasure |
| `markdown_export.py` | Operator-owned plain-text memory export (GBrain-aligned); timeline + topic Markdown |
| `config.py` | Centralized YAML config with schema validation, dot-path access, overrides |

## Retrieval Benchmarks

### LoCoMo Benchmark (real-world conversations)

Evaluated on the [LoCoMo-10 dataset](https://github.com/snap-research/LoCoMo): 10 conversations, 5,882 turns across 272 sessions, 1,986 QA pairs across 5 categories. Pure retrieval (no LLM generation).

| Method | has_answer | F1 | Latency |
|---|---|---|---|
| VectorSimilarity | 13.1% | 0.026 | 122.2ms |
| OscillationResonance | 11.9% | 0.026 | 110.4ms |
| **HybridFusion + BM25** | **15.3%** | **0.025** | <200ms |

Per-category has_answer:

| Category | #QA | VecSim | OscRes | HybFus |
|---|---|---|---|---|
| Temporal (1) | 282 | 3.5% | 2.8% | 4.3% |
| Short Memory (2) | 321 | 1.9% | 2.2% | 1.9% |
| Long Memory (3) | 96 | 2.1% | 2.1% | 3.1% |
| Composite (4) | 841 | 18.0% | 16.4% | 21.0% |
| Adversarial (5) | 446 | 20.4% | 18.4% | 23.5% |

### Internal Benchmark (synthetic multi-session)

6 sessions × 80 turns, 5 categories. 1.7x compression (6,708 → 3,982 tokens) with maintained or improved recall.

| Method | C-R@3 | C-R@5 | Interf |
|---|---|---|---|
| VectorSimilarity | 0.933 | 0.933 | N/A |
| **OscillationResonance** | **0.967** | **0.967** | 0.667 |
| HybridFusion | 0.900 | 0.900 | 0.667 |

## Memory Lifecycle

Every anchor moves through 6 states:

```
ACTIVE → REHEARSING → CONSOLIDATING → DORMANT → GHOST → REACTIVATED
```

- **Active**: Just created or recently accessed — fully plastic, easy to update
- **Rehearsing**: Being replayed during sleep — temporarily elevated importance
- **Consolidating**: Transferring from hippocampal to cortical — increasing stability
- **Dormant**: Stable, low-activity — read-only, cortical retrieval
- **Ghost**: Pruned but with residual trace — can partially recall or fully revive
- **Reactivated**: Ghost revived by new relevant experience — reduced stability, high plasticity

Paired with **ThermalState** (HOT → WARM → COLD → DEAD) for storage tier switching:
- HOT: in-memory, fully accessible
- WARM: in-memory, periodically flushed to disk
- COLD: disk-only, transparent thaw on access

## Sleep Consolidation

Sleep is not cleanup. Sleep **changes the graph**:

1. **N1_Replay** — prioritizes surprising and emotional memories for replay via SWR scoring
2. **N2_Merge** — fuses near-duplicate anchors (ANN-accelerated, O(n×k)), bridges constellations
3. **N3_Compression** — transfers memories from hippocampal to cortical, forms schemas
4. **N3b_AtomFacts** — LLM extraction of atomic facts from compressed clusters
5. **REM_Emotion** — strips emotional charge from consolidated memories
6. **N4_Prune** — removes weak anchors/edges, creates ghost traces for savings effect
7. **N5_HubConnect** — cross-cortex hub bridge formation
8. **N6_IndexRebuild** — refreshes ANN, BM25, and community indices

## Dual-Channel Retrieval

System-1 (fast, embedding + BM25 hybrid) and System-2 (deep, hierarchical traversal) with automatic triggering:

- Low-confidence System-1 results (<0.35) automatically trigger System-2
- Structural keywords ("all", "every", "list", "which", "before", "last") trigger exhaustive search
- Results merged via weighted reciprocal rank fusion

## Configuration

```python
from star_graph.config import config, override, load_config

# Dot-path access
threshold = config.sleep.merge.default_threshold  # 0.85

# Programmatic override
override('sleep.merge.default_threshold', 0.75)
override('gate.k', 30)

# Schema validation
warnings = config.validate()  # type, range, and cross-section checks

# Load custom YAML
cfg = load_config("my_params.yaml")
```

See `star_graph/defaults.yaml` for all 300+ tunable parameters.

## Installation

```bash
# From PyPI (package name: NWcortex, import as: star_graph)
pip install NWcortex

# With sentence-transformers for semantic embeddings
pip install "NWcortex[embeddings]"

# With MCP server support (for AI agent integration)
pip install "NWcortex[mcp]"

# Everything
pip install "NWcortex[all]"

# Run demo
python examples/emergence_demo.py
```

**Note:** Without `[embeddings]`, the system uses a lightweight TF-IDF fallback for text encoding. Install `sentence-transformers` only if you need semantic-quality embeddings.

## MCP Server — AI Agent Integration

NeuroWeave Cortex ships with a [Model Context Protocol](https://modelcontextprotocol.io) server. Connect any MCP-compatible AI agent (Claude Desktop, OpenClaw, Cursor, etc.) for persistent cognitive memory across conversations.

### Quick start

```bash
# Install with MCP support
pip install "NWcortex[mcp]"

# Launch the MCP server on stdio
nwc-mcp

# With persistent storage
nwc-mcp --storage agent_memory.json

# Load a previously saved memory graph
nwc-mcp --load my_memories.json
```

### Tool reference (12 tools)

| Tool | Description |
|------|-------------|
| `remember` | Store a long-term memory (tags, importance, emotional valence) |
| `remember_working` | Store in fast ephemeral working-memory buffer (current task context) |
| `recall` | Context-aware semantic retrieval with task-type routing |
| `forget` | Remove a memory, creating a ghost trace for potential fuzzy recall |
| `sleep` | Run 5-phase sleep consolidation — merges, prunes, forms schemas |
| `consolidate` | Micro-consolidation — incremental, non-blocking |
| `stats` | Memory system statistics (anchors, edges, ghosts, schemas, cognitive health) |
| `fuzzy_recall` | Low-confidence recall from ghost traces ("I seem to remember...") |
| `get_profile` | Inferred user profile from accumulated memories |
| `evolve` | Memory evolution cycle (decay, boost, conflict resolution) |
| `save` | Persist memory graph to disk (JSON) |
| `load` | Load memory graph from disk (JSON) |

### Claude Desktop config

```json
{
  "mcpServers": {
    "neuroweave-cortex": {
      "command": "nwc-mcp",
      "args": ["--storage", "/path/to/agent_memory.json"]
    }
  }
}
```

### OpenClaw config

```json
{
  "mcpServers": {
    "neuroweave-cortex": {
      "command": "nwc-mcp",
      "args": ["--storage", "/path/to/agent_memory.json"]
    }
  }
}
```

## REST API Server

```bash
# Start the REST server
nwc-server --port 8420

# Or via module
python -m star_graph.server --port 8420
```

Endpoints:

| Method | Path | Description |
|--------|------|-------------|
| GET | `/health` | Health check with anchor/edge counts |
| GET | `/metrics` | Prometheus-format metrics |
| GET | `/stats` | Full memory system statistics |
| POST | `/remember` | Store a memory `{"text": "...", "tags": [...]}` |
| POST | `/recall` | Retrieve memories `{"query": "...", "max_items": 10}` |
| POST | `/sleep` | Run sleep consolidation |
| POST | `/consolidate` | Run micro-consolidation |

## Interactive Demo

```bash
python examples/emergence_demo.py

# Or use the CLI:
# sg-add "Discussed microservices deployment patterns" --tags architecture --emotional 0.6
# sg-query "database connection pooling best practices"
# sg-query --trace "When did Alice visit Hawaii?"
# sg-stats --schemas --ghosts
# sg-sleep --retention 0.15 --edge-prune 0.1
# nwc-export --output memories/ --organize both
# nwc-forget <anchor_id> --certificate --reason gdpr_art17
# nwc-verify certificates/forget-<id>.jws
```

## Benchmarks

```bash
python examples/memory_benchmark.py --quick   # 4 sessions, ~200 turns
python examples/memory_benchmark.py --full    # 12 sessions, ~5000 turns
```

## Running Tests

```bash
pip install pytest pytest-cov
pytest tests/ -v

# With coverage report
pytest tests/ --cov=star_graph --cov-report=term
```

**Status:** 1,989 tests passing, 84 modules (v1.0.4-dev).

## Roadmap

See [ROADMAP.md](ROADMAP.md) for planned work.

## License

MIT
