neural-memory 0.1.0__tar.gz

neural_memory-0.1.0/.gitignore

@@ -0,0 +1,161 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+.python-version
+
+# pipenv
+Pipfile.lock
+
+# poetry
+poetry.lock
+
+# pdm
+.pdm.toml
+.pdm-python
+.pdm-build/
+
+# PEP 582
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Project specific
+*.db
+*.sqlite
+data/
+logs/
+.neural_memory/
+.claude/
+
+# spaCy models
+en_core_web_sm/
+en_core_web_md/
+en_core_web_lg/

neural_memory-0.1.0/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.

neural_memory-0.1.0/PKG-INFO

@@ -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).