hebbmem 0.1.0__tar.gz

hebbmem-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,21 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: pip install -e ".[dev]"
+      - run: pytest tests/ -v --cov=hebbmem --cov-report=term-missing --cov-fail-under=88

hebbmem-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,34 @@
+# Publishes to PyPI when a version tag (v*) is pushed.
+#
+# Uses Trusted Publishing (OIDC) — no API token needed in secrets.
+# One-time setup required on PyPI:
+#   1. Go to https://pypi.org/manage/project/hebbmem/settings/publishing/
+#      (or create the project first via manual upload / `twine upload`)
+#   2. Add a new "GitHub Actions" publisher:
+#      - Owner: codepawl
+#      - Repository: hebbmem
+#      - Workflow: publish.yml
+#      - Environment: pypi
+
+name: Publish to PyPI
+
+on:
+  push:
+    tags: ["v*"]
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write
+    environment:
+      name: pypi
+      url: https://pypi.org/p/hebbmem
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install build
+      - run: python -m build
+      - uses: pypa/gh-action-pypi-publish@release/v1

hebbmem-0.1.0/.gitignore

@@ -0,0 +1,10 @@
+__pycache__/
+*.pyc
+*.pyo
+dist/
+build/
+*.egg-info/
+.coverage
+.pytest_cache/
+.venv/
+.claude/

hebbmem-0.1.0/LICENSE

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

hebbmem-0.1.0/PKG-INFO

