flurryx-code-memory 0.6.2__tar.gz → 0.7.0__tar.gz

{flurryx_code_memory-0.6.2 → flurryx_code_memory-0.7.0}/CHANGELOG.md

@@ -8,6 +8,207 @@ when the repo grows.
 This file complements `git log`: commits explain mechanics, this file
 explains intent.
 
+## [0.7.0] — 2026-06-12
+
+Release theme: **Worktree resilience, atomic graph rebuilds, and fresh
+indexes**. The index now survives interrupted full ingests; linked git
+worktrees reuse the main repo's index instead of forcing a cold re-ingest;
+and queries trigger non-blocking background rebuilds when the index drifts
+from HEAD.
+
+### Added — Linked git worktree awareness
+
+**What:** a new `_git_toplevel()` helper resolves linked git worktrees
+to the main repo's root by running `git rev-parse --git-common-dir`
+after the baseline `--show-toplevel` call. In a linked worktree, the
+two paths differ; in the main worktree, they're the same. The project
+slug is now derived from the main repo's directory name, so all worktrees
+of the same project reuse the same Qdrant / Falkor namespace without
+requiring a cold re-ingest.
+
+**Reason:** developers working in linked worktrees (e.g. `git worktree add
+../feature-branch`) saw no code-memory functionality because the ingest
+system minted a separate Qdrant collection and Falkor graph for each
+worktree. A single repo with 3–5 active worktrees accumulated 3–5 cold
+ingests. The main repo and each worktree now share the same index.
+
+### Added — Non-persistent autostart for linked worktrees
+
+**What:** two new gates in the autostart system:
+
+- `is_linked_git_worktree(path)` — checks whether *path* is inside a
+  linked worktree via git CLI.
+- `is_non_persistent_watch_dir(path)` — returns True for ephemeral
+  session dirs OR linked worktrees; used by `ensure_autostart()` to skip
+  registering a persistent OS agent for directories that are temporary or
+  share the main repo's watcher.
+- `LaunchdAdapter.prune_stale()` (run on every MCP bootstrap) removes
+  launchd agents whose `WorkingDirectory` is gone or is a linked worktree.
+
+**Reason:** the prior release fixed the watcher's per-session accumulation;
+this release prevents the same bleed on linked worktrees. A developer with
+2 linked worktrees no longer gets 3 persistent `code-memory watch` units.
+
+### Added — Shadow-graph atomic promotion (graph durability fix)
+
+**What:** the full ingest pipeline now builds into a shadow FalkorDB
+graph named `<project_graph>__shadow` and atomically promotes it only
+after the rebuild succeeds:
+
+1. At ingest start, drop any leftover shadow from a prior interrupted
+   rebuild.
+2. Redirect all graph writes to the shadow FalkorStore instance.
+3. On successful completion, execute `GRAPH.DELETE <live>`, then
+   `GRAPH.COPY <shadow> <live>`, then `GRAPH.DELETE <shadow>`.
+4. If the copy fails, the live graph is cleared but the shadow stays
+   intact — the caller can retry without losing data.
+
+**Reason:** before this, an interrupted full ingest (network loss,
+Ollama timeout, Falkor down, user kills the process) left the live
+graph empty so subsequent `callers` / `definitions` / `callees` queries
+returned nothing until a manual full re-ingest. The graph now survives
+interruption — the shadow is cleaned up on the next rebuild attempt.
+
+### Added — Health-check guard for stale rebuilds
+
+**What:** the ingest state now records `file_count` and `symbol_count`
+from each successful full rebuild. Before starting an incremental ingest,
+`_health_check_ok()` compares the current ingestable file count against
+the stored baseline; if it grew more than 20% and the graph symbol count
+is suspiciously low (below a ratio threshold), a full rebuild is forced
+with a diagnostic message to stderr.
+
+Config:
+- `CODE_MEMORY_INGEST_HEALTH_CHECK_ENABLED` (default `true`)
+- `CODE_MEMORY_INGEST_HEALTH_CHECK_MIN_RATIO` (default `0.3` = expect ≥30%
+  of file count as symbol count)
+
+**Reason:** a transient FalkorDB outage or an incomplete prior ingest
+could leave the graph permanently empty while incremental ingests reported
+success. The health check detects this silently-failed state and forces a
+rebuild, with no user intervention needed.
+
+### Added — Single-flight ingest lock
+
+**What:** new `src/code_memory/sync/single_flight.py` module provides
+in-process (`asyncio.Lock`) + cross-process (PID file) guards to prevent
+concurrent full ingests for the same (root, project) pair.
+
+- `try_acquire(root, project)` — returns True if no rebuild is running,
+  False if the slot is taken.
+- `release(root, project)` — releases the slot unconditionally.
+- Stale PID files (dead process or age > 30 min) are silently removed.
+
+The Claude Code and Cursor plugins' `on-session-start.js` fast-path-skip a
+spawn when a live ingest is detected, preventing thundering-herd `code-memory
+ingest` calls on boot.
+
+**Reason:** on slow machines or large repos, overlapping `code-memory ingest`
+calls could queue up and queue up (especially if the embedder is I/O-bound),
+causing a session to take 5+ minutes to boot. The lock ensures at most one
+rebuild runs; fast-path skips spare the overhead.
+
+### Added — Ingest safety guards
+
+**What:** new `assert_safe_ingest_root()` function in `sync/safety.py`
+refuses to ingest:
+
+1. System/HOME roots (same set as the watcher guard: HOME, /, /tmp,
+   /var, /etc, /usr, /System, /Library, /opt, /Applications, C:/, etc.)
+2. Non-git directories (checked via `is_inside_git_worktree()`).
+
+Bypass via `CODE_MEMORY_UNSAFE_INGEST=1` env var (env-only, not a CLI
+flag, to prevent accidental use).
+
+**Reason:** `code-memory ingest ~` could walk every IDE cache, checkout,
+and node_modules on disk. `ingest` is more dangerous than `watch` because
+it stores results; a non-git directory ingest mints an arbitrary project
+slug. The guard is invoked by the CLI `ingest` entry point and by hooks.
+
+### Added — IPv4-default service URLs
+
+**What:** the default `OLLAMA_URL`, `QDRANT_URL`, and `FALKOR_URL` now
+use `127.0.0.1` instead of `localhost`. This works around a Windows
+quirk where `localhost` may resolve to `::1` (IPv6) and hang on socket
+connect.
+
+Config example (all in `.code-memoryrc` or env):
+```
+OLLAMA_URL=http://127.0.0.1:11434
+QDRANT_URL=http://127.0.0.1:6333
+FALKOR_URL=redis://127.0.0.1:6379
+```
+
+**Reason:** on some Windows setups, the TCP stack prefers IPv6 and
+binds localhost to `::1`, while the service listens on `127.0.0.1`.
+Callers then hang waiting for a timeout (seconds to minutes). Using
+the explicit IPv4 address is more reliable.
+
+### Added — Non-blocking `_ensure_fresh` for MCP queries
+
+**What:** the pre-query guard `_ensure_fresh()` no longer blocks on a
+sync. Instead:
+
+1. Spawn a quick freshness check (`_is_index_stale()`) in a bounded
+   daemon thread (`_FRESHNESS_PROBE_TIMEOUT`, default 2.0 s).
+2. If the index is stale AND the check finished in time, fire a
+   background `_background_rebuild()` in a detached daemon thread
+   protected by the single-flight lock.
+3. Return immediately so the query gets the current (possibly stale)
+   index while the rebuild runs in the background.
+
+**Reason:** MCP queries were blocking on a full ingest in the worst case,
+causing Claude Code / OpenCode / Cursor to hang for minutes. Now the agent
+gets an answer immediately while background sync keeps the index fresh.
+
+### Fixed — Ollama embed connect timeout
+
+**What:** `OllamaEmbedder` now uses split connect/read timeouts:
+
+- `_DEFAULT_CONNECT_TIMEOUT = 5.0 s` — fail fast on wrong stack (IPv6
+  vs IPv4) or misconfigured host.
+- `_DEFAULT_READ_TIMEOUT = 300.0 s` — Ollama's cold-load model phase
+  happens during read, not connect.
+
+Configurable via `OLLAMA_CONNECT_TIMEOUT` and `OLLAMA_READ_TIMEOUT`
+env vars.
+
+**Reason:** the old single `timeout=300` param applied to connect, which
+could hang for 300 s waiting on a misconfigured IPv6 address. A 5 s
+connect timeout with 3 retries fails fast (~15 s worst case) instead.
+
+### Added — Vibe plugin
+
+**What:** new `plugins/vibe/` brings code-memory to Mistral Vibe. Vibe
+lacks lifecycle hooks (unlike Claude Code, Cursor, OpenCode), so the
+plugin delivers:
+
+- **Skill** (`/code-memory`) with orientation guidance and manual command
+  runner.
+- **MCP server** registration in `config.toml`.
+- **OS autostart watcher** for file-edit → auto-reingest (since hooks
+  aren't available).
+
+Install: `./plugins/vibe/install.sh` (default user scope, with flags for
+project scope, no-mcp, no-watch, uninstall).
+
+**Reason:** Vibe is a code-aware LLM editor with a different extension
+model. Bundling the same code-memory integration surfaces our topology
+queries to Vibe users without reimplementation.
+
+### Added — Ingest state enhancements
+
+**What:** the ingest state now stores:
+
+- `file_count` / `symbol_count` from each full rebuild (used by the
+  health check).
+- `file_count` and `symbol_count` are populated by the pipeline during
+  ingest and read by the health-check predicate before deciding to
+  rebuild.
+
+**Reason:** enables the health-check guard to detect silently-failed
+ingests.
+
 ## [0.6.0] — 2026-06-04
 
 Release theme: **Dart joins the graph, and `this.field.method()` resolves

{flurryx_code_memory-0.6.2 → flurryx_code_memory-0.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: flurryx-code-memory
-Version: 0.6.2
+Version: 0.7.0
 Summary: Local lightweight memory layer for coding agents: FalkorDB + Qdrant + Ollama (BGE-M3) + tree-sitter
 Requires-Python: >=3.11
 Requires-Dist: anyio>=4.4

{flurryx_code_memory-0.6.2/plugins/cursor → flurryx_code_memory-0.7.0/plugins/claude-code}/scripts/lib/memory.js

@@ -7,6 +7,8 @@
  */
 
 const { execFile } = require("node:child_process");
+const fs = require("node:fs");
+const nodePath = require("node:path");
 
 const DEFAULT_BINARY = process.env.CODE_MEMORY_BIN || "code-memory";
 const DEFAULT_PROJECT = process.env.CODE_MEMORY_PROJECT || null;
@@ -39,6 +41,82 @@ async function detectAvailable(binary, log) {
   return ok;
 }
 
+/**
+ * Derive the lock directory used by code-memory's single_flight module.
+ * Mirrors the Python logic in sync/single_flight.py:_lock_dir().
+ * Returns null if the directory cannot be determined.
+ */
+function _lockDir() {
+  const override = process.env.CODE_MEMORY_LOCK_DIR;
+  if (override) return override;
+  const stateHome =
+    process.env.XDG_STATE_HOME ||
+    nodePath.join(
+      process.env.HOME || process.env.USERPROFILE || "",
+      ".local",
+      "state",
+    );
+  return nodePath.join(stateHome, "code-memory", "locks");
+}
+
+/**
+ * Fast-path check: return true if a live ingest is already running for
+ * (resolvedRoot, slug).  Mirrors Python single_flight._is_stale() logic:
+ * a lockfile is considered live when it exists, is not older than the TTL,
+ * and its PID is still running.
+ *
+ * This is JS-side best-effort only — the Python ingest entry point is the
+ * authoritative single-flight guard.  We check here solely to avoid
+ * spawning a new process that would immediately lose the race.
+ *
+ * @param {string} resolvedRoot - Absolute resolved path of the repo root.
+ * @param {string} slug - Project slug.
+ * @returns {boolean} true when a live ingest appears to be running.
+ */
+function _ingestLockLive(resolvedRoot, slug) {
+  try {
+    const lockDir = _lockDir();
+    if (!lockDir) return false;
+
+    // Replicate the Python filename derivation:
+    //   name = f"{root_part[:64]}__{project_part[:32]}.lock"
+    const rootPart = resolvedRoot.replace(/[/\\]/g, "_").replace(/ /g, "_").slice(0, 64);
+    const slugPart = slug.replace(/\//g, "_").replace(/ /g, "_").slice(0, 32);
+    const lockFile = nodePath.join(lockDir, `${rootPart}__${slugPart}.lock`);
+
+    let stat;
+    try {
+      stat = fs.statSync(lockFile);
+    } catch {
+      return false; // file does not exist — no live ingest
+    }
+
+    const ttl = parseFloat(process.env.CODE_MEMORY_REBUILD_LOCK_TTL || "3600");
+    const ageSecs = (Date.now() - stat.mtimeMs) / 1000;
+    if (ageSecs > ttl) return false; // stale by age
+
+    let pid;
+    try {
+      pid = parseInt(fs.readFileSync(lockFile, "utf8").trim(), 10);
+    } catch {
+      return false; // unreadable → treat as stale
+    }
+    if (!pid || isNaN(pid)) return false;
+
+    // Check if the PID is alive (POSIX: signal 0; Windows: tasklist not used,
+    // fall back to optimistic "assume live" to avoid a subprocess spawn).
+    try {
+      process.kill(pid, 0);
+      return true; // PID exists and is alive
+    } catch (e) {
+      if (e.code === "EPERM") return true; // exists but we lack permission
+      return false; // ESRCH — process is dead
+    }
+  } catch {
+    return false; // any unexpected error → don't block
+  }
+}
+
 /**
  * Spawn detached fire-and-forget. Parent exits immediately.
  * stdout/stderr ignored. Used when the hook must not block.
@@ -115,6 +193,13 @@ async function createMemoryClient(opts = {}) {
 
     ingestDetached({ full = false } = {}) {
       if (!available) return false;
+      // Fast-path: skip spawn if the Python single-flight lock shows a live
+      // ingest is already running for this root.  The CLI is the authoritative
+      // guard; this avoids spawning a process that would immediately lose the
+      // race and exit with code 0.
+      const resolvedCwd = nodePath.resolve(cwd);
+      const slug = project || nodePath.basename(resolvedCwd);
+      if (_ingestLockLive(resolvedCwd, slug)) return false;
       return spawnDetached(
         binary,
         ["ingest", cwd, "--json", ...(full ? ["--full"] : []), ...baseArgs(project)],

{flurryx_code_memory-0.6.2 → flurryx_code_memory-0.7.0}/plugins/claude-code/scripts/on-session-start.js

@@ -25,8 +25,18 @@ const { pruneExpired } = require("./lib/state");
   const mem = await createMemoryClient({ cwd, log });
   if (mem.available) {
     // Ensure a launchd/systemd watcher unit exists for this repo so file
-    // edits between sessions trigger reingest automatically. Idempotent;
-    // safety guard inside the CLI refuses home/root / non-VCS dirs.
+    // edits between sessions trigger reingest automatically. Idempotent.
+    //
+    // Both calls delegate to the `code-memory` binary (DEFAULT_BINARY /
+    // CODE_MEMORY_BIN — see lib/memory.js).  The CLI enforces its own
+    // safety guards at the Python entry point:
+    //   • `autostart install` — rejects HOME / system roots / ephemeral dirs
+    //     via sync/safety.py:assert_safe_watch_root (wired in cli.py:watch).
+    //   • `ingest` — rejects HOME / filesystem roots / non-git dirs via
+    //     sync/safety.py:assert_safe_ingest_root (wired in cli.py:ingest).
+    //     A single-flight PID lock also prevents concurrent ingests for the
+    //     same root (sync/single_flight.py).
+    // These guards are install-version-independent (PyPI, uv tool, editable).
     mem.autostartInstallDetached();
     mem.ingestDetached();
   }

{flurryx_code_memory-0.6.2/plugins/claude-code → flurryx_code_memory-0.7.0/plugins/cursor}/scripts/lib/memory.js

@@ -7,6 +7,8 @@
  */
 
 const { execFile } = require("node:child_process");
+const fs = require("node:fs");
+const nodePath = require("node:path");
 
 const DEFAULT_BINARY = process.env.CODE_MEMORY_BIN || "code-memory";
 const DEFAULT_PROJECT = process.env.CODE_MEMORY_PROJECT || null;
@@ -39,6 +41,82 @@ async function detectAvailable(binary, log) {
   return ok;
 }
 
+/**
+ * Derive the lock directory used by code-memory's single_flight module.
+ * Mirrors the Python logic in sync/single_flight.py:_lock_dir().
+ * Returns null if the directory cannot be determined.
+ */
+function _lockDir() {
+  const override = process.env.CODE_MEMORY_LOCK_DIR;
+  if (override) return override;
+  const stateHome =
+    process.env.XDG_STATE_HOME ||
+    nodePath.join(
+      process.env.HOME || process.env.USERPROFILE || "",
+      ".local",
+      "state",
+    );
+  return nodePath.join(stateHome, "code-memory", "locks");
+}
+
+/**
+ * Fast-path check: return true if a live ingest is already running for
+ * (resolvedRoot, slug).  Mirrors Python single_flight._is_stale() logic:
+ * a lockfile is considered live when it exists, is not older than the TTL,
+ * and its PID is still running.
+ *
+ * This is JS-side best-effort only — the Python ingest entry point is the
+ * authoritative single-flight guard.  We check here solely to avoid
+ * spawning a new process that would immediately lose the race.
+ *
+ * @param {string} resolvedRoot - Absolute resolved path of the repo root.
+ * @param {string} slug - Project slug.
+ * @returns {boolean} true when a live ingest appears to be running.
+ */
+function _ingestLockLive(resolvedRoot, slug) {
+  try {
+    const lockDir = _lockDir();
+    if (!lockDir) return false;
+
+    // Replicate the Python filename derivation:
+    //   name = f"{root_part[:64]}__{project_part[:32]}.lock"
+    const rootPart = resolvedRoot.replace(/[/\\]/g, "_").replace(/ /g, "_").slice(0, 64);
+    const slugPart = slug.replace(/\//g, "_").replace(/ /g, "_").slice(0, 32);
+    const lockFile = nodePath.join(lockDir, `${rootPart}__${slugPart}.lock`);
+
+    let stat;
+    try {
+      stat = fs.statSync(lockFile);
+    } catch {
+      return false; // file does not exist — no live ingest
+    }
+
+    const ttl = parseFloat(process.env.CODE_MEMORY_REBUILD_LOCK_TTL || "3600");
+    const ageSecs = (Date.now() - stat.mtimeMs) / 1000;
+    if (ageSecs > ttl) return false; // stale by age
+
+    let pid;
+    try {
+      pid = parseInt(fs.readFileSync(lockFile, "utf8").trim(), 10);
+    } catch {
+      return false; // unreadable → treat as stale
+    }
+    if (!pid || isNaN(pid)) return false;
+
+    // Check if the PID is alive (POSIX: signal 0; Windows: tasklist not used,
+    // fall back to optimistic "assume live" to avoid a subprocess spawn).
+    try {
+      process.kill(pid, 0);
+      return true; // PID exists and is alive
+    } catch (e) {
+      if (e.code === "EPERM") return true; // exists but we lack permission
+      return false; // ESRCH — process is dead
+    }
+  } catch {
+    return false; // any unexpected error → don't block
+  }
+}
+
 /**
  * Spawn detached fire-and-forget. Parent exits immediately.
  * stdout/stderr ignored. Used when the hook must not block.
@@ -115,6 +193,13 @@ async function createMemoryClient(opts = {}) {
 
     ingestDetached({ full = false } = {}) {
       if (!available) return false;
+      // Fast-path: skip spawn if the Python single-flight lock shows a live
+      // ingest is already running for this root.  The CLI is the authoritative
+      // guard; this avoids spawning a process that would immediately lose the
+      // race and exit with code 0.
+      const resolvedCwd = nodePath.resolve(cwd);
+      const slug = project || nodePath.basename(resolvedCwd);
+      if (_ingestLockLive(resolvedCwd, slug)) return false;
       return spawnDetached(
         binary,
         ["ingest", cwd, "--json", ...(full ? ["--full"] : []), ...baseArgs(project)],

{flurryx_code_memory-0.6.2 → flurryx_code_memory-0.7.0}/plugins/cursor/scripts/on-session-start.js

@@ -21,6 +21,16 @@ const { pruneExpired } = require("./lib/state");
 
   const mem = await createMemoryClient({ cwd, log: () => {} });
   if (mem.available) {
+    // Both calls delegate to the `code-memory` binary (DEFAULT_BINARY /
+    // CODE_MEMORY_BIN — see lib/memory.js).  The CLI enforces its own
+    // safety guards at the Python entry point:
+    //   • `autostart install` — rejects HOME / system roots / ephemeral dirs
+    //     via sync/safety.py:assert_safe_watch_root (wired in cli.py:watch).
+    //   • `ingest` — rejects HOME / filesystem roots / non-git dirs via
+    //     sync/safety.py:assert_safe_ingest_root (wired in cli.py:ingest).
+    //     A single-flight PID lock also prevents concurrent ingests for the
+    //     same root (sync/single_flight.py).
+    // These guards are install-version-independent (PyPI, uv tool, editable).
     mem.ingestDetached();
     mem.autostartInstallDetached();
   }

{flurryx_code_memory-0.6.2 → flurryx_code_memory-0.7.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "flurryx-code-memory"
-version = "0.6.2"
+version = "0.7.0"
 description = "Local lightweight memory layer for coding agents: FalkorDB + Qdrant + Ollama (BGE-M3) + tree-sitter"
 requires-python = ">=3.11"
 dependencies = [

{flurryx_code_memory-0.6.2 → flurryx_code_memory-0.7.0}/src/code_memory/cli.py

@@ -118,14 +118,37 @@ def ingest(
 
     Default: git-aware incremental — diff prior state to HEAD.
     """
-    slug = project or detect_project_slug(root)
-    pipe = Pipeline(project=slug, skip_vectors=no_vectors)
-    stats = pipe.ingest_repo(
-        root,
-        mode="full" if full else "auto",
-        since=since,
-        dry_run=dry_run,
-    )
+    from .sync.safety import UnsafeIngestRootError, assert_safe_ingest_root
+    from .sync.single_flight import release, try_acquire
+
+    # --- Phase 3a: refuse HOME / filesystem roots / non-git dirs ----------
+    try:
+        safe_root = assert_safe_ingest_root(root)
+    except UnsafeIngestRootError as exc:
+        typer.echo(f"error: {exc}", err=True)
+        raise typer.Exit(code=2) from exc
+
+    slug = project or detect_project_slug(safe_root)
+
+    # --- Phase 3b: single-flight lock — skip if an ingest is already live --
+    if not try_acquire(safe_root, slug):
+        typer.echo(
+            f"skipped: ingest already running for project={slug!r} root={safe_root}",
+            err=True,
+        )
+        raise typer.Exit(code=0)
+
+    try:
+        pipe = Pipeline(project=slug, skip_vectors=no_vectors)
+        stats = pipe.ingest_repo(
+            safe_root,
+            mode="full" if full else "auto",
+            since=since,
+            dry_run=dry_run,
+        )
+    finally:
+        release(safe_root, slug)
+
     _emit(
         {"project": slug, "dry_run": dry_run, "ingested": asdict(stats)},
         as_json=as_json,
@@ -289,6 +312,25 @@ def reingest(
     as_json: bool = JsonOpt,
 ) -> None:
     """Re-ingest a single file."""
+    from .config import is_inside_git_worktree
+
+    # --- Phase 4: skip files that are not inside any git worktree ---------
+    # This backstop catches edits to files under ~/.claude/..., C:\Users\...,
+    # or any other non-project path that the cwd-containment guard in the JS
+    # hook can't catch when cwd itself is not a git directory.  Without this
+    # guard, detect_project_slug falls back to the raw directory name and
+    # mints parasitic Qdrant collections like "code_chunks__on-session-start-js".
+    if not is_inside_git_worktree(path.resolve().parent):
+        _emit(
+            {
+                "skipped": True,
+                "reason": "not inside a git worktree",
+                "path": str(path),
+            },
+            as_json=as_json,
+        )
+        raise typer.Exit(code=0)
+
     slug = project or detect_project_slug(path)
     pipe = Pipeline(project=slug)
     ex = pipe.reingest_file(path)