NWcortex 1.3.1

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.

🧠 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.
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 (true forgetting)	❌	❌	❌	✅
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 Right Way (NWC v1.3):

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
4. Recency boost — recently accessed memories activate more readily

---

🏗️ 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: Archive  ─── Compressed summaries, not in real-time retrieval
    ↑ reactivate on query similarity

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")

---

📦 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

---

📄 Citation

@software{neuroweave_cortex,
  title = {NeuroWeave Cortex: A Hippocampal-Inspired Cognitive Memory System},
  author = {Thatgfsj},
  year = {2026},
  url = {https://github.com/Thatgfsj/neuroweave-cortex}
}

---

⚖️ License

MIT

---

Report a bug · Discussion · Roadmap