hebbmem 0.1.0__py3-none-any.whl

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/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/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]

hebbmem/memory.py

@@ -0,0 +1,142 @@
+"""HebbMem — public API for bio-inspired memory."""
+
+from __future__ import annotations
+
+import uuid
+from typing import Any
+
+from hebbmem.encoders import (
+    EncoderBackend,
+    HashEncoder,
+    SentenceTransformerEncoder,
+    auto_select_encoder,
+)
+from hebbmem.graph import MemoryGraph
+from hebbmem.node import MemoryNode
+from hebbmem.types import Config, RecallResult
+
+
+class HebbMem:
+    """Bio-inspired memory for AI agents.
+
+    Uses decay, Hebbian learning, and spreading activation
+    to model how human memory works.
+    """
+
+    # TODO v0.2: save(path) / HebbMem.load(path) — persistence
+    # TODO v0.2: store_batch(contents) — batch ingestion
+    # TODO v0.2: threading.RLock — thread safety
+
+    def __init__(
+        self,
+        encoder: str | EncoderBackend = "auto",
+        config: Config | None = None,
+    ) -> None:
+        self.config = config or Config()
+        self._encoder = self._resolve_encoder(encoder)
+        self._graph = MemoryGraph(self.config)
+        self._time_step: int = 0
+
+    @staticmethod
+    def _resolve_encoder(encoder: str | EncoderBackend) -> EncoderBackend:
+        if isinstance(encoder, EncoderBackend):
+            return encoder
+        if encoder == "auto":
+            return auto_select_encoder()
+        if encoder == "hash":
+            return HashEncoder()
+        if encoder == "sentence-transformer":
+            return SentenceTransformerEncoder()
+        raise ValueError(f"Unknown encoder: {encoder}")
+
+    def store(
+        self,
+        content: str,
+        importance: float = 0.5,
+        metadata: dict[str, Any] | None = None,
+    ) -> uuid.UUID:
+        """Encode and store content. Returns memory_id."""
+        embedding = self._encoder.encode(content)
+        node = MemoryNode(
+            content=content,
+            embedding=embedding,
+            importance=importance,
+            metadata=metadata or {},
+        )
+        self._graph.add_node(node)
+        return node.memory_id
+
+    def recall(self, query: str, top_k: int = 5) -> list[RecallResult]:
+        """Full recall pipeline: encode → similarity → spread → hebbian → rank."""
+        query_embedding = self._encoder.encode(query)
+
+        # Find seed candidates (fetch extra to allow spreading to surface more)
+        candidates = self._graph.cosine_similarity(query_embedding, top_k=top_k * 2)
+        if not candidates:
+            return []
+
+        # Activate seeds proportional to similarity
+        seeds = [(nid, sim) for nid, sim in candidates if sim > 0]
+
+        # Spread activation through graph
+        activated_ids = self._graph.spread_activation(seeds)
+
+        # Hebbian update on co-activated nodes
+        self._graph.hebbian_update(activated_ids)
+
+        # Rank by weighted score
+        weights = self.config.scoring_weights
+        sim_map = dict(candidates)
+        results: list[RecallResult] = []
+
+        for nid in activated_ids:
+            node = self._graph.get_node(nid)
+            if node is None:
+                continue
+            node.touch()
+            sim = sim_map.get(nid, 0.0)
+            values = {
+                "activation": node.activation,
+                "similarity": sim,
+                "strength": node.base_strength,
+                "importance": node.importance,
+            }
+            score = sum(weights[k] * values[k] for k in weights)
+            results.append(
+                RecallResult(
+                    memory_id=node.memory_id,
+                    content=node.content,
+                    score=score,
+                    activation=node.activation,
+                    similarity=sim,
+                    strength=node.base_strength,
+                    importance=node.importance,
+                    metadata=node.metadata,
+                )
+            )
+
+        results.sort(key=lambda r: r.score, reverse=True)
+        return results[:top_k]
+
+    def step(self, n: int = 1) -> None:
+        """Advance time by n steps, applying decay each step."""
+        for _ in range(n):
+            self._time_step += 1
+            self._graph.decay_all()
+
+    def forget(self, memory_id: uuid.UUID) -> bool:
+        """Explicitly remove a memory. Returns True if found and removed."""
+        node = self._graph.get_node(memory_id)
+        if node is None:
+            return False
+        self._graph.remove_node(memory_id)
+        return True
+
+    def stats(self) -> dict[str, Any]:
+        """Return introspection statistics."""
+        return {
+            "node_count": self._graph.node_count,
+            "edge_count": self._graph.edge_count,
+            "time_step": self._time_step,
+            "encoder": type(self._encoder).__name__,
+        }

