NWcortex 1.0.1__tar.gz

nwcortex-1.0.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Thatgfsj
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

nwcortex-1.0.1/MANIFEST.in

@@ -0,0 +1,10 @@
+include README.md
+include LICENSE
+include star_graph/defaults.yaml
+recursive-include examples *.py
+prune venv
+prune dist
+prune build
+prune .git
+prune __pycache__
+global-exclude *.pyc

nwcortex-1.0.1/NWcortex.egg-info/PKG-INFO

@@ -0,0 +1,317 @@
+Metadata-Version: 2.4
+Name: NWcortex
+Version: 1.0.1
+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"
+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 |
+| 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")
+```
+
+## 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,   │  "How do memories connect, strengthen, and fade?"
+     ghost.py,       │
+     abstraction.py, │
+     community.py,   │
+     competition.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` | 8-phase sleep: N1_Replay → N2_Merge → N3_Compression → N3b_AtomFacts → REM_Emotion → N4_Prune → N5_HubConnect → N6_IndexRebuild |
+| `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 reciprocal rank fusion for hybrid search |
+| `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) |
+| `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 (~2GB model download on first use)
+pip install "NWcortex[embeddings]"
+
+# Optional: for SQLite storage backend
+pip install aiosqlite
+
+# 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.
+
+## 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
+```
+
+## 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, 80% coverage (v1.0.0).
+
+## Roadmap
+
+See [ROADMAP.md](ROADMAP.md) for planned work.
+
+## License
+
+MIT

nwcortex-1.0.1/NWcortex.egg-info/SOURCES.txt

