cortex-claude 0.7.0__tar.gz → 0.7.2__tar.gz

{cortex_claude-0.7.0 → cortex_claude-0.7.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: cortex-claude
-Version: 0.7.0
+Version: 0.7.2
 Summary: Local-first, token-efficient memory system for Claude Code via MCP
 Project-URL: Homepage, https://github.com/rafaelaugusto/cortex-claude
 Project-URL: Repository, https://github.com/rafaelaugusto/cortex-claude
@@ -68,7 +68,7 @@ Description-Content-Type: text/markdown
     <img src="https://img.shields.io/badge/License-MIT-blue.svg" alt="License">
   </a>
   <a href="pyproject.toml">
-    <img src="https://img.shields.io/badge/version-0.7.0-green.svg" alt="Version">
+    <img src="https://img.shields.io/badge/version-0.7.2-green.svg" alt="Version">
   </a>
   <a href="pyproject.toml">
     <img src="https://img.shields.io/badge/python-%3E%3D3.11-brightgreen.svg" alt="Python">
@@ -177,6 +177,17 @@ That's it. The setup command:
 
 Restart Claude Code and it works in **every project**, no per-project config needed. Claude will automatically consult Cortex before saying "I don't know" and save important context to memory.
 
+### Upgrading
+
+`uv tool install cortex-claude` is idempotent by design &mdash; if it's already installed, running it again is a no-op and does **not** fetch a newer version, even after you've `uv tool install`ed a fresh copy. Use the dedicated upgrade command instead:
+
+```bash
+uv tool upgrade cortex-claude
+cortex-claude setup
+```
+
+(`pip install --upgrade cortex-claude` is the equivalent if you installed via pip.)
+
 ### Alternative: pip
 
 ```bash

{cortex_claude-0.7.0 → cortex_claude-0.7.2}/README.md

@@ -13,7 +13,7 @@
     <img src="https://img.shields.io/badge/License-MIT-blue.svg" alt="License">
   </a>
   <a href="pyproject.toml">
-    <img src="https://img.shields.io/badge/version-0.7.0-green.svg" alt="Version">
+    <img src="https://img.shields.io/badge/version-0.7.2-green.svg" alt="Version">
   </a>
   <a href="pyproject.toml">
     <img src="https://img.shields.io/badge/python-%3E%3D3.11-brightgreen.svg" alt="Python">
@@ -122,6 +122,17 @@ That's it. The setup command:
 
 Restart Claude Code and it works in **every project**, no per-project config needed. Claude will automatically consult Cortex before saying "I don't know" and save important context to memory.
 
+### Upgrading
+
+`uv tool install cortex-claude` is idempotent by design &mdash; if it's already installed, running it again is a no-op and does **not** fetch a newer version, even after you've `uv tool install`ed a fresh copy. Use the dedicated upgrade command instead:
+
+```bash
+uv tool upgrade cortex-claude
+cortex-claude setup
+```
+
+(`pip install --upgrade cortex-claude` is the equivalent if you installed via pip.)
+
 ### Alternative: pip
 
 ```bash

{cortex_claude-0.7.0 → cortex_claude-0.7.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "cortex-claude"
-version = "0.7.0"
+version = "0.7.2"
 description = "Local-first, token-efficient memory system for Claude Code via MCP"
 readme = "README.md"
 license = { text = "MIT" }

cortex_claude-0.7.2/src/cortex_claude/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.7.2"

{cortex_claude-0.7.0 → cortex_claude-0.7.2}/src/cortex_claude/clustering/engine.py

@@ -20,6 +20,14 @@ class ClusteringConfig:
     max_label_length: int = 60
     saves_between_runs: int = 20
     cooldown_seconds: int = 300
+    # How many incremental cluster_scope() runs happen before a reassignment
+    # pass considers moving stale (poorly-fit) memories to a better cluster.
+    # 0 disables reassignment entirely. See ClusteringEngine.reassign_stale.
+    reassign_after_runs: int = 10
+    # A member is "stale" if its similarity to its own cluster's centroid
+    # has drifted below threshold * this factor — i.e. it's no longer a
+    # confident fit for the cluster it's sitting in.
+    reassign_drift_factor: float = 0.9
 
     @classmethod
     def from_dict(cls, raw: dict) -> ClusteringConfig:
@@ -33,6 +41,8 @@ class ClusteringConfig:
         cfg.max_label_length = raw.get("max_label_length", cfg.max_label_length)
         cfg.saves_between_runs = raw.get("saves_between_runs", cfg.saves_between_runs)
         cfg.cooldown_seconds = raw.get("cooldown_seconds", cfg.cooldown_seconds)
+        cfg.reassign_after_runs = raw.get("reassign_after_runs", cfg.reassign_after_runs)
+        cfg.reassign_drift_factor = raw.get("reassign_drift_factor", cfg.reassign_drift_factor)
         return cfg
 
 
@@ -44,6 +54,13 @@ class ClusterStats:
     skipped: int = 0
 
 
+@dataclass
+class ReassignStats:
+    moved: int = 0
+    examined: int = 0
+    emptied_clusters: int = 0
+
+
 def _cosine(a: np.ndarray, b: np.ndarray) -> float:
     return _cosine_with_norms(a, float(np.linalg.norm(a)), b, float(np.linalg.norm(b)))
 
@@ -64,11 +81,15 @@ class ClusteringEngine:
 
     Labels are derived from the most frequent subjects/objects in the cluster's facts.
 
-    Note: clustering is append-only. A memory is only ever considered while
-    its `cluster_id` is NULL, so once assigned it never migrates even if a
-    better-fitting cluster appears later. Memories are processed in a fixed
-    `created_at ASC` order so repeated runs over the same data are
-    deterministic. To force a full re-clustering (e.g. after tuning
+    Note: incremental assignment (cluster_scope) is append-only — a memory
+    is only ever considered while its `cluster_id` is NULL, so a single run
+    never migrates an already-assigned memory even if a better-fitting
+    cluster appears later. Memories are processed in a fixed `created_at
+    ASC` order so repeated runs over the same data are deterministic.
+    `reassign_stale` mitigates drift from the append-only design with a
+    separate, periodic pass that moves poorly-fit memories to a better
+    cluster (see its docstring) — this is targeted, not a full
+    re-clustering. To force a full re-clustering (e.g. after tuning
     `similarity_threshold`), use `cortex_clusters action="backfill"`, which
     resets all assignments in the scope before re-running.
     """
@@ -145,6 +166,86 @@ class ClusteringEngine:
 
         return stats
 
+    def reassign_stale(self, conn: sqlite3.Connection, scope: str) -> ReassignStats:
+        """Move poorly-fit memories to a better cluster.
+
+        Clustering is normally append-only (see class docstring) — this is
+        the mitigation for that: a periodic, targeted pass (not a full
+        re-clustering) that only touches memories whose similarity to their
+        *own* cluster's centroid has drifted below
+        `threshold * reassign_drift_factor`. For each such memory, it finds
+        the best-fitting cluster among all existing centroids in the scope
+        and moves the memory there if that's a different, better-fitting
+        cluster. Both the origin and destination clusters' centroids and
+        member_counts are updated. A cluster left with zero members is
+        deleted.
+        """
+        stats = ReassignStats()
+        if not self.config.enabled or self.config.reassign_after_runs <= 0:
+            return stats
+
+        existing = self._clusters.list_for_scope(conn, scope)
+        centroids: dict[int, tuple[np.ndarray, float, int]] = {
+            c.id: (c.centroid, float(np.linalg.norm(c.centroid)), c.member_count)
+            for c in existing
+            if c.centroid is not None
+        }
+        if len(centroids) < 2:
+            return stats
+
+        members = self._memories.iter_clustered_with_embeddings(conn, scope)
+        threshold = self.config.similarity_threshold * self.config.reassign_drift_factor
+
+        moves: list[tuple[str, int, int]] = []  # (memory_id, from_cluster, to_cluster)
+        for memory_id, emb, current_cluster_id in members:
+            current = centroids.get(current_cluster_id)
+            if current is None:
+                continue
+            emb_norm = float(np.linalg.norm(emb))
+            current_sim = _cosine_with_norms(emb, emb_norm, current[0], current[1])
+            if current_sim >= threshold:
+                continue
+
+            stats.examined += 1
+            best_id, best_sim = current_cluster_id, current_sim
+            for cid, (centroid, centroid_norm, _) in centroids.items():
+                sim = _cosine_with_norms(emb, emb_norm, centroid, centroid_norm)
+                if sim > best_sim:
+                    best_sim = sim
+                    best_id = cid
+
+            if best_id != current_cluster_id:
+                moves.append((memory_id, current_cluster_id, best_id))
+
+        if not moves:
+            return stats
+
+        # Apply moves against the DB (member_count/centroid recomputed from
+        # ground truth afterward, not tracked incrementally — reassignment
+        # is infrequent enough that re-reading is cheap and avoids drift
+        # between in-memory bookkeeping and what's actually stored).
+        self._memories.set_cluster_batch(
+            conn, [(mid, to_cid) for mid, _, to_cid in moves]
+        )
+        stats.moved = len(moves)
+
+        touched: set[int] = set()
+        for _, from_cid, to_cid in moves:
+            touched.add(from_cid)
+            touched.add(to_cid)
+
+        for cid in touched:
+            remaining = self._memories.get_embeddings_for_cluster(conn, cid)
+            if not remaining:
+                self._clusters.delete(conn, cid)
+                stats.emptied_clusters += 1
+                continue
+            new_centroid = np.mean(remaining, axis=0)
+            self._clusters.update_centroid(conn, cid, new_centroid, member_count=len(remaining))
+            self._relabel_cluster(conn, cid)
+
+        return stats
+
     def _relabel_cluster(self, conn: sqlite3.Connection, cluster_id: int) -> bool:
         cluster = self._clusters.get(conn, cluster_id)
         if cluster is None or cluster.member_count < self.config.min_members_for_label:

{cortex_claude-0.7.0 → cortex_claude-0.7.2}/src/cortex_claude/code/extractor.py

@@ -32,6 +32,13 @@ class Symbol:
     calls: list[str] = field(default_factory=list)
     extends: list[str] = field(default_factory=list)
     imports: list[str] = field(default_factory=list)
+    # Best-effort correlation of calls to the module they were imported
+    # from, populated only where the extractor can resolve it (currently:
+    # Python `from module import name` followed by a call to `name()` in
+    # the same file — the most common case, not a full import resolver).
+    # Maps callee name -> source module. See extract_symbols for how this
+    # is built; empty when nothing could be resolved.
+    resolved_calls: dict[str, str] = field(default_factory=dict)
 
 
 # Tree-sitter S-expression queries per language. We capture functions, classes/structs,
@@ -44,6 +51,7 @@ QUERIES: dict[str, str] = {
         (class_definition name: (identifier) @class.name) @class.body
         (import_statement name: (dotted_name) @import.name)
         (import_from_statement module_name: (dotted_name) @import.name)
+        (import_from_statement name: (dotted_name) @import.imported_name)
         (call function: (identifier) @call.name)
         (call function: (attribute attribute: (identifier) @call.name))
     """,
@@ -209,6 +217,10 @@ def extract_symbols(path: str | Path, content: str) -> list[Symbol]:
     pending_calls: list[tuple[int, str]] = []
     pending_imports: list[str] = []
     pending_extends: list[str] = []
+    # name imported via `from module import name` -> module it came from.
+    # Populated only for Python (see QUERIES["python"]'s import.imported_name
+    # capture); empty for every other language.
+    imported_name_to_module: dict[str, str] = {}
 
     path_str = str(path)
     captures_iter = (
@@ -242,6 +254,14 @@ def extract_symbols(path: str | Path, content: str) -> list[Symbol]:
         elif capture_name == "import.name":
             text = node.text.decode("utf-8", errors="ignore").strip("\"'")
             pending_imports.append(text)
+        elif capture_name == "import.imported_name":
+            imported_name = node.text.decode("utf-8", errors="ignore")
+            parent = node.parent
+            if parent is not None and parent.type == "import_from_statement":
+                module_node = parent.child_by_field_name("module_name")
+                if module_node is not None:
+                    module_text = module_node.text.decode("utf-8", errors="ignore")
+                    imported_name_to_module[imported_name] = module_text
         elif capture_name == "class.extends":
             text = node.text.decode("utf-8", errors="ignore")
             pending_extends_with_pos.append((node.start_byte, text))
@@ -274,6 +294,9 @@ def extract_symbols(path: str | Path, content: str) -> list[Symbol]:
                 sym = symbols_by_body[key]
                 if call_name != sym.name and call_name not in sym.calls:
                     sym.calls.append(call_name)
+                module = imported_name_to_module.get(call_name)
+                if module is not None:
+                    sym.resolved_calls[call_name] = module
                 break
 
     # Attach extends to the enclosing class symbol when possible.

{cortex_claude-0.7.0 → cortex_claude-0.7.2}/src/cortex_claude/code/facts.py

@@ -72,15 +72,22 @@ def symbols_to_facts(symbols: list[Symbol]) -> list[Fact]:
     """Convert extracted symbols into knowledge-graph facts.
 
     Vocabulary:
-      - subject → defined_in → path:line   (one per symbol)
-      - subject → in_language → lang       (one per symbol)
-      - subject → calls → callee           (one per call site)
+      - subject → defined_in → path:line       (one per symbol)
+      - subject → in_language → lang           (one per symbol)
+      - subject → calls → callee               (one per call site)
       - subject → extends → parent_class
       - subject → imports → module_path
+      - path:subject → calls_from → module:callee   (aditional, best-effort)
 
     `calls`/`extends` resolution is purely textual (same-name matching
     within the parsed file), not scope- or import-aware — two same-named
-    functions in different files/scopes will share the same graph node.
+    functions in different files/scopes will share the same graph node
+    under `calls`. `calls_from` is an additive relation (never replaces
+    `calls`) that qualifies a call by both the caller's file (via a
+    `path:name` subject) and the callee's source module, but only for
+    calls the extractor could resolve against a `from module import name`
+    in the same file (see `Symbol.resolved_calls`) — most calls (same-file,
+    builtins, `module.func()` style, method calls) are not covered.
     """
     facts: list[Fact] = []
     seen: set[tuple[str, str, str]] = set()
@@ -108,6 +115,9 @@ def symbols_to_facts(symbols: list[Symbol]) -> list[Fact]:
         for callee in sym.calls:
             add(sym.name, "calls", callee)
 
+        for callee, module in sym.resolved_calls.items():
+            add(f"{sym.path}:{sym.name}", "calls_from", f"{module}:{callee}")
+
         for parent in sym.extends:
             add(sym.name, "extends", parent)
 

{cortex_claude-0.7.0 → cortex_claude-0.7.2}/src/cortex_claude/core/engine.py

@@ -5,6 +5,8 @@ from dataclasses import dataclass
 from pathlib import Path
 from typing import Literal
 
+import numpy as np
+
 from cortex_claude.core.decay import recalculate_decay_scores
 from cortex_claude.core.privacy import is_fully_private, strip_private
 from cortex_claude.core.scope_manager import ScopeManager
@@ -88,42 +90,55 @@ class CortexEngine:
             (c for c in candidates if c[1] >= self._config.dedup_similarity_threshold),
             None,
         )
-        if dup_candidate:
-            existing_memory = self._memory_repo.get(conn, dup_candidate[0])
-            if existing_memory:
-                merged = f"{existing_memory.content}\n\n{content}"
-                self._fact_repo.delete_by_memory(conn, existing_memory.id)
-                self._memory_repo.delete(conn, existing_memory.id)
-                content = merged
-                embedding = self._embeddings.embed(content)
-                tokens = count_tokens(content)
-
-        summary = summarize(content) if tokens > 50 else None
-
-        memory = Memory(
-            content=content,
-            summary=summary,
-            tags=tags or [],
-            scope=write_scope,
-        )
 
-        self._memory_repo.save(conn, memory, embedding)
+        # Everything below is one logical unit of work (dedup merge, insert,
+        # fact extraction/contradiction handling) — run it as a single
+        # transaction so a crash or exception midway can't leave a memory
+        # persisted without its facts, or facts penalized without the new
+        # memory actually saved. Every repo call below passes commit=False;
+        # we commit once at the end (or roll back on any exception).
+        try:
+            if dup_candidate:
+                existing_memory = self._memory_repo.get(conn, dup_candidate[0])
+                if existing_memory:
+                    merged = f"{existing_memory.content}\n\n{content}"
+                    self._fact_repo.delete_by_memory(conn, existing_memory.id, commit=False)
+                    self._memory_repo.delete(conn, existing_memory.id, commit=False)
+                    content = merged
+                    embedding = self._embeddings.embed(content)
+                    tokens = count_tokens(content)
+
+            summary = summarize(content) if tokens > 50 else None
+
+            memory = Memory(
+                content=content,
+                summary=summary,
+                tags=tags or [],
+                scope=write_scope,
+            )
 
-        facts = extract_facts(
-            content,
-            min_confidence=self._config.fact_min_confidence,
-            claude_fallback=self._config.fact_claude_fallback,
-            claude_confidence_threshold=self._config.fact_claude_confidence_threshold,
-        )
-        for fact in facts:
-            fact.source_memory_id = memory.id
-            fact.scope = write_scope
-        if facts:
+            self._memory_repo.save(conn, memory, embedding, commit=False)
+
+            facts = extract_facts(
+                content,
+                min_confidence=self._config.fact_min_confidence,
+                claude_fallback=self._config.fact_claude_fallback,
+                claude_confidence_threshold=self._config.fact_claude_confidence_threshold,
+            )
             for fact in facts:
-                contradictions = self._fact_repo.detect_contradictions(conn, fact, write_scope)
-                if contradictions:
-                    self._fact_repo.penalize(conn, [c.id for c in contradictions])
-            self._fact_repo.save_batch(conn, facts)
+                fact.source_memory_id = memory.id
+                fact.scope = write_scope
+            if facts:
+                for fact in facts:
+                    contradictions = self._fact_repo.detect_contradictions(conn, fact, write_scope)
+                    if contradictions:
+                        self._fact_repo.penalize(conn, [c.id for c in contradictions], commit=False)
+                self._fact_repo.save_batch(conn, facts, commit=False)
+
+            conn.commit()
+        except Exception:
+            conn.rollback()
+            raise
 
         return SaveResult(
             memory_id=memory.id,
@@ -258,8 +273,6 @@ class CortexEngine:
             if cluster is None or cluster.scope != s:
                 continue
 
-            import numpy as np
-
             centroid = cluster.centroid
             if centroid is None:
                 continue
@@ -592,12 +605,10 @@ class CortexEngine:
     ) -> ForgetResult:
         """Delete memories by id or semantic query.
 
-        Note: deleting a clustered memory updates the owning cluster's
-        member_count (via recount_members) but does not recompute its
-        centroid — the centroid drifts slightly stale until the next
-        `cortex_clusters action="backfill"`. Recomputing it on every forget
-        would require re-reading every remaining member's embedding, which
-        is too expensive to do per-delete.
+        Deleting a clustered memory recomputes the owning cluster's
+        centroid and member_count from its remaining members. Clusters left
+        with zero members are deleted outright rather than lingering with a
+        stale centroid.
         """
         scopes = [scope] if scope else self._scope_manager.resolve(cwd)
         # candidate_scope tracks, per to-be-deleted memory id, which scope it
@@ -625,7 +636,7 @@ class CortexEngine:
 
         deleted_by_scope: dict[str, list[str]] = {}
         if not dry_run:
-            touched_cluster_scopes: set[str] = set()
+            touched_clusters: set[tuple[str, int]] = set()
             for mid in to_delete:
                 s = candidate_scope.get(mid)
                 if s is None:
@@ -637,11 +648,19 @@ class CortexEngine:
                     cluster_id = self._memory_repo.delete(conn, mid)
                     deleted_by_scope.setdefault(s, []).append(mid)
                     if cluster_id is not None:
-                        touched_cluster_scopes.add(s)
+                        touched_clusters.add((s, cluster_id))
 
-            for s in touched_cluster_scopes:
+            for s, cluster_id in touched_clusters:
                 conn = self._storage.get_database(s)
-                self._cluster_repo.recount_members(conn, s)
+                remaining = self._memory_repo.get_embeddings_for_cluster(conn, cluster_id)
+                if not remaining:
+                    self._cluster_repo.delete(conn, cluster_id)
+                    conn.commit()
+                    continue
+                new_centroid = np.mean(remaining, axis=0)
+                self._cluster_repo.update_centroid(
+                    conn, cluster_id, new_centroid, member_count=len(remaining)
+                )
         else:
             for mid in to_delete:
                 s = candidate_scope.get(mid)

{cortex_claude-0.7.0 → cortex_claude-0.7.2}/src/cortex_claude/daemon.py

@@ -43,6 +43,7 @@ class CortexDaemon:
         self._saves_since_cluster: dict[str, int] = {}
         self._last_cluster_at: dict[str, float] = {}
         self._cluster_in_flight: set[str] = set()
+        self._cluster_runs_since_reassign: dict[str, int] = {}
         self._known_symbols_cache: dict[str, set[str]] = {}
         self._project_scan_in_flight: set[str] = set()
         self._project_scan_tasks: dict[str, asyncio.Task] = {}
@@ -305,10 +306,25 @@ class CortexDaemon:
             conn = self._engine.get_scope_connection(scope)
             stats = await asyncio.to_thread(self._cluster_engine.cluster_scope, conn, scope)
             self._last_cluster_at[scope] = time.time()
+            self._maybe_reassign_stale(conn, scope)
             return stats
         finally:
             self._cluster_in_flight.discard(scope)
 
+    def _maybe_reassign_stale(self, conn, scope: str) -> None:
+        reassign_after = self._cluster_config.reassign_after_runs
+        if reassign_after <= 0:
+            return
+
+        self._cluster_runs_since_reassign[scope] = (
+            self._cluster_runs_since_reassign.get(scope, 0) + 1
+        )
+        if self._cluster_runs_since_reassign[scope] < reassign_after:
+            return
+
+        self._cluster_runs_since_reassign[scope] = 0
+        self._cluster_engine.reassign_stale(conn, scope)
+
     async def start(self):
         if SOCKET_PATH.exists():
             SOCKET_PATH.unlink()