yourmemory 1.2.2__tar.gz → 1.3.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: yourmemory
-Version: 1.2.2
+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
@@ -256,17 +259,23 @@ pip install yourmemory
 
 All dependencies installed automatically. No clone, no Docker, no database setup.
 
-### 2. Get your config
+### 2. Run setup (once)
 
-Run this once to get your exact config:
+```bash
+yourmemory-setup
+```
+
+Downloads the spaCy language model and initialises the database. Run this once after install.
+
+### 3. Get your config
 
 ```bash
 yourmemory-path
 ```
 
-It prints your full executable path and a ready-to-paste config for any MCP client. Copy it.
+Prints your full executable path and a ready-to-paste config for any MCP client. Copy it.
 
-### 3. Wire into your AI client
+### 4. Wire into your AI client
 
 The database is created automatically at `~/.yourmemory/memories.duckdb` on first use.
 
@@ -352,7 +361,7 @@ Restart Claude Desktop.
 
 YourMemory is a standard stdio MCP server. Works with Claude Code, Claude Desktop, Cline, Cursor, Windsurf, Continue, and Zed. Use the full path from `yourmemory-path` if the client doesn't inherit shell PATH.
 
-### 4. Add memory instructions to your project
+### 5. Add memory instructions to your project
 
 Copy `sample_CLAUDE.md` into your project root as `CLAUDE.md` and replace:
 - `YOUR_NAME` — your name (e.g. `Alice`)

{yourmemory-1.2.2 → yourmemory-1.3.0}/README.md

@@ -61,17 +61,23 @@ pip install yourmemory
 
 All dependencies installed automatically. No clone, no Docker, no database setup.
 
-### 2. Get your config
+### 2. Run setup (once)
 
-Run this once to get your exact config:
+```bash
+yourmemory-setup
+```
+
+Downloads the spaCy language model and initialises the database. Run this once after install.
+
+### 3. Get your config
 
 ```bash
 yourmemory-path
 ```
 
-It prints your full executable path and a ready-to-paste config for any MCP client. Copy it.
+Prints your full executable path and a ready-to-paste config for any MCP client. Copy it.
 
-### 3. Wire into your AI client
+### 4. Wire into your AI client
 
 The database is created automatically at `~/.yourmemory/memories.duckdb` on first use.
 
@@ -157,7 +163,7 @@ Restart Claude Desktop.
 
 YourMemory is a standard stdio MCP server. Works with Claude Code, Claude Desktop, Cline, Cursor, Windsurf, Continue, and Zed. Use the full path from `yourmemory-path` if the client doesn't inherit shell PATH.
 
-### 4. Add memory instructions to your project
+### 5. Add memory instructions to your project
 
 Copy `sample_CLAUDE.md` into your project root as `CLAUDE.md` and replace:
 - `YOUR_NAME` — your name (e.g. `Alice`)

{yourmemory-1.2.2 → 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.2 → yourmemory-1.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "yourmemory"
-version = "1.2.2"
+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.2 → 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