# Nexus Memory Architecture

Standalone, pure-Python (stdlib-only) agent memory architecture extracted from **Nexus Harness v1.1** alongside the **Universal Memory-Vault MCP Server**. Designed for predictable multi-turn recall, deterministic noise gating, cross-session continuity, temporal graph relations, Markdown Wiki compilation, and zero-VRAM offline dreaming consolidation.

## Architecture Overview

| Module / Component | Role | Layer |
| :--- | :--- | :--- |
| `nexus/services/memory.py` (`Vault`) | SQLite FTS5 + BM25 + CJK `LIKE` hybrid search, dual-stream (`code` vs `interaction`) routing, temporal relation edges, node deactivation/superseding | L2 Core |
| `nexus/services/retrieval_gate.py` (`RetrievalGate`) | Zero-dependency turn gate skipping trivial confirmations and filtering low-overlap retrieval noise | L2 Core |
| `nexus/services/memory_wiki.py` (`MemoryWikiCompiler`) | Atomic Markdown Linked Wiki compiler (`INDEX.md`, per-node pages with `Outgoing Relations` and `## Backlinks`, dream digests) | L2 Core |
| `nexus/services/memory_dreaming.py` (`MemoryDreamingEngine`) | 5-stage deterministic consolidation (`SUPERSEDES` dedup, anchor linking & `CONTRADICTS`, stale decay, session/handoff distillation, Wiki sync) with `local_vram_guard` | L2 Core |
| `nexus/services/negative_extractor.py` (`NegativePatternExtractor`) | Scoped (`global`/`workspace`/`session`) + TTL negative constraints with quoted/fenced/meta-question false-positive guards | L2 Core |
| `nexus/services/user_profile.py` (`UserProfileService`) | Thread-safe user constraints and preferences compiled into Zone-4 JIT `<user_profile>` injections | L2 Core |
| `nexus/services/handoff.py` & `session_profile.py` | 4-state session isolation and structured cross-session handoff continuity | L2 Core |
| `nexus/services/context/shadow_archive.py` | Per-session lossless SQLite FTS5 archive linked to compressed turns and `rewind_to` support | L2 Core |
| `nexus/branches/plugins/memory_plugin.py` | Tool & lifecycle hook orchestrator (`vault_*`, `shadow_recall`, `vault_wiki`, `memory_dream`, `before_turn`/`after_turn`/`session_cleared`) | L4 Plugin |
| `nexus/branches/server/handlers/memory.py` | Framework-agnostic HTTP handlers (`/api/memory/wiki`, `/api/memory/dream`) | L4 HTTP |
| `mcp_memory_vault/` | Standalone JSON-RPC 2.0 `stdio` MCP server implementing physical dual-vault persistence, RRF/FAIR-DRI/MMR reranking, SSOT Markdown projection, sanitizer, and watchdog daemon | MCP Service |

## Directory Layout

```text
nexus-memory-architecture/
├── nexus/
│   ├── infra/              # Minimal path & JSONL logging utilities
│   ├── contract/           # Plugin DI & event contract primitives
│   ├── services/           # Vault, RetrievalGate, Wiki, Dreaming, NegativeExtractor, UserProfile, Handoff, ShadowArchive
│   └── branches/           # MemoryPlugin and /api/memory/* HTTP handlers
├── mcp_memory_vault/       # Standalone Dual-Vault MCP server, engines, scripts & tests
└── tests/harness/          # Extracted & standalone tests for the Nexus memory subsystem
```

## Quickstart & Verification

No external Python runtime dependencies are required (standard library only; `pytest` for tests):

```bash
pip install -e .[dev]
pytest -q
```

To launch the standalone Memory-Vault MCP `stdio` server:

```bash
python mcp_memory_vault/server.py
```

## License

MIT