@@ -0,0 +1,196 @@
+LICENSE
+MANIFEST.in
+README.md
+pyproject.toml
+NWcortex.egg-info/PKG-INFO
+NWcortex.egg-info/SOURCES.txt
+NWcortex.egg-info/dependency_links.txt
+NWcortex.egg-info/entry_points.txt
+NWcortex.egg-info/requires.txt
+NWcortex.egg-info/top_level.txt
+examples/ablation_benchmark.py
+examples/emergence_demo.py
+examples/locomo_eval.py
+examples/locomo_llm_eval.py
+examples/locomo_test.py
+examples/memory_basic.py
+examples/memory_benchmark.py
+star_graph/__init__.py
+star_graph/__main__.py
+star_graph/abstraction.py
+star_graph/anchor.py
+star_graph/async_manager.py
+star_graph/atom_facts.py
+star_graph/autobiography.py
+star_graph/benchmark.py
+star_graph/bm25.py
+star_graph/brain_sphere.py
+star_graph/cascade.py
+star_graph/causal_edges.py
+star_graph/cli.py
+star_graph/cluster_memory.py
+star_graph/cognitive_cache.py
+star_graph/community.py
+star_graph/competition.py
+star_graph/compiler.py
+star_graph/compression.py
+star_graph/config.py
+star_graph/cortex.py
+star_graph/cost_estimator.py
+star_graph/defaults.yaml
+star_graph/domain_router.py
+star_graph/dual_channel.py
+star_graph/edge_budget.py
+star_graph/edge_decay.py
+star_graph/edge_management.py
+star_graph/embedding.py
+star_graph/episodic_memory.py
+star_graph/evolution.py
+star_graph/exact_cache.py
+star_graph/four_layer.py
+star_graph/gate.py
+star_graph/ghost.py
+star_graph/goal_tree.py
+star_graph/graph.py
+star_graph/hippocampus.py
+star_graph/hub.py
+star_graph/index.py
+star_graph/layers.py
+star_graph/logger.py
+star_graph/manager.py
+star_graph/manager_stats.py
+star_graph/math_utils.py
+star_graph/mcp_server.py
+star_graph/metrics.py
+star_graph/micro_sleep.py
+star_graph/multimodal.py
+star_graph/online.py
+star_graph/personality.py
+star_graph/raw_buffer.py
+star_graph/reflection_loop.py
+star_graph/resonance.py
+star_graph/retrieval_budget.py
+star_graph/retrieval_core.py
+star_graph/retrieval_pipeline.py
+star_graph/retriever.py
+star_graph/router.py
+star_graph/runtime.py
+star_graph/runtime_core.py
+star_graph/runtime_lifecycle.py
+star_graph/runtime_stats.py
+star_graph/scheduler.py
+star_graph/seed.py
+star_graph/self_org.py
+star_graph/server.py
+star_graph/shard.py
+star_graph/sleep.py
+star_graph/sleep_consolidate.py
+star_graph/sleep_nrem.py
+star_graph/sleep_rem.py
+star_graph/sleep_report.py
+star_graph/snapshot.py
+star_graph/spreading.py
+star_graph/sqlite_storage.py
+star_graph/storage.py
+star_graph/storage_backend.py
+star_graph/streaming.py
+star_graph/survival.py
+star_graph/symbolic_filter.py
+star_graph/thermal_store.py
+star_graph/tier.py
+star_graph/tiered.py
+star_graph/timespine.py
+star_graph/topology.py
+star_graph/tracing.py
+star_graph/versioned_memory.py
+star_graph/working_memory.py
+star_graph/write_gate.py
+star_graph/consolidation/__init__.py
+star_graph/contrib/__init__.py
+star_graph/contrib/benchmark.py
+star_graph/contrib/mcp_server.py
+star_graph/contrib/snapshot.py
+star_graph/contrib/streaming.py
+star_graph/contrib/symbolic_filter.py
+star_graph/cortex_api/__init__.py
+star_graph/embedding_provider/__init__.py
+star_graph/embedding_provider/providers.py
+star_graph/extras/__init__.py
+star_graph/extras/autobiography.py
+star_graph/extras/resonance.py
+star_graph/memory_core/__init__.py
+star_graph/retrieval_engine/__init__.py
+tests/test_abstraction.py
+tests/test_abstractive_memory.py
+tests/test_anchor.py
+tests/test_atom_facts.py
+tests/test_autobiography.py
+tests/test_bm25.py
+tests/test_brain_sphere.py
+tests/test_cascade.py
+tests/test_causal_edges.py
+tests/test_cluster_memory.py
+tests/test_cognitive_cache.py
+tests/test_cognitive_compiler.py
+tests/test_community.py
+tests/test_competition.py
+tests/test_compiler.py
+tests/test_compression.py
+tests/test_config_schema.py
+tests/test_cortex_hierarchy.py
+tests/test_cost_estimator.py
+tests/test_domain_router.py
+tests/test_edge_budget.py
+tests/test_edge_decay.py
+tests/test_edge_management.py
+tests/test_embedding.py
+tests/test_episodic_memory.py
+tests/test_evolution.py
+tests/test_four_layer.py
+tests/test_gate.py
+tests/test_ghost.py
+tests/test_ghost_intensity.py
+tests/test_goal_tree.py
+tests/test_graph.py
+tests/test_hippocampus.py
+tests/test_index.py
+tests/test_layers.py
+tests/test_logger.py
+tests/test_manager_stats.py
+tests/test_math_utils.py
+tests/test_memory_tier.py
+tests/test_metrics.py
+tests/test_micro_sleep.py
+tests/test_multimodal.py
+tests/test_online.py
+tests/test_oscillation_match.py
+tests/test_personality.py
+tests/test_raw_buffer.py
+tests/test_readme_doctest.py
+tests/test_reflection_loop.py
+tests/test_resonance.py
+tests/test_retrieval_budget.py
+tests/test_retrieval_trace.py
+tests/test_retriever.py
+tests/test_router.py
+tests/test_scheduler.py
+tests/test_seed.py
+tests/test_self_org.py
+tests/test_shard.py
+tests/test_sleep_consolidation.py
+tests/test_sleep_report.py
+tests/test_spreading.py
+tests/test_sqlite_storage.py
+tests/test_storage.py
+tests/test_storage_backend.py
+tests/test_streaming.py
+tests/test_survival.py
+tests/test_thermal_store.py
+tests/test_tier.py
+tests/test_timespine.py
+tests/test_topology.py
+tests/test_tracing.py
+tests/test_v08_modules.py
+tests/test_versioned_memory.py
+tests/test_working_memory.py
+tests/test_write_gate.py

nwcortex-1.0.1/NWcortex.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

nwcortex-1.0.1/NWcortex.egg-info/entry_points.txt

@@ -0,0 +1,5 @@
+[console_scripts]
+sg-add = star_graph.cli:add
+sg-query = star_graph.cli:query
+sg-sleep = star_graph.cli:sleep_cmd
+sg-stats = star_graph.cli:stats_cmd

nwcortex-1.0.1/NWcortex.egg-info/requires.txt

@@ -0,0 +1,6 @@
+numpy>=1.24.0
+PyYAML>=6.0
+scikit-learn>=1.3.0
+
+[embeddings]
+sentence-transformers>=2.2.0

nwcortex-1.0.1/NWcortex.egg-info/top_level.txt

@@ -0,0 +1 @@
+star_graph