mda-memory 0.1.1__tar.gz

mda_memory-0.1.1/LICENSE

@@ -0,0 +1,67 @@
+Server Side Public License
+VERSION 1, OCTOBER 16, 2018
+
+Copyright (C) 2026 Mert Polat <mert@kairfy.com>
+
+Everyone is permitted to copy and distribute verbatim copies of this
+license document, but changing it is not allowed.
+
+                            PREAMBLE
+
+The Server Side Public License (this document, or "SSPL") is based on the
+GNU General Public License, version 3 ("GPL"). The goal of SSPL is to
+ensure that companies that use and benefit from open source software
+provide meaningful access to the source code of the tools they use to
+provide their services.
+
+If you modify the Program, or if you make it available over a network, you
+must provide the source code of the entire program stack being used,
+including the service source code.
+
+                TERMS AND CONDITIONS
+
+0. Definitions.
+
+"This License" refers to version 1 of the Server Side Public License.
+
+"The Program" refers to any copyrightable work licensed under this License.
+
+"You" refers to the licensee.
+
+"Service" means making the functionality of the Program, or a modified
+version thereof, available to third parties as a service.
+
+1. Personal and Internal Use
+
+You may use, copy, modify, and distribute this software for personal or
+internal business purposes, free of charge, under the following conditions:
+
+  a) You do not make the software available as a service to third parties.
+  b) You retain all copyright and license notices.
+
+2. Service Use
+
+If you use this software or a modified version of it to provide a service
+to third parties, you must make the complete corresponding source code of
+the entire program stack — including all modules, services, and tooling
+required to deploy and run the service — available under this License.
+
+3. No Sublicensing
+
+You may not sublicense the software under any other license. All copies
+and derivative works must carry this License.
+
+4. No Warranty
+
+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.
+
+5. Contact
+
+For commercial licensing inquiries (cloud deployment, SaaS integration,
+or enterprise use), contact: mert@kairfy.com

mda_memory-0.1.1/PKG-INFO

@@ -0,0 +1,22 @@
+Metadata-Version: 2.4
+Name: mda-memory
+Version: 0.1.1
+Summary: Online associative memory for LLMs
+Requires-Python: >=3.10
+License-File: LICENSE
+Requires-Dist: numpy
+Requires-Dist: torch
+Requires-Dist: rich
+Requires-Dist: prompt_toolkit
+Requires-Dist: python-dotenv
+Requires-Dist: requests
+Requires-Dist: anthropic
+Requires-Dist: ollama
+Requires-Dist: chromadb
+Requires-Dist: sentence-transformers
+Requires-Dist: tqdm
+Requires-Dist: matplotlib
+Requires-Dist: ijson
+Requires-Dist: deep-translator
+Requires-Dist: langdetect
+Dynamic: license-file

mda_memory-0.1.1/README.md

