nexus-agent-memory 0.1.0__py3-none-any.whl

nexus/__init__.py

@@ -0,0 +1 @@
+"""Nexus Memory System - compatibility package"""

nexus/belief.py

@@ -0,0 +1 @@
+from src.nexus_belief import *

nexus/cli.py

@@ -0,0 +1 @@
+from src.nexus_cli import *

nexus/constitution.py

@@ -0,0 +1 @@
+from src.nexus_constitution import *

nexus/core.py

@@ -0,0 +1 @@
+from src.nexus_core import *

nexus/drive.py

@@ -0,0 +1 @@
+from src.nexus_drive import *

nexus/embedder.py

@@ -0,0 +1 @@
+from src.nexus_embedder import *

nexus/episodes.py

@@ -0,0 +1,4 @@
+
+class EpisodeStore:
+    def __init__(self, *args, **kwargs):
+        raise NotImplementedError("EpisodeStore not yet implemented in standalone package")

nexus/evolve.py

@@ -0,0 +1 @@
+from src.nexus_evolve import *

nexus/extract.py

@@ -0,0 +1 @@
+from src.nexus_extract import *

nexus/facts.py

@@ -0,0 +1,8 @@
+
+class FactExtractor:
+    def __init__(self, *args, **kwargs):
+        raise NotImplementedError("FactExtractor not yet implemented in standalone package")
+
+class FactStore:
+    def __init__(self, *args, **kwargs):
+        raise NotImplementedError("FactStore not yet implemented in standalone package")

nexus/graph.py

@@ -0,0 +1 @@
+from src.nexus_graph import *

nexus/hnsw.py

@@ -0,0 +1 @@
+from src.nexus_hnsw import *

nexus/local.py

@@ -0,0 +1 @@
+from src.nexus_local import *

nexus/miner.py

@@ -0,0 +1 @@
+from src.nexus_miner import *

nexus/resolve.py

@@ -0,0 +1,4 @@
+
+class EntityResolver:
+    def __init__(self, *args, **kwargs):
+        raise NotImplementedError("EntityResolver not yet implemented in standalone package")

nexus/search.py

@@ -0,0 +1 @@
+from src.nexus_search import *

nexus/utils.py

@@ -0,0 +1 @@
+from src.nexus_utils import *

nexus_agent_memory-0.1.0.dist-info/METADATA