hebbmem/node.py

@@ -0,0 +1,41 @@
+"""MemoryNode — a single unit of memory in the graph."""
+
+from __future__ import annotations
+
+import time
+import uuid
+from dataclasses import dataclass, field
+from typing import Any
+
+import numpy as np
+
+
+@dataclass
+class MemoryNode:
+    """A single memory node with content, embedding, and activation dynamics."""
+
+    content: str
+    embedding: np.ndarray
+    importance: float = 0.5
+    metadata: dict[str, Any] = field(default_factory=dict)
+    memory_id: uuid.UUID = field(default_factory=uuid.uuid4)
+    activation: float = 0.0
+    base_strength: float = 1.0
+    decay_rate: float = 1.0  # per-node multiplier (1.0 = use global defaults)
+    created_at: float = field(default_factory=time.time)
+    last_accessed: float = field(default_factory=time.time)
+    access_count: int = 0
+
+    def activate(self, amount: float) -> None:
+        """Add activation energy, clamped to [0, 1]."""
+        self.activation = min(1.0, self.activation + amount)
+
+    def decay(self, activation_rate: float, strength_rate: float) -> None:
+        """Apply one step of temporal decay to activation and strength."""
+        self.activation *= activation_rate * self.decay_rate
+        self.base_strength *= strength_rate
+
+    def touch(self) -> None:
+        """Record an access (updates last_accessed, increments count)."""
+        self.last_accessed = time.time()
+        self.access_count += 1

hebbmem/types.py

@@ -0,0 +1,49 @@
+"""Shared data structures for hebbmem."""
+
+from __future__ import annotations
+
+import uuid
+from dataclasses import dataclass, field
+from typing import Any
+
+
+@dataclass
+class Edge:
+    """A weighted connection (synapse) between two memory nodes."""
+
+    weight: float = 0.1
+    co_activations: int = 0
+
+
+@dataclass
+class Config:
+    """Configuration for the hebbmem memory system."""
+
+    activation_decay: float = 0.95
+    strength_decay: float = 0.999
+    edge_decay: float = 0.99
+    hebbian_lr: float = 0.1
+    spread_factor: float = 0.5
+    max_hops: int = 3
+    auto_connect_threshold: float = 0.5
+    activation_threshold: float = 0.1
+    scoring_weights: dict[str, float] = field(default_factory=lambda: {
+        "activation": 0.4,
+        "similarity": 0.35,
+        "strength": 0.15,
+        "importance": 0.1,
+    })
+
+
+@dataclass
+class RecallResult:
+    """A single result from a recall query, with full score breakdown."""
+
+    memory_id: uuid.UUID
+    content: str
+    score: float
+    activation: float
+    similarity: float
+    strength: float
+    importance: float
+    metadata: dict[str, Any] = field(default_factory=dict)

hebbmem-0.1.0.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,10 @@
+hebbmem/__init__.py,sha256=TSfOcTnaoOvdG7xq_tM_C_Nt7urSDfGCs8vtQt0lggU,584
+hebbmem/encoders.py,sha256=mhT3ifWIqUpMJPkn_TiWWyKoqQmhYeByVNtUZMbkxMI,2768
+hebbmem/graph.py,sha256=Tt9InYdcpsVert8uB4Q1YMZtBdqsEzraR8euHHsxPNQ,6686
+hebbmem/memory.py,sha256=QuzDrB6FOjbrPI_O1fyOLHJLW9irZlBBQu_m80Tm94Y,4692
+hebbmem/node.py,sha256=yLX3-ThW9dT9A4cS4CgxzeTF--yoKeHXQsehFmi75hg,1386
+hebbmem/types.py,sha256=AgDJ4ZuA7SI6FRH35Qm1MkGXy1X07CNIRtFJnP0UDj0,1140
+hebbmem-0.1.0.dist-info/METADATA,sha256=1X024ZD42Tkw0s6bVpmoXZaaqVk92aphXEsuEWjFbOU,2592
+hebbmem-0.1.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+hebbmem-0.1.0.dist-info/licenses/LICENSE,sha256=U3h9vQu24D-tEPiBuuIh-a8BQV1xKzV-D5j1st3qFLc,1065
+hebbmem-0.1.0.dist-info/RECORD,,

hebbmem-0.1.0.dist-info/WHEEL

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

hebbmem-0.1.0.dist-info/licenses/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.