@@ -0,0 +1,195 @@
+# MDA — Modular Dynamic Architecture
+
+**Online associative memory for LLMs. Learns during inference. No backpropagation. No GPU required.**
+
+[![License: SSPL](https://img.shields.io/badge/License-SSPL-blue.svg)](LICENSE)
+[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/)
+
+---
+
+## What is MDA?
+
+Large language models can reason but cannot remember. RAG partially addresses this — but it cannot update during a conversation, and it cannot learn from the conversation itself.
+
+MDA fills precisely these gaps.
+
+It encodes knowledge as **256-dimensional Holographic Distributed Representations (HDRs)**, connects concepts through a **sparse synapse graph**, and retrieves context by activating entity networks — not by text-chunk similarity search. New knowledge is integrated immediately, without rebuilding any index.
+
+**MDA is not a RAG replacement. It is the persistent learning layer that RAG and LLMs are missing.**
+
+---
+
+## Key Properties
+
+- **Token-free** — no tokenizer, no vocabulary
+- **Attention-free** — no transformer encoder required
+- **Online learning** — learns during inference via the Oja rule
+- **No catastrophic forgetting** — entities are independent; new knowledge never overwrites old
+- **CPU-only** — runs entirely on numpy, no GPU required
+- **Model-agnostic** — works with Ollama, OpenAI, Anthropic, or any LLM
+
+---
+
+## Benchmark Results
+
+Evaluated against a strong RAG baseline (bge-large-en-v1.5 + ChromaDB, top-6 retrieval) across 80 questions spanning 8 cognitive categories:
+
+| Category | RAG | MDA | Δ |
+|---|---|---|---|
+| ATOMIC_RECALL | 100% | 85% | −15% |
+| MULTI_HOP | 90% | 90% | 0% |
+| CROSS_DOCUMENT | 80% | 70% | −10% |
+| REASONING | 70% | 90% | **+20%** |
+| INCREMENTAL_LEARNING | 0% | 60% | **+60%** |
+| NOISE_RESISTANCE | 100% | 100% | 0% |
+| MEMORY_COMPRESSION | 90% | 70% | −20% |
+| BOUNDARY | 100% | 100% | 0% |
+| **OVERALL** | **78.8%** | **83.1%** | **+4.3%** |
+
+MDA uses **3.1× less context per query** than RAG while achieving higher overall accuracy.
+
+**Long-context retention (200 turns):** RAG 0% — MDA 92%.
+
+---
+
+## Quick Start
+
+```bash
+git clone https://github.com/Rangle2/mda
+cd mda
+pip install -r requirements.txt
+```
+
+> **Note:** `pip install mda-memory` coming in v0.2. Clone-based install is the supported method for now.
+
+### Basic Usage
+
+```python
+from mda import MDA
+
+memory = MDA()
+
+# Teach facts
+memory.learn("The capital of Veloria is Aranthos.")
+memory.learn("Aranthos was founded by Queen Seraphel in 412 AE.")
+
+# Retrieve context — returns memory string ready for LLM injection
+context = memory.context_for("Who founded the capital?")
+print(context)
+# → [MEMORY] Aranthos was founded by Queen Seraphel in 412 AE.
+```
+
+### With Ollama
+
+```bash
+# Start Ollama with any model
+ollama pull qwen3:4b
+
+# Run MDA CLI
+python -m integrations.cli --model qwen3:4b
+```
+
+### With Anthropic (Claude)
+
+```bash
+# Set your API key
+export ANTHROPIC_API_KEY=your_key_here
+
+# Run MDA CLI with Claude
+python -m integrations.cli --model claude-haiku-4-5-20251001 --provider anthropic
+```
+
+### Running Benchmarks
+
+```bash
+# Main benchmark — Ollama
+python benchmark/benchmark.py --model qwen3:4b
+
+# Main benchmark — Anthropic
+python benchmark/benchmark.py --model claude-haiku-4-5-20251001 --provider anthropic
+
+# Long-context retention benchmark — Ollama
+python benchmark/long_context_benchmark.py --model qwen3:4b
+
+# Long-context retention benchmark — Anthropic
+python benchmark/long_context_benchmark.py --model claude-haiku-4-5-20251001 --provider anthropic
+```
+
+---
+
+## Project Structure
+
+```
+mda/
+├── mda.py                 # Public API — MDA class
+├── core/
+│   ├── bind.py            # HDR ops: bind, unbind, normalize, cosine
+│   ├── encoder.py         # HolisticEncoder: text → 256-dim vector
+│   ├── entity.py          # Entity: v, r, h, W, neurons, synapses, senses
+│   ├── neuron.py          # Neuron (Oja rule), Synapse (Hebbian)
+│   └── registry.py        # EntityRegistry: surface → Entity lookup
+├── inference/
+│   ├── associative.py     # AssociativeChain: multi-hop traversal
+│   ├── broca.py           # BrocaModule: W-hybrid context scoring
+│   ├── reasoning.py       # ReasoningEngine: cross-entity inference
+│   └── memory.py          # ConversationMemory: multi-turn context
+├── training/
+│   └── checkpoint.py      # save/load: float32, atomic write
+├── integrations/
+│   ├── engine.py          # MDAEngine: LLM bridge (Ollama / Anthropic)
+│   └── cli.py             # Interactive CLI (Rich + prompt_toolkit)
+├── benchmark/
+│   ├── benchmark.py       # 80-question main benchmark
+│   └── long_context_benchmark.py  # 200-turn retention benchmark
+└── tests/                 # pytest test suite
+```
+
+---
+
+## How It Works
+
+### Entity & W Matrix
+Every concept is an `Entity` with a 256-dim identity vector `v` and a lazy-initialized Hebbian weight matrix `W`. `W` is `None` until the entity is first activated — memory overhead is proportional to usage.
+
+### Online Learning (Oja Rule)
+```
+ΔW = η(yxᵀ − y²W)
+```
+where `x` is the query vector and `y = Wx`. No backpropagation. No gradient descent. Runs in O(d²) per entity per turn.
+
+### AssociativeChain
+Query → origin entity → breadth-first synapse traversal (depth 3) → context assembly. Dynamic inhibition prevents context flooding.
+
+### BrocaModule
+Facts are scored with a W-hybrid formula:
+```
+score = 0.35·s_query + 0.45·s_W + 0.20·s_sense
+```
+Facts below 0.20 are suppressed.
+
+---
+
+## Running Tests
+
+```bash
+pytest tests/
+```
+
+---
+
+## Roadmap
+
+- [ ] **GPU acceleration** — PyTorch tensor ops, parallel entity traversal
+- [ ] **Low-rank W** — W ≈ A×B factorization for higher-dimensional HDRs
+- [ ] **`mda.cloud` API** — persistent memory as a service
+- [ ] **MDA + RAG hybrid** — offline corpus retrieval + online conversational learning
+- [ ] **Real-world corpus evaluation** — beyond fictional benchmark domains
+- [ ] **Independent benchmark** — community-constructed evaluation set
+
+---
+
+## License
+
+[SSPL 1.0](LICENSE) — free for research and personal use. Commercial use requires a separate agreement.
+
+For commercial licensing: mert@kairfy.com

mda_memory-0.1.1/mda/__init__.py

@@ -0,0 +1,3 @@
+from mda.mda import MDA
+
+__all__ = ["MDA"]

mda_memory-0.1.1/mda/core/bind.py

@@ -0,0 +1,39 @@
+import numpy as np
+
+DIM = 256
+
+
+def normalize(v: np.ndarray) -> np.ndarray:
+    n = np.linalg.norm(v)
+    return v / (n + 1e-8)
+
+
+def random_vector(dim: int = DIM, seed: int = None) -> np.ndarray:
+    rng = np.random.default_rng(seed)
+    return normalize(rng.normal(0, 1, dim))
+
+
+def zero_vector(dim: int = DIM) -> np.ndarray:
+    return np.zeros(dim)
+
+
+def bind(a: np.ndarray, b: np.ndarray) -> np.ndarray:
+    return np.real(np.fft.ifft(np.fft.fft(a) * np.fft.fft(b)))
+
+
+def unbind(compound: np.ndarray, b: np.ndarray) -> np.ndarray:
+    F_b     = np.fft.fft(b)
+    F_b_inv = np.conj(F_b) / (np.abs(F_b) ** 2 + 1e-6)
+    b_inv   = np.real(np.fft.ifft(F_b_inv))
+    return np.real(np.fft.ifft(np.fft.fft(compound) * np.fft.fft(b_inv)))
+
+
+def bind_many(*vectors: np.ndarray) -> np.ndarray:
+    result = vectors[0].copy()
+    for v in vectors[1:]:
+        result = bind(result, v)
+    return result
+
+
+def cosine(a: np.ndarray, b: np.ndarray) -> float:
+    return float(np.dot(a, b) / (np.linalg.norm(a) * np.linalg.norm(b) + 1e-8))