@@ -0,0 +1,353 @@
+Metadata-Version: 2.4
+Name: nexus-agent-memory
+Version: 0.1.0
+Summary: Cross-session persistent memory for AI Agents. 4500x faster retrieval, zero LLM dependency.
+Home-page: https://github.com/chuf-China/nexus-memory
+Author: chuf
+Author-email: chuf <64515713+chuf-China@users.noreply.github.com>
+License: MIT
+Project-URL: Homepage, https://github.com/chuf-China/nexus-memory
+Project-URL: Repository, https://github.com/chuf-China/nexus-memory
+Project-URL: Issues, https://github.com/chuf-China/nexus-memory/issues
+Keywords: ai-agent,memory,persistent-memory,llm,knowledge-graph,sqlite,mcp,vector-search
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Database
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.21.0
+Dynamic: author
+Dynamic: home-page
+Dynamic: license-file
+Dynamic: requires-python
+
+<div align="center">
+
+# 🧠 Nexus Memory
+
+### Cross-Session Persistent Memory for AI Agents
+
+**Your agent remembers everything. Across sessions. Across restarts. Forever.**
+
+[![CI](https://github.com/chuf-China/nexus-memory/actions/workflows/python-package.yml/badge.svg)](https://github.com/chuf-China/nexus-memory/actions/workflows/python-package.yml)
+[![PyPI](https://img.shields.io/pypi/v/nexus-memory?color=CB3837&label=PyPI&logo=pypi)](https://pypi.org/project/nexus-memory/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Python 3.9+](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/downloads/)
+
+<br/>
+
+![Search Latency](https://img.shields.io/badge/Search_Latency-20ms-brightgreen?style=for-the-badge)
+![Speedup](https://img.shields.io/badge/Speedup-4500x-FF6B35?style=for-the-badge)
+![Threat Patterns](https://img.shields.io/badge/Threat_Patterns-30+-red?style=for-the-badge)
+![LLM Dependency](https://img.shields.io/badge/LLM_Dependency-Zero-brightgreen?style=for-the-badge)
+
+[Install](#install) · [Quick Start](#quick-start) · [vs Competitors](#vs-competitors) · [Architecture](#architecture) · [API](#api) · [中文](README_CN.md)
+
+</div>
+
+---
+
+## The Problem
+
+Every AI coding agent starts from zero. You explain your project, your preferences, your stack — again and again. Context windows fill up. Token costs explode. The agent never learns.
+
+## The Solution
+
+Nexus Memory gives your agent a persistent brain. It remembers facts, preferences, corrections, and context across sessions — with **zero LLM calls**, **20ms retrieval**, and **automatic knowledge promotion**.
+
+```python
+from src.nexus_core import NexusCore
+
+nexus = NexusCore("nexus.db")
+
+# One line to remember
+nexus.write("User prefers Python type hints", source="conversation", confidence=0.9)
+
+# One line to recall
+results = nexus.search("What coding style does the user prefer?", limit=5)
+
+# One line to inject into any agent
+system_prompt = f"You are helpful.\n{nexus.system_prompt_block()}"
+```
+
+## Install
+
+```bash
+pip install nexus-memory
+```
+
+Or from source:
+
+```bash
+git clone https://github.com/chuf-China/nexus-memory.git
+cd nexus-memory
+pip install -e .
+```
+
+## Quick Start
+
+### Standalone (any agent)
+
+```python
+from src.nexus_core import NexusCore
+
+nexus = NexusCore("agent_memory.db")
+
+class YourAgent:
+    def __init__(self):
+        self.memory = NexusCore("agent_memory.db")
+
+    def chat(self, user_input):
+        # Retrieve relevant memories (20ms)
+        context = self.memory.search(user_input, limit=3)
+        # Build prompt with memory
+        prompt = f"Memories: {context}\nUser: {user_input}"
+        response = self.llm.generate(prompt)
+        # Auto-save conversation
+        self.memory.write(f"Q: {user_input}\nA: {response}", source="conversation")
+        return response
+```
+
+### Lifecycle Hooks
+
+```python
+nexus.register_hook("pre_llm_call", lambda ctx: ctx.update({
+    "alerts": nexus.get_alerts(),
+    "temporal": nexus.search_temporal(ctx["query"]),
+    "history": nexus.get_history(ctx["session_id"])
+}))
+
+nexus.register_hook("session_end", lambda ctx: {
+    nexus.consolidate(ctx["session_id"]),
+    nexus.knowledge_snapshot()
+})
+```
+
+### CLI
+
+```bash
+nexus-memory status          # Show DB stats
+nexus-memory search "query"  # Search knowledge
+nexus-memory export          # Export to JSON
+nexus-memory benchmark       # Run performance test
+```
+
+---
+
+## vs Competitors
+
+| Feature | Nexus Memory | [agentmemory](https://github.com/rohitg00/agentmemory) | [mem0](https://github.com/mem0ai/mem0) |
+|---------|:---:|:---:|:---:|
+| **Search Latency** | **20ms** | Unknown | ~100ms |
+| **LLM Dependency** | **Zero** | Uses iii engine | Requires LLM |
+| **Knowledge Layers** | **3-tier auto** | Claimed | Flat |
+| **Correction Handling** | **SPO conflict + belief degradation** | Unknown | Basic overwrite |
+| **Threat Detection** | **30+ patterns** | None | None |
+| **Graph Relations** | **Yes (NetworkX)** | Unknown | No |
+| **Vector Search** | **HNSW + fastembed** | Yes | Yes |
+| **Full-Text Search** | **FTS5** | Yes | Yes |
+| **Auto Extraction** | **Dual-channel (regex + LLM)** | Hooks only | LLM only |
+| **Memory Aging** | **48h decay + auto-archive** | Unknown | None |
+| **Scope Control** | **3-tier security** | None | None |
+| **External DB Required** | **No** | No | Yes (Qdrant/Redis) |
+| **Language** | **Python** | JavaScript | Python |
+| **License** | **MIT** | Unknown | Apache 2.0 |
+
+### Why Nexus Wins on Memory Quality
+
+**Agentmemory** is a great product with broad agent support (20+ integrations). But it treats memory as a black box inside the iii engine. You can't see how knowledge is stored, promoted, or corrected.
+
+**Nexus Memory** is transparent and precise:
+
+- **SPO Triplets**: Facts stored as Subject-Predicate-Object with confidence scores, not flat text
+- **Belief Network**: Knowledge auto-promotes from Observation → Belief → Fact based on evidence
+- **Correction Intelligence**: When you say "that's wrong", the old fact degrades AND the new fact promotes — a natural淘汰 system, not a permanent correction list that pollutes context
+- **Write-time Merging**: 5 strategies (exact_dup, fuzzy_dup, complement, contradict, new) prevent knowledge bloat
+
+---
+
+## Architecture
+
+```
+┌─────────────────────────────────────────────────────┐
+│                   Agent / LLM                       │
+│              (Claude Code, Cursor, etc.)             │
+└──────────────┬──────────────────────┬───────────────┘
+               │ search()             │ write()
+               ▼                      ▼
+┌─────────────────────────────────────────────────────┐
+│               Nexus Core Engine                     │
+│  ┌──────────┐ ┌──────────┐ ┌──────────┐           │
+│  │ Extract  │ │  Search  │ │  Belief  │           │
+│  │ (dual-   │ │ (4-way   │ │ (3-tier  │           │
+│  │  channel)│ │  fusion) │ │  promo)  │           │
+│  └────┬─────┘ └────┬─────┘ └────┬─────┘           │
+│       │            │            │                   │
+│  ┌────▼────────────▼────────────▼────┐             │
+│  │        SQLite + FTS5 + WAL        │             │
+│  │   HNSW Vectors │ NetworkX Graph   │             │
+│  └───────────────────────────────────┘             │
+│                                                     │
+│  ┌──────────┐ ┌──────────┐ ┌──────────┐           │
+│  │Constitu- │ │  Evolve  │ │  Miner   │           │
+│  │tion (30+ │ │ (auto-   │ │ (know-   │           │
+│  │ threats) │ │  aging)  │ │  ledge)  │           │
+│  └──────────┘ └──────────┘ └──────────┘           │
+└─────────────────────────────────────────────────────┘
+```
+
+### 3-Layer Knowledge Architecture
+
+| Layer | Confidence | Behavior |
+|-------|-----------|----------|
+| **Observation** | 0.30 - 0.50 | Raw signal, first appearance |
+| **Belief** | 0.70 - 0.85 | Multiple confirmations, emerging pattern |
+| **Fact** | 0.85 + | High confidence, persistent knowledge |
+
+- Auto-promote: Same pattern ≥3 times OR user confirmation
+- Auto-degrade: 48h unused → -0.05, corrected → -0.30
+- Auto-archive: confidence < 0.30 → archived
+
+### 6-Domain Scoring
+
+Every knowledge entry is scored on:
+**Freshness** · **Importance** · **Frequency** · **Relevance** · **Confidence** · **Feedback**
+
+### 4-Way Search Fusion
+
+1. **FTS5 Full-Text** (20ms) — SQLite native full-text index
+2. **Vector Search** (50ms) — HNSW approximate nearest neighbor with fastembed
+3. **Graph Query** (10ms) — NetworkX adjacency traversal
+4. **Cross-Encoder Reranking** — Final relevance scoring
+
+---
+
+## Performance Benchmarks
+
+| Operation | Latency | Notes |
+|-----------|---------|-------|
+| FTS5 Search | 20ms | SQLite full-text index |
+| Vector Search | 50ms | HNSW approximate nearest neighbor |
+| Graph Query | 10ms | Adjacency list traversal |
+| Write Knowledge | 5ms | WAL mode batch write |
+| Consolidation | 100ms | Merge + dedup + score update |
+
+**4500x faster** than LLM-based memory retrieval. Zero external service dependencies.
+
+---
+
+## Security Defense
+
+30+ built-in threat patterns:
+
+- **Injection**: Prompt injection, role hijacking, system prompt leakage
+- **Exfiltration**: Encoding bypass, covert channels, C2 communication
+- **Anti-forensics**: Log tampering, timestamp forgery, evidence destruction
+
+3-tier scope control:
+- `all` — Scan all knowledge
+- `context` — Scan only context-related knowledge
+- `strict` — Strict mode, highest security level
+
+---
+
+## Directory Structure
+
+```
+nexus-memory/
+├── src/
+│   ├── nexus_core.py          # Core engine (2448 lines)
+│   ├── nexus_drive.py         # Data persistence layer
+│   ├── nexus_extract.py       # Knowledge extractor (dual-channel)
+│   ├── nexus_search.py        # Hybrid search engine (4-way fusion)
+│   ├── nexus_embedder.py      # Vector embedding (fastembed)
+│   ├── nexus_hnsw.py          # HNSW index
+│   ├── nexus_graph.py         # Graph relationship (NetworkX)
+│   ├── nexus_belief.py        # Belief network (3-tier promotion)
+│   ├── nexus_constitution.py  # Security defense (30+ patterns)
+│   ├── nexus_evolve.py        # Self-evolution (aging + consolidation)
+│   ├── nexus_miner.py         # Knowledge mining
+│   ├── nexus_cli.py           # CLI tool
+│   ├── nexus_local.py         # Local storage
+│   └── nexus_utils.py         # Utility functions
+├── tests/
+│   ├── test_nexus_core.py     # Core tests
+│   └── test_nexus_benchmark.py # Performance benchmarks
+├── docs/
+│   └── architecture.md        # Architecture documentation
+├── pyproject.toml             # PyPI packaging
+├── setup.py                   # Installation config
+└── README.md                  # This file
+```
+
+## Dependencies
+
+- Python 3.9+
+- SQLite 3.38+ (FTS5 support)
+- numpy (vector computation)
+- **No external service dependencies** — pure local execution
+
+## API
+
+```python
+from src.nexus_core import NexusCore
+
+nexus = NexusCore("nexus.db")
+
+# Write
+nexus.write(content, source="conversation", confidence=0.9, domain="workflow")
+
+# Search
+results = nexus.search(query, limit=5, domain_filter=None)
+
+# System prompt injection
+block = nexus.system_prompt_block()
+
+# Consolidate session
+nexus.consolidate(session_id)
+
+# Knowledge snapshot
+nexus.knowledge_snapshot()
+
+# Register lifecycle hooks
+nexus.register_hook(event_name, callback)
+
+# Get alerts
+alerts = nexus.get_alerts()
+
+# Temporal search
+results = nexus.search_temporal(query)
+
+# Session history
+history = nexus.get_history(session_id)
+```
+
+## Run Tests
+
+```bash
+python -m pytest tests/ -v
+```
+
+## License
+
+MIT License
+
+## Acknowledgments
+
+Built as the memory backbone of [Hermes Agent](https://github.com/NousResearch/hermes-agent). Inspired by Karpathy's LLM Wiki pattern — extended with confidence scoring, lifecycle management, knowledge graphs, and hybrid search.
+
+---
+
+<div align="center">
+
+**If Nexus Memory helps your agent, give it a ⭐**
+
+</div>

nexus_agent_memory-0.1.0.dist-info/RECORD

@@ -0,0 +1,39 @@
+nexus/__init__.py,sha256=fHcmm57DptKgi7U2EMJp6zmZ0WoYc4Y-JzgSPrAenwo,50
+nexus/belief.py,sha256=M6YEjW6aSJEzE2IgPHB05aw3ZJlgaSyaWcVH9lWq8c0,31
+nexus/cli.py,sha256=HyikL4p_3mfAwBQbeRJzJZjCNr13Picg0fggl9OvPoQ,28
+nexus/constitution.py,sha256=E7HdW40c1VBmiwD_Zu4I1E4nKgUACh5ZVyXRD5K6efs,37
+nexus/core.py,sha256=NeYc5JL2I5ZT7m-RsZWO5qHrdjRbPerMRoYcHS5XRD4,29
+nexus/drive.py,sha256=XNFm--i1Yf_G0pTzBC8B2SaxzgBFPSCJg2MGPD2zKpY,30
+nexus/embedder.py,sha256=ku2awG26RA7VCvxD35uppO-VcLHyR274LJXqhytDQgA,33
+nexus/episodes.py,sha256=705LE6kIusxERCr_f_yAQ1EWAw4xkblHOVR08ODbAP4,154
+nexus/evolve.py,sha256=lMhvAcUDL3gob5Tq1bY4uJz57Cx92YPaQo2UfdHwzCo,31
+nexus/extract.py,sha256=daeb3gByszZ8HMX5TmCeHFl8W7GrTmzId7125Tcdp3E,32
+nexus/facts.py,sha256=w-u6yZYZG_cCs4Al0PJ1CNSVtaIKaLZAjWeA6Y4zRFE,304
+nexus/graph.py,sha256=YBbqjiYjSYq2G-Xb9eMIK490t9PSIGnBbF5U3Vh2pzs,30
+nexus/hnsw.py,sha256=-OuoWy-r5s5xOYqRLkSxb09MzurRYaR7ZKX4SO8fMjg,29
+nexus/local.py,sha256=tAjPG0Ey9Z2YDEQvtNNrqA_MKgnsH4AJtj-WFsZDUtk,30
+nexus/miner.py,sha256=j6BuVorIVmbJj39VFK_ko7HHf80Z_ET2KJK7xg1MMy0,30
+nexus/resolve.py,sha256=rfLPBy5T0Wh6Vnh3ya2mc6sHrF6nK1KfdWCCZGYlUys,158
+nexus/search.py,sha256=L3oMN-jOjoCb1sa1kogciTiGN6-xD-e59TrFLVh3YMA,31
+nexus/utils.py,sha256=0Yra5F-lTV7lyv0WxjgHToDa5uRK3nyLDVNhJPpApHI,30
+nexus_agent_memory-0.1.0.dist-info/licenses/LICENSE,sha256=mJ5DHmOWK6Lq7OJ1462ZcyESgqDg-YEdGlWXgIk4xuI,1067
+src/__init__.py,sha256=H1MaEKG2F4kHdGEo84pv_ISx7anvYgUe7Ab932D7PCk,285
+src/nexus_belief.py,sha256=EeDpyo_JT_k7nfkUTftBWjSrCjcdXnHrfOhuwQiKBwg,22492
+src/nexus_cli.py,sha256=vAXAzhi1U7ETy-W63dah17XakXvvShCxcLD4wJvWZuM,12475
+src/nexus_constitution.py,sha256=Nj9SeskbzYcrAWShCK_Ltla_e9IF5oFHee002QqypJ0,13834
+src/nexus_core.py,sha256=THw3uQ8L4YB9FMh6hOzdGV_xq3w9GyWySauqZ5_1mwE,106862
+src/nexus_drive.py,sha256=iBsxWZIdx27NYEaIyzhgiVXSYud66-IRbDY6L3GhOKU,7140
+src/nexus_embedder.py,sha256=K_pINcZxgYH1n8WChbfg0mYSG2wnDHIL2q52BwZZ7nY,13793
+src/nexus_evolve.py,sha256=FwCHrSSmpTa5fF6i8d0OKml-SiY9HS1LExGpVVGGFOc,18399
+src/nexus_extract.py,sha256=ocNPGZWh0JGGYLz5cpO5Q0z39FizAEyvMOdhJCLfWww,8951
+src/nexus_graph.py,sha256=fjJ5wPCHufpTEhIEB95Ka63RtfLftSAYrPtVz1pTGQU,16167
+src/nexus_hnsw.py,sha256=WF3HU3wNX16Ba7sKPG3PnoMZS0a4R_-NuaeM5fwDam4,8585
+src/nexus_local.py,sha256=AukmgRCAZ-1hwh_eIwjco6IG_czhcP9A_QLU4PwarG4,10225
+src/nexus_miner.py,sha256=7qRKv4NlNg3SIlNn63TRlEZ99A_KOu5hrLe2lX8xTmM,16186
+src/nexus_search.py,sha256=WW3gEkhkYeKA7XapXTsUSFoLa6F8yBG2g9mN1A_TKKs,15803
+src/nexus_utils.py,sha256=5xHoVavK_h0E5GugCn2y419uGkYBFe2aQ357FDwLjrE,3906
+nexus_agent_memory-0.1.0.dist-info/METADATA,sha256=8FZeY-SlIEQFyzKxKtl6DxKSucOY7c0rmIovEe06Oak,13429
+nexus_agent_memory-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+nexus_agent_memory-0.1.0.dist-info/entry_points.txt,sha256=EAcYDf50G0LjEoszM-2MGZJX-MjSeQ8llBpfNS0SC4E,52
+nexus_agent_memory-0.1.0.dist-info/top_level.txt,sha256=SXyG2-neQN3raYSF5pqXtKJOsbIfln0L2ZTf9ORSl-A,10
+nexus_agent_memory-0.1.0.dist-info/RECORD,,

nexus_agent_memory-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

nexus_agent_memory-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+nexus-memory = src.nexus_cli:main

nexus_agent_memory-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 chuf-China
+
+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.

nexus_agent_memory-0.1.0.dist-info/top_level.txt

@@ -0,0 +1,2 @@
+nexus
+src

src/__init__.py

@@ -0,0 +1,9 @@
+"""Nexus Memory System - Cross-session persistent memory for AI Agents"""
+
+from .nexus_core import NexusCore
+from .nexus_drive import NexusDrive
+from .nexus_search import EnhancedSearch
+
+__version__ = "1.0.0"
+__author__ = "chuf"
+__all__ = ["NexusCore", "NexusDrive", "EnhancedSearch"]