neural-memory 0.1.0__py3-none-any.whl

neural_memory-0.1.0.dist-info/METADATA

@@ -0,0 +1,314 @@
+Metadata-Version: 2.4
+Name: neural-memory
+Version: 0.1.0
+Summary: Reflex-based memory system for AI agents - retrieval through activation, not search
+Project-URL: Homepage, https://github.com/nhadaututtheky/neural-memory
+Project-URL: Documentation, https://github.com/nhadaututtheky/neural-memory#readme
+Project-URL: Repository, https://github.com/nhadaututtheky/neural-memory
+Project-URL: Issues, https://github.com/nhadaututtheky/neural-memory/issues
+Author: NeuralMemory Contributors
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agents,ai,graph,llm,memory,neural,retrieval
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+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: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: aiohttp>=3.9.0
+Requires-Dist: aiosqlite>=0.19.0
+Requires-Dist: networkx>=3.0
+Requires-Dist: pydantic>=2.0
+Requires-Dist: python-dateutil>=2.8
+Requires-Dist: rich>=13.0.0
+Requires-Dist: tomli>=2.0; python_version < '3.11'
+Requires-Dist: typer>=0.9.0
+Provides-Extra: all
+Requires-Dist: fastapi>=0.100; extra == 'all'
+Requires-Dist: neo4j>=5.0; extra == 'all'
+Requires-Dist: pyvi>=0.1; extra == 'all'
+Requires-Dist: spacy>=3.6; extra == 'all'
+Requires-Dist: underthesea>=6.0; extra == 'all'
+Requires-Dist: uvicorn[standard]>=0.23; extra == 'all'
+Provides-Extra: dev
+Requires-Dist: httpx>=0.24; extra == 'dev'
+Requires-Dist: mypy>=1.5; extra == 'dev'
+Requires-Dist: pre-commit>=3.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.21; extra == 'dev'
+Requires-Dist: pytest-cov>=4.0; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: ruff>=0.1.0; extra == 'dev'
+Provides-Extra: neo4j
+Requires-Dist: neo4j>=5.0; extra == 'neo4j'
+Provides-Extra: nlp
+Requires-Dist: pyvi>=0.1; extra == 'nlp'
+Requires-Dist: spacy>=3.6; extra == 'nlp'
+Requires-Dist: underthesea>=6.0; extra == 'nlp'
+Provides-Extra: nlp-en
+Requires-Dist: spacy>=3.6; extra == 'nlp-en'
+Provides-Extra: nlp-vi
+Requires-Dist: pyvi>=0.1; extra == 'nlp-vi'
+Requires-Dist: underthesea>=6.0; extra == 'nlp-vi'
+Provides-Extra: server
+Requires-Dist: fastapi>=0.100; extra == 'server'
+Requires-Dist: uvicorn[standard]>=0.23; extra == 'server'
+Description-Content-Type: text/markdown
+
+# NeuralMemory
+
+[![CI](https://github.com/nhadaututtheky/neural-memory/workflows/CI/badge.svg)](https://github.com/nhadaututtheky/neural-memory/actions)
+[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](https://opensource.org/licenses/MIT)
+[![Code style: ruff](https://img.shields.io/badge/code%20style-ruff-000000.svg)](https://github.com/astral-sh/ruff)
+
+<!-- Badges to enable after setup:
+[![Coverage](https://codecov.io/gh/nhadaututtheky/neural-memory/branch/main/graph/badge.svg)](https://codecov.io/gh/nhadaututtheky/neural-memory)
+[![PyPI](https://img.shields.io/pypi/v/neural-memory.svg)](https://pypi.org/project/neural-memory/)
+-->
+
+**Reflex-based memory system for AI agents** - retrieval through activation, not search.
+
+NeuralMemory stores experiences as interconnected neurons and recalls them through spreading activation, mimicking how the human brain works. Instead of searching a database, memories are retrieved through associative recall - activating related concepts until the relevant memory emerges.
+
+## Why Not RAG / Vector Search?
+
+| Aspect | RAG / Vector Search | NeuralMemory |
+|--------|---------------------|--------------|
+| **Model** | Search Engine | Human Brain |
+| **Query** | "Find similar text" | "Recall through association" |
+| **Structure** | Flat chunks + embeddings | Neural graph + synapses |
+| **Relationships** | None (just similarity) | Explicit: `CAUSED_BY`, `LEADS_TO`, `DISCUSSED` |
+| **Temporal** | Timestamp filter | Time as first-class neurons |
+| **Multi-hop** | Multiple queries needed | Natural graph traversal |
+| **Memory lifecycle** | Static | Decay, reinforcement, compression |
+
+**Example: "Why did Tuesday's outage happen?"**
+
+- **RAG**: Returns "JWT caused outage" (missing *why* we used JWT)
+- **NeuralMemory**: Traces `outage ← CAUSED_BY ← JWT ← SUGGESTED_BY ← Alice` → full causal chain
+
+See [full comparison](docs/GUIDE.md#neuralmemory-vs-rag--vector-search) in the docs.
+
+---
+
+## The Problem
+
+AI agents face fundamental memory limitations:
+
+| Problem | Impact |
+|---------|--------|
+| **Limited context windows** | Cannot complete large projects across sessions |
+| **Session amnesia** | Forget everything between conversations |
+| **No knowledge sharing** | Cannot share learned patterns with other agents |
+| **Context overflow** | Important early context gets lost |
+
+## The Solution
+
+| Feature | Benefit |
+|---------|---------|
+| **Persistent memory** | Survives across sessions |
+| **Efficient retrieval** | Inject only relevant context, not everything |
+| **Shareable brains** | Export/import patterns like Git repos |
+| **Real-time sharing** | Multi-agent collaboration |
+| **Project-bounded** | Optimize for active project timeframes |
+
+## Installation
+
+```bash
+pip install neural-memory
+```
+
+With optional features:
+```bash
+pip install neural-memory[server]   # FastAPI server
+pip install neural-memory[nlp-vi]   # Vietnamese NLP
+pip install neural-memory[all]      # All features
+```
+
+## Quick Start
+
+### CLI
+
+```bash
+# Store memories
+nmem remember "Fixed auth bug with null check in login.py:42"
+nmem remember "We decided to use PostgreSQL" --type decision
+nmem todo "Review PR #123" --priority 7
+
+# Query memories
+nmem recall "auth bug"
+nmem recall "database decision" --depth 2
+
+# Get context for AI injection
+nmem context --limit 10 --json
+
+# Manage brains
+nmem brain list
+nmem brain create work
+nmem brain use work
+
+# Real-time sharing
+nmem shared enable http://localhost:8000
+nmem remember "Team knowledge" --shared
+nmem recall "project status" --shared
+```
+
+### Python API
+
+```python
+import asyncio
+from neural_memory import Brain
+from neural_memory.storage import InMemoryStorage
+from neural_memory.engine.encoder import MemoryEncoder
+from neural_memory.engine.retrieval import ReflexPipeline
+
+async def main():
+    storage = InMemoryStorage()
+    brain = Brain.create("my_brain")
+    await storage.save_brain(brain)
+    storage.set_brain(brain.id)
+
+    # Encode memories
+    encoder = MemoryEncoder(storage, brain.config)
+    await encoder.encode("Met Alice to discuss API design")
+    await encoder.encode("Decided to use FastAPI for backend")
+
+    # Query through activation
+    pipeline = ReflexPipeline(storage, brain.config)
+    result = await pipeline.query("What did we decide about backend?")
+    print(result.context)  # "Decided to use FastAPI for backend"
+
+asyncio.run(main())
+```
+
+## Features
+
+### Memory Types
+```bash
+nmem remember "Objective fact" --type fact
+nmem remember "We chose X" --type decision
+nmem remember "User prefers Y" --type preference
+nmem todo "Action item" --type todo --expires 30
+nmem remember "Learned pattern" --type insight
+nmem remember "Meeting notes" --type context --expires 7
+```
+
+### Project Scoping
+```bash
+nmem project create "Q1 Sprint" --duration 14
+nmem remember "Sprint task" --project "Q1 Sprint"
+nmem recall "sprint progress" --project "Q1 Sprint"
+```
+
+### Real-Time Brain Sharing
+```bash
+# Enable shared mode
+nmem shared enable http://localhost:8000
+
+# Per-command sharing
+nmem remember "Team insight" --shared
+nmem recall "shared knowledge" --shared
+
+# Sync local with remote
+nmem shared sync --direction push
+```
+
+### Safety Features
+```bash
+# Check for sensitive content
+nmem check "API_KEY=sk-xxx"
+
+# Auto-redact before storing
+nmem remember "Config: API_KEY=sk-xxx" --redact
+
+# Safe export
+nmem brain export --exclude-sensitive -o safe.json
+
+# Health check
+nmem brain health
+```
+
+## Server Mode
+
+```bash
+pip install neural-memory[server]
+uvicorn neural_memory.server:app --reload
+```
+
+API endpoints:
+```
+POST /memory/encode     - Store memory
+POST /memory/query      - Query memories
+POST /brain/create      - Create brain
+GET  /brain/{id}/export - Export brain
+WS   /sync/ws           - Real-time sync
+```
+
+## Documentation
+
+- **[Complete Guide](docs/GUIDE.md)** - Full documentation with all features
+- **[Integration Guide](docs/integration.md)** - AI assistant & tool integration
+- **[Safety & Limitations](docs/safety.md)** - Security best practices
+- **[Architecture & Scalability](docs/architecture.md)** - Technical design & future roadmap
+
+## Development
+
+```bash
+git clone https://github.com/neural-memory/neural-memory
+cd neural-memory
+pip install -e ".[dev]"
+pre-commit install
+
+# Run tests
+pytest tests/ -v --cov=neural_memory
+
+# Type check
+mypy src/
+
+# Lint
+ruff check src/ tests/
+```
+
+## How It Works
+
+```
+Query: "What did Alice suggest?"
+         │
+         ▼
+┌─────────────────────┐
+│ 1. Decompose Query  │  → time hints, entities, intent
+└─────────────────────┘
+         │
+         ▼
+┌─────────────────────┐
+│ 2. Find Anchors     │  → "Alice" neuron
+└─────────────────────┘
+         │
+         ▼
+┌─────────────────────┐
+│ 3. Spread Activation│  → activate connected neurons
+└─────────────────────┘
+         │
+         ▼
+┌─────────────────────┐
+│ 4. Find Intersection│  → high-activation subgraph
+└─────────────────────┘
+         │
+         ▼
+┌─────────────────────┐
+│ 5. Extract Context  │  → "Alice suggested rate limiting"
+└─────────────────────┘
+```
+
+## Contributing
+
+Contributions welcome! See [CONTRIBUTING.md](CONTRIBUTING.md).
+
+## License
+
+MIT License - see [LICENSE](LICENSE).

neural_memory-0.1.0.dist-info/RECORD

@@ -0,0 +1,55 @@
+neural_memory/__init__.py,sha256=-PzpjmZU17qTgPuZJE6VgFijzpefAdr2HlRpP3wSTeM,970
+neural_memory/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+neural_memory/unified_config.py,sha256=BySYLNJmnBcz9A83kKztJ53ShkScJ5qOVqBNGQls0Rs,10208
+neural_memory/cli/__init__.py,sha256=4srWgYwiGcs-mG6dm91gRbYCN-om2hfkuxd-fYkgIGI,409
+neural_memory/cli/__main__.py,sha256=TnhrDVCqsaagmqua7QH1yaP9YXLNRvLxQ0pFrMxDYRw,132
+neural_memory/cli/config.py,sha256=3kuYeWyTJms_2H_xAgx0qXEN1FbaYwvcU0oKPdiGO2Y,5612
+neural_memory/cli/main.py,sha256=DsHZDnYXFaWRqJzOFo_IK0bMNEmTtDxDpeJSGCriTJU,92396
+neural_memory/cli/storage.py,sha256=xiIk9Nmygw2G-nBDuRaSh6ZY6Ccu3zX_1l_eyeOlIsM,6044
+neural_memory/cli/tui.py,sha256=3D0uhQD2LpP7caBOns7EeOsx-JsORl4-DyzSsS1HN64,16335
+neural_memory/core/__init__.py,sha256=j9oPfDRg6n3Jr1OwwjY1OufH1zEPcL5aZol23R8vik0,1181
+neural_memory/core/brain.py,sha256=VYrAClvHMDadn6ED5rtyXBf_cU-Z9rJYdKfaK7ZaLVI,9745
+neural_memory/core/brain_mode.py,sha256=DLfGkQeKcDBHedL553nYW8e0c-ZFkD4k1mZfD7sj0Is,8245
+neural_memory/core/fiber.py,sha256=98lyGgXG63iMqpTJks63nHj_J9lCqCcX0as_Tt6OJbo,7319
+neural_memory/core/memory_types.py,sha256=Rt8VH3vFTo8x-QXHAwsDm4B1USE9msq8uabYVdyM0MQ,11077
+neural_memory/core/neuron.py,sha256=xFGw9UWEHhcnReRug_8cRQ3x5B89Vx5G2BwDV3daFsY,5202
+neural_memory/core/project.py,sha256=H9Fws8dDB7NA__xWFw3U3hcxqRvdd8hLqfSuEMBFB28,8594
+neural_memory/core/synapse.py,sha256=esfb0kNKwyYw0Ps68ao7IfFxf9thyML24WJJoLgnQjM,6862
+neural_memory/engine/__init__.py,sha256=bBuk-gqynBG_ebwB1scGu52PE6LjZw5fNOpL9zTe4wE,472
+neural_memory/engine/activation.py,sha256=wTecU_j5FBe3LgXAvPNnR6Nji-fsLeLsANezIBW0KaI,11221
+neural_memory/engine/encoder.py,sha256=uk3NvThLntXszzlbR0nO2GiPFikJ4th4TKkZf4NueyY,12716
+neural_memory/engine/retrieval.py,sha256=0IjyDVDnUJCdZo6umgjYIBElVbTggV45zGxRzYoQryg,13809
+neural_memory/extraction/__init__.py,sha256=XTuBnuAv0uWXs6LOUEQMoPBsBxVih93EvBaY1Vb_OCk,854
+neural_memory/extraction/entities.py,sha256=62To2Z-DbPFidOLn2pjY6tN10LmAxk_7vDyhTtxinso,13430
+neural_memory/extraction/parser.py,sha256=Obvp2s1Zy4L3vzVekC4VZZKFRknsJDZb9kn-5MaUJ8o,9914
+neural_memory/extraction/router.py,sha256=PGN0Z5uwmtYhARajVhb-q01PDG2cuxMUp_xqwZWL77k,12296
+neural_memory/extraction/temporal.py,sha256=uESwr-NWTMNiRJHDryKBdSS3swnkp_FBwjUwiHAnIf0,15930
+neural_memory/mcp/__init__.py,sha256=8qo502ZfwryBv5htRaUJWsk3q9tbZX6TBtjmO6H0iTA,332
+neural_memory/mcp/__main__.py,sha256=BETnISNHCDaqFhvOo51fSV1DcB2yMu9iefu-b6mA0bk,137
+neural_memory/mcp/server.py,sha256=TwTIc60xCSDSdGOHSVEr7tPi-DUHAABdBHS74F1ADZw,23291
+neural_memory/safety/__init__.py,sha256=25_pdeXu-UI3dNsPYiCsC3Rvq26ma-tCd3h1ow7Ny3w,679
+neural_memory/safety/freshness.py,sha256=nwUdybjsDK_8uwa_mJRPflx0XGZXVwDwJCw-LEVyh9c,6748
+neural_memory/safety/sensitive.py,sha256=3dCv951D1JOMo6V4vu11d0OxUFhxCITZ2w05HhJ3CtA,9359
+neural_memory/server/__init__.py,sha256=-VB8CldyBAzD10NK0aFBKMhUkHwR4aJHn05g_4X8xYQ,114
+neural_memory/server/app.py,sha256=dEc1qKxTt6bGlzkiwlatVOZ_p48ukW4Dd14mClpD4vw,2649
+neural_memory/server/dependencies.py,sha256=gcUsxihGs7VrhZjmqzA4VwytTNkQE9IMswQnf5t-fnA,923
+neural_memory/server/models.py,sha256=HDrqIMamc2c4bf2yrsVgTGDQZcO27ASCjeVJAdOWpso,4259
+neural_memory/server/routes/__init__.py,sha256=dkZBeETlaGDW1uetueQWhCRgzfUGr64T_ELkDUWFi1c,310
+neural_memory/server/routes/brain.py,sha256=ej7N5jU8SKTC4jkX-uXEmSojONd3q0EJjgjJwEVKXXc,6389
+neural_memory/server/routes/memory.py,sha256=A-A8PF-aX7L8RhEN_zn0Gno09oI1IUnYadEZ7B5YcC8,5076
+neural_memory/server/routes/sync.py,sha256=5nvnuu8EakOQ-iNEBztSehvbwQDpdT5YwMP8zy3RBco,12747
+neural_memory/storage/__init__.py,sha256=jiVLlyvj_Yn-E24O_edNQmyYhNsUNmT8OMvvrvxll9c,542
+neural_memory/storage/base.py,sha256=LxoiYseiNP4zOpK__lYW7eGkUiNw7tuLDPX_vH_dZNY,10565
+neural_memory/storage/factory.py,sha256=kQYTDuPG3LTW8lPrzn556DDci3d8uEHfWUgn0uox3E4,10567
+neural_memory/storage/memory_store.py,sha256=cY5Gtw1_oDyOzDVuIQTPZ-q0javFb2t2gr1lFC_a_Vo,31669
+neural_memory/storage/shared_store.py,sha256=wI33TY40c-_7sCIRIn63mLzfSXHgvdhGUnrj4fMK2tg,23372
+neural_memory/storage/sqlite_store.py,sha256=TARL9mIvaeY_NwA1DJ8cy25f4C9ZEFa6PyC_xcZe80g,60327
+neural_memory/sync/__init__.py,sha256=epKpdAsHzwUYXrWawlHPckSEgK5CZYb-B29AAcdTnVk,162
+neural_memory/sync/client.py,sha256=kiKqRlteXVe9P-IzgayV7bwdT9Ovu2UgV_XJtEUIbxQ,13421
+neural_memory/utils/__init__.py,sha256=vZM_jKQ_BUUd6jXtz9BGq5A1d-kFRMcMXt96XVhRv2M,135
+neural_memory/utils/config.py,sha256=jgDaHksEibusC2gub1I_USUBOJyP6gBHcfgS7RkL4dc,3086
+neural_memory-0.1.0.dist-info/METADATA,sha256=VWQ5A-nyNmq28EGUP1AWf-kduWj5-4xyIA-6QXBp9K8,10305
+neural_memory-0.1.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+neural_memory-0.1.0.dist-info/entry_points.txt,sha256=u0ZGaAD6uU98g0Wheyj1WjrSchm_zlAkyzz1HRbKOnE,121
+neural_memory-0.1.0.dist-info/licenses/LICENSE,sha256=uuCGDPgkW8shclBRpQNK5I0T97ZQy9HHolwo9Qr3Bbc,1082
+neural_memory-0.1.0.dist-info/RECORD,,

neural_memory-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.28.0
+Root-Is-Purelib: true
+Tag: py3-none-any

neural_memory-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,4 @@
+[console_scripts]
+neural-memory = neural_memory.cli:main
+nmem = neural_memory.cli:main
+nmem-mcp = neural_memory.mcp:main

neural_memory-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 NeuralMemory Contributors
+
+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.