yourmemory 1.2.3__tar.gz → 1.3.0__tar.gz

{yourmemory-1.2.3/yourmemory.egg-info → yourmemory-1.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: yourmemory
-Version: 1.2.3
+Version: 1.3.0
 Summary: Persistent memory for Claude — Ebbinghaus forgetting curve, semantic deduplication, MCP-native
 Author-email: Sachit Misra <mishrasachit1@gmail.com>
 License:                                  Apache License
@@ -182,6 +182,7 @@ Requires-Dist: python-dateutil
 Requires-Dist: duckdb>=0.10.0
 Requires-Dist: apscheduler
 Requires-Dist: spacy<4.0,>=3.8.13
+Requires-Dist: networkx>=3.0
 Provides-Extra: postgres
 Requires-Dist: psycopg2-binary; extra == "postgres"
 Requires-Dist: pgvector; extra == "postgres"
@@ -189,8 +190,10 @@ Provides-Extra: sse
 Requires-Dist: fastapi; extra == "sse"
 Requires-Dist: uvicorn[standard]; extra == "sse"
 Requires-Dist: httpx; extra == "sse"
+Provides-Extra: neo4j
+Requires-Dist: neo4j>=5.0; extra == "neo4j"
 Provides-Extra: all
-Requires-Dist: yourmemory[postgres,sse]; extra == "all"
+Requires-Dist: yourmemory[neo4j,postgres,sse]; extra == "all"
 Dynamic: license-file
 
 # YourMemory

{yourmemory-1.2.3 → yourmemory-1.3.0}/memory_mcp.py

@@ -399,6 +399,23 @@ async def call_tool(name: str, arguments: dict) -> list[types.TextContent]:
             cur.close()
         conn.close()
 
+        # Index into graph (best-effort; never blocks the response)
+        if memory_id is not None:
+            try:
+                from src.graph.graph_store import index_memory as _graph_index
+                _graph_index(
+                    memory_id=memory_id,
+                    user_id=user_id,
+                    content=final_content,
+                    strength=importance,
+                    importance=importance,
+                    category=category,
+                    embedding=list(embedding),
+                )
+            except Exception as _ge:
+                import sys as _sys
+                print(f"[graph] index_memory failed: {_ge}", file=_sys.stderr)
+
         return [types.TextContent(type="text", text=json.dumps(
             {"stored": 1, "id": memory_id, "content": final_content, "category": category,
              "importance": importance, "agent_id": agent_id, "visibility": visibility,

{yourmemory-1.2.3 → yourmemory-1.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "yourmemory"
-version = "1.2.3"
+version = "1.3.0"
 description = "Persistent memory for Claude — Ebbinghaus forgetting curve, semantic deduplication, MCP-native"
 readme = "README.md"
 requires-python = ">=3.11"
@@ -29,12 +29,14 @@ dependencies = [
     "duckdb>=0.10.0",
     "apscheduler",
     "spacy>=3.8.13,<4.0",
+    "networkx>=3.0",
 ]
 
 [project.optional-dependencies]
 postgres = ["psycopg2-binary", "pgvector"]
 sse = ["fastapi", "uvicorn[standard]", "httpx"]
-all = ["yourmemory[postgres,sse]"]
+neo4j = ["neo4j>=5.0"]
+all = ["yourmemory[postgres,sse,neo4j]"]
 
 [project.scripts]
 yourmemory = "memory_mcp:run"

{yourmemory-1.2.3 → yourmemory-1.3.0}/src/db/migrate.py

@@ -39,6 +39,14 @@ def migrate():
     conn.close()
     print(f"Migration complete ({backend}).", file=sys.stderr)
 
+    # Bootstrap the graph backend (creates indexes for Neo4j, touches pickle for NetworkX)
+    try:
+        from src.graph import get_graph_backend
+        get_graph_backend()
+        print("Graph backend initialised.", file=sys.stderr)
+    except Exception as exc:
+        print(f"Graph backend init skipped: {exc}", file=sys.stderr)
+
 
 if __name__ == "__main__":
     migrate()

yourmemory-1.3.0/src/graph/__init__.py

@@ -0,0 +1,44 @@
+"""
+Graph backend factory.
+
+Usage:
+    from src.graph import get_graph_backend
+    graph = get_graph_backend()   # NetworkX by default
+
+Override via env var:
+    GRAPH_BACKEND=neo4j  →  Neo4jBackend
+    GRAPH_BACKEND=networkx (default)
+
+The returned instance is a module-level singleton — import graph_store
+instead of calling this directly in application code.
+"""
+
+import os
+from src.graph.backend import GraphBackend
+
+_instance: GraphBackend | None = None
+
+
+def get_graph_backend() -> GraphBackend:
+    """Return the module-level singleton graph backend."""
+    global _instance
+    if _instance is None:
+        backend = os.getenv("GRAPH_BACKEND", "networkx").lower()
+        if backend == "neo4j":
+            from src.graph.neo4j_backend import Neo4jBackend
+            _instance = Neo4jBackend()
+        else:
+            from src.graph.networkx_backend import NetworkXBackend
+            _instance = NetworkXBackend()
+    return _instance
+
+
+def reset_graph_backend() -> None:
+    """Force re-initialisation (used in tests)."""
+    global _instance
+    if _instance is not None:
+        try:
+            _instance.close()
+        except Exception:
+            pass
+    _instance = None

yourmemory-1.3.0/src/graph/backend.py

@@ -0,0 +1,58 @@
+"""
+Abstract GraphBackend interface.
+Implementations: NetworkXBackend (default), Neo4jBackend (opt-in via GRAPH_BACKEND=neo4j).
+"""
+
+from abc import ABC, abstractmethod
+from typing import Optional
+
+
+class GraphBackend(ABC):
+
+    @abstractmethod
+    def upsert_node(self, memory_id: int, user_id: str, strength: float,
+                    importance: float, category: str) -> None:
+        """Create or update a node for a memory."""
+
+    @abstractmethod
+    def upsert_edge(self, source_id: int, target_id: int,
+                    relation: str, weight: float) -> None:
+        """Create or strengthen a directed edge between two memory nodes."""
+
+    @abstractmethod
+    def get_neighbors(self, memory_id: int, user_id: str,
+                      max_depth: int = 2) -> list:
+        """
+        BFS from memory_id up to max_depth hops.
+        Returns list of {"memory_id": int, "distance": int, "edge_weight": float}.
+        Only traverses nodes belonging to user_id.
+        """
+
+    @abstractmethod
+    def boost_node_and_neighbors(self, memory_id: int, user_id: str,
+                                  boost: float = 0.2,
+                                  max_depth: int = 1) -> list:
+        """
+        Propagate a recall boost through depth-1 neighbors.
+        Returns list of memory_ids that were boosted (for vector DB recall_count bump).
+        """
+
+    @abstractmethod
+    def get_node_strength(self, memory_id: int) -> Optional[float]:
+        """Return the cached strength of a node, or None if not found."""
+
+    @abstractmethod
+    def update_node_strength(self, memory_id: int, strength: float) -> None:
+        """Refresh the cached strength after vector DB recomputes it."""
+
+    @abstractmethod
+    def get_all_nodes_for_user(self, user_id: str) -> list:
+        """Return all node dicts for chain-aware pruning."""
+
+    @abstractmethod
+    def delete_node(self, memory_id: int) -> None:
+        """Remove a node and all its edges from the graph."""
+
+    @abstractmethod
+    def close(self) -> None:
+        """Flush and release resources."""

yourmemory-1.3.0/src/graph/graph_store.py

@@ -0,0 +1,275 @@
+"""
+High-level graph façade used by the rest of the application.
+
+Four public functions:
+  index_memory(memory_id, user_id, content, strength, importance, category)
+      → extract SVO triples, upsert node, upsert edges
+
+  expand_with_graph(seed_ids, user_id, top_k) → list of extra memory_ids
+      → multi-hop BFS from each seed; deduplicated, sorted by edge_weight
+
+  propagate_recall(memory_id, user_id) → list of memory_ids that were boosted
+      → boost recall_proxy on depth-1 neighbours (for recall_count bump in DB)
+
+  chain_safe_to_prune(memory_id, user_id, threshold) → bool
+      → True only when ALL graph neighbours are also below the threshold
+
+All four are silent no-ops if the graph backend is unavailable.
+"""
+
+import sys
+from typing import Optional
+
+from src.graph.svo_extract import extract_triples
+
+# Lazy: don't crash the server if networkx is missing
+_graph = None
+
+
+def _g():
+    global _graph
+    if _graph is None:
+        try:
+            from src.graph import get_graph_backend
+            _graph = get_graph_backend()
+        except Exception as exc:
+            print(f"[graph_store] backend unavailable: {exc}", file=sys.stderr)
+    return _graph
+
+
+# ------------------------------------------------------------------ #
+# Index a stored memory (call after INSERT)
+# ------------------------------------------------------------------ #
+
+def index_memory(
+    memory_id:  int,
+    user_id:    str,
+    content:    str,
+    strength:   float,
+    importance: float,
+    category:   str,
+    embedding:  list | None = None,
+) -> None:
+    """
+    Register a memory node in the graph and create semantically-weighted edges.
+
+    Edge strategy:
+    - If `embedding` is provided (always the case from store_memory):
+        Query the DB for the top-5 most similar *existing* memories by cosine
+        similarity (above a 0.3 floor).  Edge weight = similarity × verb_weight
+        from the SVO triple (or 0.5 default if spaCy unavailable).
+        This means edges connect memories that are *actually related*, not just
+        stored around the same time.
+    - Fallback (no embedding): connect to 5 most recent nodes at weight 0.4.
+    """
+    g = _g()
+    if g is None:
+        return
+
+    try:
+        g.upsert_node(memory_id, user_id, strength, importance, category)
+    except Exception as exc:
+        print(f"[graph_store] upsert_node failed: {exc}", file=sys.stderr)
+        return
+
+    # ── Find semantically similar neighbours via the vector DB ──────────
+    if embedding is not None:
+        similar = _similar_nodes(memory_id, user_id, embedding, top_k=5, min_sim=0.4)
+    else:
+        similar = []  # fallback handled below
+
+    if not similar:
+        return  # no semantically related neighbours — isolated node is correct
+
+    # ── Get verb weight from SVO triple (if spaCy available) ────────────
+    triples = extract_triples(content)
+    # Use the highest-weight predicate found, or 0.5 default
+    verb_weight = max((t["weight"] for t in triples), default=0.5)
+    relation    = triples[0]["predicate"] if triples else "related"
+
+    # ── Create edges: weight = cosine_similarity × verb_weight ──────────
+    for nbr in similar:
+        target_id  = nbr["memory_id"]
+        sim        = nbr["similarity"]
+        edge_weight = round(sim * verb_weight, 4)
+        try:
+            g.upsert_edge(memory_id, target_id, relation, edge_weight)
+        except Exception as exc:
+            print(f"[graph_store] upsert_edge failed: {exc}", file=sys.stderr)
+
+
+def _similar_nodes(
+    memory_id: int,
+    user_id:   str,
+    embedding: list,
+    top_k:     int   = 5,
+    min_sim:   float = 0.3,
+) -> list:
+    """
+    Query the vector DB for the top-k most similar existing memories
+    (excluding memory_id itself).  Returns [{memory_id, similarity}].
+    """
+    try:
+        from src.db.connection import get_backend, get_conn
+        from src.db.connection import duckdb_rows
+        backend = get_backend()
+        conn    = get_conn()
+
+        if backend == "duckdb":
+            result = conn.execute("""
+                SELECT id,
+                       array_cosine_similarity(embedding, ?::FLOAT[768]) AS sim
+                FROM memories
+                WHERE user_id = ? AND id != ?
+                  AND array_cosine_similarity(embedding, ?::FLOAT[768]) >= ?
+                ORDER BY sim DESC
+                LIMIT ?
+            """, [embedding, user_id, memory_id, embedding, min_sim, top_k])
+            rows = duckdb_rows(result)
+            conn.close()
+            return [{"memory_id": r["id"], "similarity": r["sim"]} for r in rows]
+
+        elif backend == "postgres":
+            emb_str = f"[{','.join(str(x) for x in embedding)}]"
+            cur = conn.cursor()
+            cur.execute("""
+                SELECT id,
+                       1 - (embedding <=> %s::vector) AS sim
+                FROM memories
+                WHERE user_id = %s AND id != %s
+                  AND 1 - (embedding <=> %s::vector) >= %s
+                ORDER BY sim DESC
+                LIMIT %s
+            """, (emb_str, user_id, memory_id, emb_str, min_sim, top_k))
+            rows = cur.fetchall()
+            cur.close()
+            conn.close()
+            return [{"memory_id": r[0], "similarity": r[1]} for r in rows]
+
+        else:  # sqlite — compute cosine in Python
+            import json
+            import numpy as np
+            cur = conn.cursor()
+            cur.execute(
+                "SELECT id, embedding FROM memories WHERE user_id = ? AND id != ?",
+                (user_id, memory_id),
+            )
+            va = np.array(embedding, dtype=float)
+            results = []
+            for row in cur.fetchall():
+                if row[1] is None:
+                    continue
+                vb  = np.array(json.loads(row[1]), dtype=float)
+                den = np.linalg.norm(va) * np.linalg.norm(vb)
+                sim = float(np.dot(va, vb) / den) if den else 0.0
+                if sim >= min_sim:
+                    results.append({"memory_id": row[0], "similarity": sim})
+            results.sort(key=lambda x: x["similarity"], reverse=True)
+            cur.close()
+            conn.close()
+            return results[:top_k]
+
+    except Exception as exc:
+        print(f"[graph_store] _similar_nodes failed: {exc}", file=sys.stderr)
+        return []
+
+
+# ------------------------------------------------------------------ #
+# Expand vector search results with graph neighbours
+# ------------------------------------------------------------------ #
+
+def expand_with_graph(
+    seed_ids: list[int],
+    user_id:  str,
+    top_k:    int = 5,
+) -> list[int]:
+    """
+    BFS from each seed memory_id; return up to top_k extra ids not in seeds.
+
+    Returned list is sorted by cumulative edge_weight (strongest first).
+    """
+    g = _g()
+    if g is None or not seed_ids:
+        return []
+
+    seen_seeds = set(seed_ids)
+    candidates: dict[int, float] = {}  # memory_id → best edge_weight
+
+    for seed in seed_ids:
+        try:
+            neighbours = g.get_neighbors(seed, user_id, max_depth=2)
+        except Exception as exc:
+            print(f"[graph_store] get_neighbors failed: {exc}", file=sys.stderr)
+            continue
+        for nbr in neighbours:
+            nid = nbr["memory_id"]
+            if nid in seen_seeds:
+                continue
+            ew = nbr["edge_weight"]
+            if nid not in candidates or candidates[nid] < ew:
+                candidates[nid] = ew
+
+    ranked = sorted(candidates, key=lambda k: candidates[k], reverse=True)
+    return ranked[:top_k]
+
+
+# ------------------------------------------------------------------ #
+# Propagate recall boost through graph edges
+# ------------------------------------------------------------------ #
+
+def propagate_recall(memory_id: int, user_id: str) -> list[int]:
+    """
+    Boost recall_proxy on depth-1 neighbours after a memory is recalled.
+
+    Returns the list of boosted memory_ids so the caller can increment
+    recall_count in the vector DB.
+    """
+    g = _g()
+    if g is None:
+        return []
+    try:
+        return g.boost_node_and_neighbors(memory_id, user_id,
+                                          boost=0.2, max_depth=1)
+    except Exception as exc:
+        print(f"[graph_store] propagate_recall failed: {exc}", file=sys.stderr)
+        return []
+
+
+# ------------------------------------------------------------------ #
+# Chain-aware pruning gate
+# ------------------------------------------------------------------ #
+
+def chain_safe_to_prune(
+    memory_id: int,
+    user_id:   str,
+    threshold: float,
+) -> bool:
+    """
+    Return True if it is safe to prune this memory.
+
+    A memory is safe to prune only when ALL of its graph neighbours are
+    also below `threshold`.  If any neighbour is still strong, the memory
+    is kept alive (chain integrity).
+
+    Falls back to True (prune normally) if the graph backend is unavailable.
+    """
+    g = _g()
+    if g is None:
+        return True
+
+    try:
+        neighbours = g.get_neighbors(memory_id, user_id, max_depth=1)
+    except Exception as exc:
+        print(f"[graph_store] chain_safe_to_prune failed: {exc}", file=sys.stderr)
+        return True
+
+    if not neighbours:
+        return True  # isolated node — prune normally
+
+    for nbr in neighbours:
+        nid = nbr["memory_id"]
+        strength = g.get_node_strength(nid)
+        if strength is not None and strength >= threshold:
+            return False  # at least one strong neighbour → keep alive
+
+    return True

yourmemory-1.3.0/src/graph/neo4j_backend.py

@@ -0,0 +1,195 @@
+"""
+Neo4j graph backend — opt-in via GRAPH_BACKEND=neo4j.
+Requires: pip install yourmemory[neo4j]  (neo4j driver)
+
+Connection: set NEO4J_URI, NEO4J_USER, NEO4J_PASSWORD env vars.
+Defaults: bolt://localhost:7687 / neo4j / neo4j
+"""
+
+import os
+from typing import Optional
+
+from src.graph.backend import GraphBackend
+
+
+def _get_driver():
+    try:
+        from neo4j import GraphDatabase  # type: ignore
+    except ImportError:
+        raise ImportError(
+            "neo4j driver not installed. Run: pip install 'yourmemory[neo4j]'"
+        )
+    uri  = os.getenv("NEO4J_URI",      "bolt://localhost:7687")
+    user = os.getenv("NEO4J_USER",     "neo4j")
+    pw   = os.getenv("NEO4J_PASSWORD", "neo4j")
+    return GraphDatabase.driver(uri, auth=(user, pw))
+
+
+class Neo4jBackend(GraphBackend):
+    """
+    Graph backend that persists nodes/edges in Neo4j.
+
+    Schema:
+      (:Memory {memory_id, user_id, strength, importance, category, recall_proxy})
+      -[:RELATES {relation, weight}]->
+    """
+
+    def __init__(self):
+        self._driver = _get_driver()
+        self._ensure_indexes()
+
+    def _ensure_indexes(self):
+        with self._driver.session() as s:
+            s.run(
+                "CREATE INDEX memory_id_idx IF NOT EXISTS "
+                "FOR (m:Memory) ON (m.memory_id)"
+            )
+            s.run(
+                "CREATE INDEX memory_user_idx IF NOT EXISTS "
+                "FOR (m:Memory) ON (m.user_id)"
+            )
+
+    # ------------------------------------------------------------------ #
+    # Node operations
+    # ------------------------------------------------------------------ #
+
+    def upsert_node(self, memory_id: int, user_id: str, strength: float,
+                    importance: float, category: str) -> None:
+        with self._driver.session() as s:
+            s.run(
+                """
+                MERGE (m:Memory {memory_id: $mid})
+                SET m.user_id    = $uid,
+                    m.strength   = $strength,
+                    m.importance = $importance,
+                    m.category   = $category,
+                    m.recall_proxy = coalesce(m.recall_proxy, 0.0)
+                """,
+                mid=memory_id, uid=user_id,
+                strength=strength, importance=importance, category=category,
+            )
+
+    def update_node_strength(self, memory_id: int, strength: float) -> None:
+        with self._driver.session() as s:
+            s.run(
+                "MATCH (m:Memory {memory_id: $mid}) SET m.strength = $strength",
+                mid=memory_id, strength=strength,
+            )
+
+    def get_node_strength(self, memory_id: int) -> Optional[float]:
+        with self._driver.session() as s:
+            result = s.run(
+                "MATCH (m:Memory {memory_id: $mid}) RETURN m.strength AS strength",
+                mid=memory_id,
+            ).single()
+            return result["strength"] if result else None
+
+    def get_all_nodes_for_user(self, user_id: str) -> list:
+        with self._driver.session() as s:
+            records = s.run(
+                """
+                MATCH (m:Memory {user_id: $uid})
+                RETURN m.memory_id AS memory_id,
+                       m.strength   AS strength,
+                       m.importance AS importance,
+                       m.category   AS category,
+                       m.recall_proxy AS recall_proxy
+                """,
+                uid=user_id,
+            )
+            return [
+                {
+                    "memory_id":   r["memory_id"],
+                    "user_id":     user_id,
+                    "strength":    r["strength"],
+                    "importance":  r["importance"],
+                    "category":    r["category"],
+                    "recall_proxy": r["recall_proxy"],
+                }
+                for r in records
+            ]
+
+    def delete_node(self, memory_id: int) -> None:
+        with self._driver.session() as s:
+            s.run(
+                "MATCH (m:Memory {memory_id: $mid}) DETACH DELETE m",
+                mid=memory_id,
+            )
+
+    # ------------------------------------------------------------------ #
+    # Edge operations
+    # ------------------------------------------------------------------ #
+
+    def upsert_edge(self, source_id: int, target_id: int,
+                    relation: str, weight: float) -> None:
+        with self._driver.session() as s:
+            s.run(
+                """
+                MATCH (a:Memory {memory_id: $src}), (b:Memory {memory_id: $tgt})
+                MERGE (a)-[r:RELATES]->(b)
+                ON CREATE SET r.relation = $relation, r.weight = $weight
+                ON MATCH  SET r.weight   = CASE
+                    WHEN r.weight + $weight * 0.1 < 1.0
+                    THEN r.weight + $weight * 0.1
+                    ELSE 1.0
+                END
+                """,
+                src=source_id, tgt=target_id,
+                relation=relation, weight=weight,
+            )
+
+    # ------------------------------------------------------------------ #
+    # Traversal
+    # ------------------------------------------------------------------ #
+
+    def get_neighbors(self, memory_id: int, user_id: str,
+                      max_depth: int = 2) -> list:
+        """BFS up to max_depth hops (undirected) — only returns user_id nodes."""
+        with self._driver.session() as s:
+            records = s.run(
+                """
+                MATCH path = (start:Memory {memory_id: $mid})-[:RELATES*1..$depth]-(nbr:Memory)
+                WHERE nbr.user_id = $uid AND nbr.memory_id <> $mid
+                WITH nbr,
+                     length(path) AS distance,
+                     reduce(w = 1.0, r IN relationships(path) | w * r.weight) AS edge_weight
+                RETURN nbr.memory_id AS memory_id, distance, edge_weight
+                ORDER BY edge_weight DESC
+                """,
+                mid=memory_id, uid=user_id, depth=max_depth,
+            )
+            # Deduplicate: keep highest edge_weight per neighbor
+            seen: dict[int, dict] = {}
+            for r in records:
+                nid = r["memory_id"]
+                if nid not in seen or r["edge_weight"] > seen[nid]["edge_weight"]:
+                    seen[nid] = {
+                        "memory_id":   nid,
+                        "distance":    r["distance"],
+                        "edge_weight": r["edge_weight"],
+                    }
+            return list(seen.values())
+
+    def boost_node_and_neighbors(self, memory_id: int, user_id: str,
+                                  boost: float = 0.2,
+                                  max_depth: int = 1) -> list:
+        neighbors = self.get_neighbors(memory_id, user_id, max_depth=max_depth)
+        if not neighbors:
+            return []
+        boosted = []
+        with self._driver.session() as s:
+            for nbr in neighbors:
+                nid      = nbr["memory_id"]
+                edge_w   = nbr["edge_weight"]
+                s.run(
+                    """
+                    MATCH (m:Memory {memory_id: $mid})
+                    SET m.recall_proxy = coalesce(m.recall_proxy, 0.0) + $delta
+                    """,
+                    mid=nid, delta=boost * edge_w,
+                )
+                boosted.append(nid)
+        return boosted
+
+    def close(self) -> None:
+        self._driver.close()