🧠 NeuroWeave Cortex

A Hippocampal-Inspired Cognitive Memory Engine for AI Agents

Not a vector database. Not a graph database. Not RAG.
Not even an "LLM-powered memory system".
A self-organizing cognitive memory — memory is structured by use, not by prompt.
No memory is ever deleted. Only accessibility changes.
LLM reads memory. LLM does not decide what memory says.

---

✨ Core Design Principle

Memory structure is decided by the memory system, not by the LLM.

The LLM can read memory. The LLM can maintain memory (summarize, merge, archive).
But the LLM does not determine retrieval paths, edge weights, or relevance scores.

Brightness = f(historical access frequency, recency, edge strength)
NOT f(LLM-generated vector at query time)

This is the difference between a memory system that learns and one that re-computes every time.

---

🔬 What Makes It Different

Vector databases retrieve. Graph databases traverse. RAG systems query.
NeuroWeave Cortex learns from use:

Capability	Vector DB	Graph DB	RAG	NWC
Semantic retrieval	✅	❌	✅	✅
Graph traversal	❌	✅	❌	✅
Activation-based retrieval	❌	❌	❌	✅
Edge decay (no deletion)	❌	❌	❌	✅
Memory never deleted	❌	❌	❌	✅
Memory lifecycle (L1→L2→L3)	❌	❌	❌	✅
LLM-free retrieval routing	✅	✅	❌	✅
LLM for maintenance only	❌	❌	❌	✅
Sleep consolidation	❌	❌	❌	✅
Source attribution & trust	❌	❌	❌	✅

---

🧠 How Retrieval Actually Works

The Wrong Way (what most systems do):

Query → LLM generates embedding → LLM decides what's relevant → Return

Problem: LLM is the router. Every retrieval is a new LLM computation. Nothing stabilizes.

The NWC Way (v1.4.0):

Query → Embedding → Find seed nodes → Activation spread → Return

The LLM never touches the retrieval path. Retrieval is driven by:

1. Historical activation — how often has each memory been accessed?
2. Edge strength — how strongly are memories connected (reinforced by co-use)?
3. Temporal decay — edges weaken naturally over days of disuse (but NEVER to zero)
4. Recency boost — recently accessed memories activate more readily

🗝️ Core Design Principle: No Memory Is Ever Deleted

Traditional memory systems:  Store → Retrieve → Delete (when full)
NWC memory system:          Create → Activate → Dim → Dormant → Reactivate ♾️

Memories do NOT have a "delete" state. They transition between activation levels:

• 1.0 — currently active (just recalled)
• 0.7 — frequent access
• 0.3 — infrequent but known
• 0.1 — dormant (not accessed in a long time)
• 0.01 — deep dormant (years old)

Even a memory with activation_level = 0.01 is retrievable — if activation propagation from a connected query reaches it. This mimics human memory: you may not think about your elementary school classmates for decades, but a single photo can bring everything flooding back.

---

🏗️ Memory Layers (L0–L3)

NWC organizes memory into four cognitively-grounded layers:

L0: Input    ─── Ephemeral, per-session only (minutes)
    ↓ promote on repeated access (>3 times) or age (>30 days)
L1: Working  ─── Recent active memories (hours-days)
    │               LLM maintains: add, merge, summarize
    │               System routes: retrieval is LLM-free
    ↓ consolidate
L2: Long-term ─── Stable facts, experiences, relationships (months-years)
    │               ONLY operations: strengthen, supplement, weaken
    │               NEVER: full reconstruction
    ↓ archive on 90d no-access or low importance
L3: Dormant  ─── Low-activation memories retrievable via propagation (years)
    │               NEVER deleted. Only activation_level approaches 0.
    ↑ reactivate on query similarity or activation propagation

This is not a flat table. Memories physically transition between layers based on access patterns — just like human memory.

---

🚀 Quick Start

pip install NWcortex

from star_graph import MemoryManager, AgentContext

mgr = MemoryManager()

# Remember
mgr.remember("User prefers type hints and concise code", tags=["preference"])
mgr.remember("Debugged Redis timeout — pool 10 → 20", tags=["redis","debug"])

# Recall (LLM-free activation spreading)
ctx = AgentContext(task_type="debugging")
memories = mgr.recall("Redis connection pool config", context=ctx)

# Sleep: consolidate, migrate layers, decay weak edges
report = mgr.sleep()

# Persist
mgr.save("agent_memory.db")

---

⚡ LoCoMo-10 Benchmark

10 conversations · 5,882 turns · 1,986 QA pairs · Zero LLM calls

Method	has_answer	Δ vs Vector
Pure Vector Search	25.3%	—
Cosine + BM25	31.5%	+6.2 pp
NWC (BM40+txt60)	44.1%	+18.8 pp

---

📦 Installation

Command	Includes
pip install NWcortex	Core engine (138 modules)
pip install "NWcortex[embeddings]"	+ sentence-transformers
pip install "NWcortex[mcp]"	+ MCP Server
pip install "NWcortex[all]"	Everything

---

🧪 Running Tests

pip install pytest pytest-cov
pytest tests/ -v

---

⚖️ License

MIT

---

Report a bug · Discussion · Roadmap