@@ -0,0 +1,79 @@
+Metadata-Version: 2.4
+Name: hebbmem
+Version: 0.1.0
+Summary: Hebbian memory for AI agents — memories that fire together wire together.
+Project-URL: Homepage, https://github.com/codepawl/hebbmem
+Project-URL: Repository, https://github.com/codepawl/hebbmem
+Project-URL: Issues, https://github.com/codepawl/hebbmem/issues
+Author-email: An <an@codepawl.dev>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agent,ai,hebbian,memory,neuroscience
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.10
+Requires-Dist: numpy>=1.24
+Provides-Extra: dev
+Requires-Dist: pytest-cov>=4.0; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Provides-Extra: ml
+Requires-Dist: sentence-transformers>=2.2; extra == 'ml'
+Description-Content-Type: text/markdown
+
+# hebbmem
+
+Hebbian memory for AI agents — memories that fire together wire together.
+
+## Install
+
+```bash
+pip install hebbmem
+```
+
+For higher-quality embeddings (recommended):
+
+```bash
+pip install hebbmem[ml]
+```
+
+## Quick Start
+
+```python
+from hebbmem import HebbMem
+
+mem = HebbMem()
+
+# Store memories
+mem.store("Python is great for data science", importance=0.8)
+mem.store("JavaScript runs in the browser", importance=0.5)
+mem.store("Neural networks learn from data", importance=0.7)
+
+# Time passes, memories decay
+mem.step(5)
+
+# Recall activates related memories through the graph
+results = mem.recall("machine learning with Python", top_k=3)
+for r in results:
+    print(f"{r.content} (score={r.score:.3f})")
+```
+
+## How It Works
+
+hebbmem replaces flat vector storage with three neuroscience mechanisms:
+
+**Decay** — Memories fade over time unless reinforced, following the Ebbinghaus forgetting curve. Recent and frequently accessed memories stay strong.
+
+**Hebbian Learning** — Memories recalled together strengthen their connections. "Neurons that fire together wire together." Over time, the graph learns which memories are related through usage, not just embedding similarity.
+
+**Spreading Activation** — Recalling one memory activates related ones through the graph, surfacing connections that keyword or vector search alone would miss.
+
+## Links
+
+- [GitHub](https://github.com/codepawl/hebbmem)
+- [Codepawl](https://github.com/codepawl)

hebbmem-0.1.0/README.md

@@ -0,0 +1,51 @@
+# hebbmem
+
+Hebbian memory for AI agents — memories that fire together wire together.
+
+## Install
+
+```bash
+pip install hebbmem
+```
+
+For higher-quality embeddings (recommended):
+
+```bash
+pip install hebbmem[ml]
+```
+
+## Quick Start
+
+```python
+from hebbmem import HebbMem
+
+mem = HebbMem()
+
+# Store memories
+mem.store("Python is great for data science", importance=0.8)
+mem.store("JavaScript runs in the browser", importance=0.5)
+mem.store("Neural networks learn from data", importance=0.7)
+
+# Time passes, memories decay
+mem.step(5)
+
+# Recall activates related memories through the graph
+results = mem.recall("machine learning with Python", top_k=3)
+for r in results:
+    print(f"{r.content} (score={r.score:.3f})")
+```
+
+## How It Works
+
+hebbmem replaces flat vector storage with three neuroscience mechanisms:
+
+**Decay** — Memories fade over time unless reinforced, following the Ebbinghaus forgetting curve. Recent and frequently accessed memories stay strong.
+
+**Hebbian Learning** — Memories recalled together strengthen their connections. "Neurons that fire together wire together." Over time, the graph learns which memories are related through usage, not just embedding similarity.
+
+**Spreading Activation** — Recalling one memory activates related ones through the graph, surfacing connections that keyword or vector search alone would miss.
+
+## Links
+
+- [GitHub](https://github.com/codepawl/hebbmem)
+- [Codepawl](https://github.com/codepawl)

hebbmem-0.1.0/pyproject.toml

@@ -0,0 +1,45 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "hebbmem"
+version = "0.1.0"
+description = "Hebbian memory for AI agents — memories that fire together wire together."
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.10"
+authors = [{ name = "An", email = "an@codepawl.dev" }]
+keywords = ["ai", "agent", "memory", "hebbian", "neuroscience"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+]
+dependencies = ["numpy>=1.24"]
+
+[project.optional-dependencies]
+ml = ["sentence-transformers>=2.2"]
+dev = ["pytest>=7.0", "pytest-cov>=4.0"]
+
+[project.urls]
+Homepage = "https://github.com/codepawl/hebbmem"
+Repository = "https://github.com/codepawl/hebbmem"
+Issues = "https://github.com/codepawl/hebbmem/issues"
+
+[tool.hatch.build]
+exclude = [".claude/"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/hebbmem"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.coverage.run]
+source = ["hebbmem"]

hebbmem-0.1.0/src/hebbmem/__init__.py

@@ -0,0 +1,21 @@
+"""hebbmem - Bio-inspired memory for AI agents."""
+
+# TODO v0.2: py.typed — PEP 561 marker
+# TODO v0.2: hebbmem/integrations/ — framework adapters (LangChain, OpenPawl, OpenCode)
+
+from hebbmem.encoders import EncoderBackend, HashEncoder, SentenceTransformerEncoder
+from hebbmem.memory import HebbMem
+from hebbmem.node import MemoryNode
+from hebbmem.types import Config, Edge, RecallResult
+
+__version__ = "0.1.0"
+__all__ = [
+    "HebbMem",
+    "Config",
+    "Edge",
+    "RecallResult",
+    "MemoryNode",
+    "EncoderBackend",
+    "HashEncoder",
+    "SentenceTransformerEncoder",
+]

hebbmem-0.1.0/src/hebbmem/encoders.py

@@ -0,0 +1,89 @@
+"""Pluggable encoder backends for hebbmem."""
+
+from __future__ import annotations
+
+import hashlib
+from abc import ABC, abstractmethod
+
+import numpy as np
+
+
+class EncoderBackend(ABC):
+    """Base class for text-to-embedding encoders."""
+
+    @abstractmethod
+    def encode(self, text: str) -> np.ndarray:
+        """Encode text to a fixed-dimension float32 vector."""
+        ...
+
+    @abstractmethod
+    def encode_batch(self, texts: list[str]) -> np.ndarray:
+        """Encode multiple texts. Returns shape (n, dim)."""
+        ...
+
+    @property
+    @abstractmethod
+    def dimension(self) -> int:
+        ...
+
+
+class HashEncoder(EncoderBackend):
+    """Zero-dependency encoder using the hashing trick.
+
+    Deterministic: same input always produces same vector.
+    Uses multiple hash seeds to fill a fixed-dimension vector,
+    then L2-normalizes so cosine similarity works correctly.
+    """
+
+    def __init__(self, dimension: int = 256, num_hashes: int = 4) -> None:
+        self._dimension = dimension
+        self._num_hashes = num_hashes
+
+    @property
+    def dimension(self) -> int:
+        return self._dimension
+
+    def encode(self, text: str) -> np.ndarray:
+        vec = np.zeros(self._dimension, dtype=np.float32)
+        tokens = text.lower().split()
+        for token in tokens:
+            for seed in range(self._num_hashes):
+                h = int(hashlib.md5(f"{seed}:{token}".encode()).hexdigest(), 16)
+                idx = h % self._dimension
+                sign = 1.0 if (h // self._dimension) % 2 == 0 else -1.0
+                vec[idx] += sign
+        norm = np.linalg.norm(vec)
+        if norm > 0:
+            vec /= norm
+        return vec
+
+    def encode_batch(self, texts: list[str]) -> np.ndarray:
+        return np.stack([self.encode(t) for t in texts])
+
+
+class SentenceTransformerEncoder(EncoderBackend):
+    """Quality encoder using sentence-transformers (optional dependency)."""
+
+    def __init__(self, model_name: str = "all-MiniLM-L6-v2") -> None:
+        from sentence_transformers import SentenceTransformer
+
+        self._model = SentenceTransformer(model_name)
+        self._dimension: int = self._model.get_sentence_embedding_dimension()
+
+    @property
+    def dimension(self) -> int:
+        return self._dimension
+
+    def encode(self, text: str) -> np.ndarray:
+        return self._model.encode(text, convert_to_numpy=True).astype(np.float32)
+
+    def encode_batch(self, texts: list[str]) -> np.ndarray:
+        return self._model.encode(texts, convert_to_numpy=True).astype(np.float32)
+
+
+def auto_select_encoder() -> EncoderBackend:
+    """Return SentenceTransformerEncoder if available, else HashEncoder."""
+    try:
+        return SentenceTransformerEncoder()
+    except ImportError:
+        return HashEncoder()

hebbmem-0.1.0/src/hebbmem/graph.py

@@ -0,0 +1,182 @@
+"""MemoryGraph — weighted graph with spreading activation and Hebbian learning."""
+
+from __future__ import annotations
+
+import uuid
+from collections import deque
+
+import numpy as np
+
+from hebbmem.node import MemoryNode
+from hebbmem.types import Config, Edge
+
+
+class MemoryGraph:
+    """Graph of memory nodes connected by weighted edges (synapses).
+
+    Implements spreading activation, Hebbian reinforcement, and temporal decay.
+    """
+
+    def __init__(self, config: Config | None = None) -> None:
+        self.config = config or Config()
+        self._nodes: dict[uuid.UUID, MemoryNode] = {}
+        self._edges: dict[tuple[uuid.UUID, uuid.UUID], Edge] = {}
+        # Embedding cache for vectorized cosine similarity
+        self._embedding_matrix: np.ndarray | None = None
+        self._embedding_ids: list[uuid.UUID] = []
+        self._cache_dirty: bool = True
+
+    # --- Node operations ---
+
+    def add_node(self, node: MemoryNode) -> None:
+        """Add a node and auto-connect to similar existing nodes."""
+        self._nodes[node.memory_id] = node
+        self._cache_dirty = True
+        self._auto_connect(node)
+
+    def remove_node(self, memory_id: uuid.UUID) -> None:
+        """Remove a node and all its edges."""
+        self._nodes.pop(memory_id, None)
+        dead = [k for k in self._edges if memory_id in k]
+        for k in dead:
+            del self._edges[k]
+        self._cache_dirty = True
+
+    def get_node(self, memory_id: uuid.UUID) -> MemoryNode | None:
+        return self._nodes.get(memory_id)
+
+    @property
+    def node_count(self) -> int:
+        return len(self._nodes)
+
+    @property
+    def edge_count(self) -> int:
+        return len(self._edges) // 2  # undirected, stored both directions
+
+    # --- Embedding cache ---
+
+    def _rebuild_cache(self) -> None:
+        if not self._nodes:
+            self._embedding_matrix = None
+            self._embedding_ids = []
+            self._cache_dirty = False
+            return
+        self._embedding_ids = list(self._nodes.keys())
+        self._embedding_matrix = np.stack(
+            [self._nodes[nid].embedding for nid in self._embedding_ids]
+        )
+        norms = np.linalg.norm(self._embedding_matrix, axis=1, keepdims=True)
+        norms = np.maximum(norms, 1e-10)
+        self._embedding_matrix /= norms
+        self._cache_dirty = False
+
+    def cosine_similarity(
+        self, query_embedding: np.ndarray, top_k: int = 5
+    ) -> list[tuple[uuid.UUID, float]]:
+        """Vectorized cosine similarity against all nodes.
+
+        Returns list of (memory_id, similarity) sorted descending.
+        """
+        if self._cache_dirty:
+            self._rebuild_cache()
+        if self._embedding_matrix is None:
+            return []
+        query_norm = query_embedding / max(float(np.linalg.norm(query_embedding)), 1e-10)
+        scores = self._embedding_matrix @ query_norm
+        top_indices = np.argsort(scores)[::-1][:top_k]
+        return [(self._embedding_ids[i], float(scores[i])) for i in top_indices]
+
+    # --- Auto-connect ---
+
+    def _auto_connect(self, node: MemoryNode) -> None:
+        """Connect new node to existing nodes above similarity threshold."""
+        if self._cache_dirty:
+            self._rebuild_cache()
+        if self._embedding_matrix is None or len(self._embedding_ids) <= 1:
+            return
+        query_norm = node.embedding / max(float(np.linalg.norm(node.embedding)), 1e-10)
+        scores = self._embedding_matrix @ query_norm
+        threshold = self.config.auto_connect_threshold
+        for i, sim in enumerate(scores):
+            nid = self._embedding_ids[i]
+            if nid != node.memory_id and sim >= threshold:
+                self._set_edge(node.memory_id, nid, float(sim))
+
+    def _set_edge(self, a: uuid.UUID, b: uuid.UUID, weight: float) -> None:
+        """Set undirected edge weight."""
+        self._edges[(a, b)] = Edge(weight=weight)
+        self._edges[(b, a)] = Edge(weight=weight)
+
+    def get_neighbors(self, memory_id: uuid.UUID) -> list[tuple[uuid.UUID, float]]:
+        """Return [(neighbor_id, edge_weight), ...] for a node."""
+        result = []
+        for (src, dst), edge in self._edges.items():
+            if src == memory_id:
+                result.append((dst, edge.weight))
+        return result
+
+    # --- Spreading Activation (BFS) ---
+
+    def spread_activation(
+        self, seeds: list[tuple[uuid.UUID, float]]
+    ) -> list[uuid.UUID]:
+        """BFS spread from seed nodes. Returns all activated node IDs.
+
+        seeds: [(memory_id, initial_activation), ...]
+        """
+        activated: set[uuid.UUID] = set()
+        queue: deque[tuple[uuid.UUID, int]] = deque()
+        threshold = self.config.activation_threshold
+
+        for nid, act in seeds:
+            node = self._nodes.get(nid)
+            if node:
+                node.activate(act)
+                activated.add(nid)
+                queue.append((nid, 0))
+
+        while queue:
+            current_id, hop = queue.popleft()
+            if hop >= self.config.max_hops:
+                continue
+            current_node = self._nodes[current_id]
+            for neighbor_id, edge_weight in self.get_neighbors(current_id):
+                spread_amount = (
+                    current_node.activation * edge_weight * self.config.spread_factor
+                )
+                if spread_amount < threshold:
+                    continue
+                neighbor = self._nodes.get(neighbor_id)
+                if neighbor:
+                    neighbor.activate(spread_amount)
+                    if neighbor_id not in activated:
+                        activated.add(neighbor_id)
+                        queue.append((neighbor_id, hop + 1))
+
+        return list(activated)
+
+    # --- Hebbian Reinforcement ---
+
+    def hebbian_update(self, activated_ids: list[uuid.UUID]) -> None:
+        """Strengthen edges between co-activated nodes."""
+        lr = self.config.hebbian_lr
+        ids = set(activated_ids)
+        for (a, b), edge in self._edges.items():
+            if a in ids and b in ids:
+                edge.weight = min(1.0, edge.weight + lr * (1.0 - edge.weight))
+                edge.co_activations += 1
+
+    # --- Temporal Decay ---
+
+    def decay_all(self) -> None:
+        """Apply one time-step of decay to all nodes and edges."""
+        for node in self._nodes.values():
+            node.decay(self.config.activation_decay, self.config.strength_decay)
+
+        dead_edges = []
+        for key, edge in self._edges.items():
+            edge.weight *= self.config.edge_decay
+            if edge.weight < 0.01:
+                dead_edges.append(key)
+        for key in dead_edges:
+            del self._edges[key]