conexus 5.2.0__tar.gz → 5.3.0__tar.gz

{conexus-5.2.0 → conexus-5.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: conexus
-Version: 5.2.0
+Version: 5.3.0
 Summary: Self-hosted semantic search and knowledge management for LLM-driven development
 Project-URL: Homepage, https://github.com/Hellblazer/nexus
 Project-URL: Repository, https://github.com/Hellblazer/nexus

{conexus-5.2.0 → conexus-5.3.0}/docs/rdr/README.md

@@ -146,6 +146,11 @@ An RDR (Research-Design-Review) is a short document that records a technical dec
 | [RDR-128](rdr-128-t2-single-writer-enforcement.md) | T2 Single-Writer Enforcement: One Owner for memory.db, or an Enforced Lock Discipline | Architecture | Closed 2026-05-25 (implemented, shipped 5.1.0) | 2026-05-25 |
 | [RDR-129](rdr-129-t2-daemon-serving-path-cross-store-contention.md) | T2 Daemon Write-Path Hardening: Guaranteed-Single-Daemon Enforcement and Contention-Free Internal Serialization | Architecture | Accepted | 2026-05-25 |
 | [RDR-130](rdr-130-command-preambles-via-nx-cli.md) | Command Preambles via the nx CLI: Thin Commands, Tested Logic, No Inlined Bash | Architecture | Accepted 2026-05-26 | 2026-05-26 |
+| [RDR-131](rdr-131-t2-session-rollup-summaries.md) | T2 Session Rollup Summaries (MemTree-Lite): Recency-Windowed Memory Consolidation for Compact Context Injection | Architecture | Draft | 2026-05-27 |
+| [RDR-132](rdr-132-scope-routed-t1-t2-promotion.md) | Scope-Routed T1 to T2 Promotion: Entity / Session / Project Scopes for Targeted Memory Retrieval | Architecture | Draft | 2026-05-27 |
+| [RDR-133](rdr-133-entity-cluster-cross-tier-aggregation.md) | Entity-Cluster Cross-Tier Aggregation: A First-Class Entity Handle Unifying T2 Memory, T3 Catalog, and T3 Chunks | Architecture | Draft | 2026-05-27 |
+| [RDR-134](rdr-134-taxonomy-aware-recall-in-nx-answer.md) | RDR-070 Phase 5: Taxonomy-Aware Recall in nx_answer — Teach the Composed-Retrieval Path to Read the Taxonomy It Already Has | Architecture | Draft | 2026-05-27 |
+| [RDR-135](rdr-135-windowed-aspect-extraction.md) | Windowed Aspect Extraction with Cross-Window Merge: Stop Whole-Paper Single-Shot Extraction from Degrading on Long Inputs | Architecture | Draft | 2026-05-27 |
 
 > **Scrapped 2026-05-19 (RDR-110-119 arc).** Bundled the storage-substrate split with new abstractions (tuplespace, ORB, host-trust, surfaces-as-tuples, UI fabric); scope discipline failed across nine RDRs and 67 stranded beads. Files preserved as tombstones per the "never delete RDR files" rule. Postmortem: [docs/postmortem/2026-05-16-rdr110-113-remediation-chain.md](../postmortem/2026-05-16-rdr110-113-remediation-chain.md). Active substrate work continues as [RDR-120](rdr-120-storage-substrate-split.md) with an explicit moratorium on co-shipped consumers. Numbers RDR-114 through RDR-117 are unused on `main` (drafted on feature branches that never merged).
 

{conexus-5.2.0 → conexus-5.3.0}/mcpb/pyproject.toml

@@ -1,10 +1,10 @@
 [project]
 name = "conexus-mcpb"
-version = "5.2.0"
+version = "5.3.0"
 description = "Conexus packaged as Claude Desktop .mcpb (Desktop Extension)"
 requires-python = ">=3.12"
 dependencies = [
-    "conexus>=5.2.0",
+    "conexus>=5.3.0",
 ]
 
 [tool.uv]

{conexus-5.2.0 → conexus-5.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "conexus"
-version = "5.2.0"
+version = "5.3.0"
 description = "Self-hosted semantic search and knowledge management for LLM-driven development"
 readme = { file = "README.md", content-type = "text/markdown" }
 requires-python = ">=3.12,<3.14"

{conexus-5.2.0 → conexus-5.3.0}/src/nexus/aspect_worker.py

@@ -158,7 +158,7 @@ class AspectExtractionWorker:
         self,
         *,
         poll_interval: float = 2.0,
-        stale_timeout_seconds: int = 300,
+        stale_timeout_seconds: int = 60,
         batch_size: int = _DEFAULT_BATCH_SIZE,
     ) -> None:
         self._poll_interval = poll_interval
@@ -272,10 +272,12 @@ class AspectExtractionWorker:
                 # contending on its single WAL writer lock. This is the
                 # every-2s contention behind the recurring
                 # `aspect_worker_claim_failed` / `database is locked`
-                # incidents (memory: daemon-restart-not-worker-fix). The
-                # work-bounded persist below stays direct (t2_ctx) because
-                # document_aspects.upsert takes an AspectRecord the daemon
-                # wire protocol cannot round-trip.
+                # incidents (memory: daemon-restart-not-worker-fix).
+                # nexus-zir76: the persist path (_process_row /
+                # _process_batch) now routes too, via the daemon-side
+                # `complete_aspect` method (AspectRecord travels as an
+                # asdict() field dict). The worker no longer opens
+                # memory.db on ANY path.
                 def _poll(t2):
                     if do_reclaim:
                         t2.aspect_queue.reclaim_stale(
@@ -316,8 +318,10 @@ class AspectExtractionWorker:
         P5.1 / nexus-8g79.34 — the batch path now mirrors the
         single-doc extractor's read contract).
         """
+        import dataclasses
+
         from nexus.aspect_extractor import select_config
-        from nexus.mcp_infra import t2_ctx
+        from nexus.mcp_infra import t2_index_write
 
         # extract_aspects_batch requires every input to share a single
         # ExtractorConfig. claim_batch grabs FIFO across collections, so
@@ -360,13 +364,14 @@ class AspectExtractionWorker:
                 row_count=len(rows),
                 exc_info=True,
             )
+            # nexus-zir76: route through the daemon, never direct memory.db.
+            def _fail_all(db):  # noqa: ANN001
+                for row in rows:
+                    db.aspect_queue.mark_failed(
+                        row.collection, row.source_path, error=str(exc),
+                    )
             try:
-                with t2_ctx() as t2:
-                    for row in rows:
-                        t2.aspect_queue.mark_failed(
-                            row.collection, row.source_path,
-                            error=str(exc),
-                        )
+                t2_index_write(_fail_all)
             except Exception:
                 _log.warning(
                     "aspect_worker_batch_mark_failed_persist_failed",
@@ -374,45 +379,78 @@ class AspectExtractionWorker:
                 )
             return
 
-        try:
-            with t2_ctx() as t2:
-                for row, record in zip(rows, records):
-                    if record is None:
-                        # Unsupported collection — drop silently.
-                        t2.aspect_queue.mark_done(
-                            row.collection, row.source_path,
-                        )
-                        continue
-                    # nexus-8g79.34: ExtractFail per-row — typed read-
-                    # failure sentinel from URI-based reading. Mark
-                    # queue done so we don't retry an unreadable
-                    # source on every drain; operators re-enqueue
-                    # manually after fixing source identity (mirrors
-                    # _process_row's handling).
-                    if isinstance(record, ExtractFail):
-                        _log.info(
-                            "aspect_worker_batch_extract_skip",
-                            uri=record.uri,
-                            reason=record.reason,
-                            detail=record.detail,
-                        )
-                        t2.aspect_queue.mark_done(
-                            row.collection, row.source_path,
-                        )
-                        continue
-                    t2.document_aspects.upsert(record)
-                    t2.aspect_queue.mark_done(
+        # nexus-zir76: one routed write_fn does the whole batch's persist;
+        # each row clears via the daemon (``complete_aspect`` /
+        # ``mark_done``) instead of a direct memory.db transaction.
+        def _persist_all(db):  # noqa: ANN001
+            for row, record in zip(rows, records):
+                if record is None:
+                    # Unsupported collection — drop silently.
+                    db.aspect_queue.mark_done(
+                        row.collection, row.source_path,
+                    )
+                    continue
+                # nexus-8g79.34: ExtractFail per-row — typed read-failure
+                # sentinel from URI-based reading. Mark queue done so we
+                # don't retry an unreadable source on every drain;
+                # operators re-enqueue manually after fixing source
+                # identity (mirrors _process_row's handling).
+                if isinstance(record, ExtractFail):
+                    _log.info(
+                        "aspect_worker_batch_extract_skip",
+                        uri=record.uri,
+                        reason=record.reason,
+                        detail=record.detail,
+                    )
+                    db.aspect_queue.mark_done(
                         row.collection, row.source_path,
                     )
+                    continue
+                db.complete_aspect(dataclasses.asdict(record))
+        try:
+            t2_index_write(_persist_all)
         except Exception:
             _log.warning(
                 "aspect_worker_batch_persist_failed",
                 exc_info=True,
             )
 
+    def _mark_failed_routed(self, row, error: str) -> None:
+        """Route a queue ``mark_failed`` through the daemon (nexus-zir76).
+
+        The failure path must not open ``memory.db`` directly either: a
+        direct ``mark_failed`` losing the WAL writer race is exactly what
+        orphaned rows ``in_progress`` until the reclaim backstop. If even
+        the routed write raises (daemon down AND the direct fallback
+        contended), ``reclaim_stale`` recovers the row; we log and move on
+        without killing the worker thread.
+        """
+        from nexus.mcp_infra import t2_index_write
+        try:
+            t2_index_write(
+                lambda db: db.aspect_queue.mark_failed(
+                    row.collection, row.source_path, error=error,
+                )
+            )
+        except Exception:
+            _log.warning(
+                "aspect_worker_mark_failed_persist_failed",
+                collection=row.collection,
+                source_path=row.source_path,
+                exc_info=True,
+            )
+
     def _process_row(self, row) -> None:
-        """Run extraction on one queue row and dispatch on the result."""
-        from nexus.mcp_infra import t2_ctx
+        """Run extraction on one queue row and dispatch on the result.
+
+        nexus-zir76: every persist routes through ``t2_index_write`` (the
+        daemon when reachable, a direct fallback when not) so the worker
+        never opens ``memory.db`` directly and cannot contend with the
+        daemon for the single WAL writer lock.
+        """
+        import dataclasses
+
+        from nexus.mcp_infra import t2_index_write
         try:
             # Content was captured at enqueue time when in scope (MCP
             # store_put). For CLI rows where content was not in scope
@@ -451,52 +489,46 @@ class AspectExtractionWorker:
                 source_path=row.source_path,
                 exc_info=True,
             )
-            try:
-                with t2_ctx() as t2:
-                    t2.aspect_queue.mark_failed(
-                        row.collection, row.source_path,
-                        error=str(exc),
-                    )
-            except Exception:
-                _log.warning(
-                    "aspect_worker_mark_failed_persist_failed",
-                    exc_info=True,
-                )
+            self._mark_failed_routed(row, str(exc))
             return
 
         try:
-            with t2_ctx() as t2:
-                if record is None:
-                    # Unsupported collection — drop silently.
-                    t2.aspect_queue.mark_done(
+            if record is None:
+                # Unsupported collection — drop silently.
+                t2_index_write(
+                    lambda db: db.aspect_queue.mark_done(
                         row.collection, row.source_path,
                     )
-                    return
-                # RDR-096 P1.2: ExtractFail is the typed read-failure
-                # sentinel. No row written; mark queue done so we
-                # don't retry the unreadable source on every drain.
-                # Operators can re-enqueue manually after fixing the
-                # source identity.
-                if isinstance(record, ExtractFail):
-                    _log.info(
-                        "aspect_worker_extract_skip",
-                        uri=record.uri,
-                        reason=record.reason,
-                        detail=record.detail,
-                    )
-                    t2.aspect_queue.mark_done(
+                )
+                return
+            # RDR-096 P1.2: ExtractFail is the typed read-failure
+            # sentinel. No row written; mark queue done so we
+            # don't retry the unreadable source on every drain.
+            # Operators can re-enqueue manually after fixing the
+            # source identity.
+            if isinstance(record, ExtractFail):
+                _log.info(
+                    "aspect_worker_extract_skip",
+                    uri=record.uri,
+                    reason=record.reason,
+                    detail=record.detail,
+                )
+                t2_index_write(
+                    lambda db: db.aspect_queue.mark_done(
                         row.collection, row.source_path,
                     )
-                    return
-                # AspectRecord — either a populated record or a null-
-                # fields record from a subprocess-side failure (the
-                # extractor already retried up to 3 attempts
-                # internally for those paths). Persist and remove
-                # from the queue.
-                t2.document_aspects.upsert(record)
-                t2.aspect_queue.mark_done(
-                    row.collection, row.source_path,
                 )
+                return
+            # AspectRecord — either a populated record or a null-fields
+            # record from a subprocess-side failure (the extractor
+            # already retried up to 3 attempts internally for those
+            # paths). nexus-zir76: persist + clear the queue row in one
+            # daemon-routed call (``complete_aspect``) so the worker
+            # never writes memory.db directly. asdict() because the wire
+            # protocol decodes a dataclass arg to its field dict.
+            t2_index_write(
+                lambda db: db.complete_aspect(dataclasses.asdict(record))
+            )
         except Exception as exc:
             _log.warning(
                 "aspect_worker_persist_failed",
@@ -504,17 +536,7 @@ class AspectExtractionWorker:
                 source_path=row.source_path,
                 exc_info=True,
             )
-            try:
-                with t2_ctx() as t2:
-                    t2.aspect_queue.mark_failed(
-                        row.collection, row.source_path,
-                        error=str(exc),
-                    )
-            except Exception:
-                _log.warning(
-                    "aspect_worker_mark_failed_secondary_persist_failed",
-                    exc_info=True,
-                )
+            self._mark_failed_routed(row, str(exc))
 
 
 # ── Module-level singleton ──────────────────────────────────────────────────
@@ -545,18 +567,56 @@ def _worker_lock_path(locks_dir: Path | None = None) -> Path:
     return base / f"aspect_worker.{os.getpid()}"
 
 
+def _sweep_dead_worker_locks(locks_dir: Path) -> None:
+    """Remove ``aspect_worker.<pid>`` lock files whose PID is dead.
+
+    nexus-zir76: ``_remove_worker_lock`` only runs on a clean
+    ``stop_worker``; a ``-9`` or a crash leaks the file. Over many
+    sessions these accumulate unbounded (85 found in the wild on
+    2026-05-27). Sweeping dead-PID locks at worker startup bounds the
+    pileup. Live locks (including this process's own) are left intact;
+    non-PID-shaped files are ignored. Best-effort — never raises.
+    """
+    import os
+
+    if not locks_dir.exists():
+        return
+    own_pid = os.getpid()
+    for lock_file in locks_dir.glob("aspect_worker.*"):
+        try:
+            pid = int(lock_file.name.rsplit(".", 1)[-1])
+        except ValueError:
+            continue  # not a PID-suffixed lock file
+        if pid == own_pid:
+            continue
+        try:
+            os.kill(pid, 0)
+        except ProcessLookupError:
+            try:
+                lock_file.unlink(missing_ok=True)
+                _log.info("aspect_worker_stale_lock_swept", pid=pid)
+            except Exception:
+                pass
+        except PermissionError:
+            # Alive under another user — leave it.
+            continue
+
+
 def _write_worker_lock(locks_dir: Path | None = None) -> None:
     """Write a process-scoped lock file advertising this worker.
 
-    Non-fatal if the locks directory cannot be created or the file cannot
-    be written — the lock is advisory; a missing file merely means
-    ``drain_worker`` from another process will not detect this worker.
+    Sweeps dead-PID lock files first (nexus-zir76) so leaked locks from
+    crashed/killed predecessors do not accumulate. Non-fatal if the locks
+    directory cannot be created or the file cannot be written — the lock
+    is advisory; a missing file merely means ``drain_worker`` from another
+    process will not detect this worker.
     """
     import os
 
     try:
         lock = _worker_lock_path(locks_dir)
         lock.parent.mkdir(parents=True, exist_ok=True)
+        _sweep_dead_worker_locks(lock.parent)
         lock.write_text(str(os.getpid()))
     except Exception:
         _log.warning("aspect_worker_lock_write_failed", exc_info=True)
@@ -576,7 +636,7 @@ def _remove_worker_lock(locks_dir: Path | None = None) -> None:
 def ensure_worker_started(
     *,
     poll_interval: float = 2.0,
-    stale_timeout_seconds: int = 300,
+    stale_timeout_seconds: int = 60,
     _locks_dir: Path | None = None,
 ) -> AspectExtractionWorker:
     """Lazy-start the singleton worker. Returns the worker.

{conexus-5.2.0 → conexus-5.3.0}/src/nexus/commands/memory.py

@@ -24,11 +24,39 @@ def memory() -> None:
 @click.option("--title", "-t", required=True, help="Entry title/filename")
 @click.option("--tags", default="", help="Comma-separated tags")
 @click.option("--ttl", default="30d", show_default=True, help="TTL: Nd, Nw, or permanent")
-def put_cmd(content: str, project: str, title: str, tags: str, ttl: str) -> None:
+@click.option(
+    "--merge",
+    is_flag=True,
+    default=False,
+    help="Canonical-fact merge: fold into an existing high-overlap entry "
+    "(non-destructive) instead of inserting a near-duplicate.",
+)
+@click.option(
+    "--merge-threshold",
+    type=float,
+    default=0.5,
+    show_default=True,
+    help="Word-set Jaccard threshold for --merge.",
+)
+def put_cmd(
+    content: str,
+    project: str,
+    title: str,
+    tags: str,
+    ttl: str,
+    merge: bool,
+    merge_threshold: float,
+) -> None:
     """Write content to the T2 memory bank.
 
     Use '-' as CONTENT to read from stdin.
 
+    With ``--merge`` (bead nexus-lhxz4), the new content is folded into the
+    most word-set-overlapping existing entry in the project when overlap is
+    at or above ``--merge-threshold`` (non-destructive: both texts are kept),
+    instead of inserting a near-duplicate. Without it, the default upsert
+    keyed on (project, title) is unchanged.
+
     RDR-120 P6 follow-up (nexus-w6txl): routes through the T2 daemon
     so host CLI + Cowork-bridged MCP + dev-container CLI all share
     the same arbitrated state. Requires the T2 daemon running; start
@@ -41,10 +69,19 @@ def put_cmd(content: str, project: str, title: str, tags: str, ttl: str) -> None
     except ValueError as exc:
         raise click.ClickException(str(exc)) from exc
     with t2_handle() as db:
-        row_id = db.memory.put(
-            project=project, title=title, content=content, tags=tags, ttl=ttl_days,
-        )
-    click.echo(f"Stored: {project}/{title} (id={row_id})")
+        if merge:
+            row_id, action = db.memory.put_or_merge(
+                project=project, title=title, content=content, tags=tags,
+                ttl=ttl_days, min_similarity=merge_threshold,
+            )
+        else:
+            row_id = db.memory.put(
+                project=project, title=title, content=content, tags=tags,
+                ttl=ttl_days,
+            )
+            action = "inserted"
+    verb = "Merged into" if action == "merged" else "Stored"
+    click.echo(f"{verb}: {project}/{title} (id={row_id})")
 
 
 @memory.command("get")

{conexus-5.2.0 → conexus-5.3.0}/src/nexus/daemon/t2_client.py

@@ -285,6 +285,12 @@ class T2Client:
     def rename_collection_cascade(self, *args: Any, **kwargs: Any) -> Any:
         return self.database.rename_collection_cascade(*args, **kwargs)
 
+    def complete_aspect(self, *args: Any, **kwargs: Any) -> Any:
+        # nexus-zir76: aspect-worker persist (document_aspects.upsert +
+        # aspect_queue.mark_done) folded into one daemon-routable call so
+        # the worker stays off the direct memory.db write path.
+        return self.database.complete_aspect(*args, **kwargs)
+
     def put(self, *args: Any, **kwargs: Any) -> Any:
         # T2Database.put is a thin facade over memory.put; mirror it so a
         # write_fn (or a helper handed the writer, e.g. T1Database.promote)

{conexus-5.2.0 → conexus-5.3.0}/src/nexus/daemon/t2_daemon.py

@@ -433,6 +433,7 @@ _T2_STORE_ATTRS: tuple[str, ...] = (
 _T2_DATABASE_METHODS: tuple[str, ...] = (
     "rename_collection_cascade",
     "expire",
+    "complete_aspect",
     "hello",
 )
 

{conexus-5.2.0 → conexus-5.3.0}/src/nexus/db/t2/__init__.py

@@ -684,6 +684,28 @@ class T2Database:
             session=session,
         )
 
+    def put_or_merge(
+        self,
+        project: str,
+        title: str,
+        content: str,
+        tags: str = "",
+        ttl: int | None = 30,
+        agent: str | None = None,
+        session: str | None = None,
+        min_similarity: float = 0.5,
+    ) -> tuple[int, str]:
+        return self.memory.put_or_merge(
+            project=project,
+            title=title,
+            content=content,
+            tags=tags,
+            ttl=ttl,
+            agent=agent,
+            session=session,
+            min_similarity=min_similarity,
+        )
+
     def get(
         self,
         project: str | None = None,
@@ -961,3 +983,31 @@ class T2Database:
             **extra,
         )
         return len(expired_ids)
+
+    def complete_aspect(self, record_fields: dict[str, Any]) -> bool:
+        """Persist an extracted aspect and clear its queue row in one call.
+
+        nexus-zir76 (RDR-128 follow-up): the aspect worker previously
+        upserted ``document_aspects`` and called ``aspect_queue.mark_done``
+        via two DIRECT ``memory.db`` writes, competing with the daemon for
+        the single WAL writer lock. When the direct ``mark_done`` (or the
+        failure path's ``mark_failed``) lost that race, the row was
+        orphaned ``in_progress`` until the ``reclaim_stale`` backstop.
+        Folding both writes into one daemon-routable method keeps the
+        worker off the direct write path and closes that window.
+
+        *record_fields* is ``dataclasses.asdict(AspectRecord)`` — a plain
+        JSON-shaped dict, because the daemon wire protocol decodes a
+        dataclass argument to its field dict (it does not reconstruct the
+        object). The ``AspectRecord`` is rebuilt here, server-side.
+
+        Returns the ``document_aspects.upsert`` result. ``mark_done`` is
+        idempotent, so a reclaim-driven re-extraction after a crash
+        between the two writes simply re-upserts — no duplicate, no stuck
+        row.
+        """
+        from nexus.db.t2.document_aspects import AspectRecord
+        record = AspectRecord(**record_fields)
+        upserted = self.document_aspects.upsert(record)
+        self.aspect_queue.mark_done(record.collection, record.source_path)
+        return upserted

{conexus-5.2.0 → conexus-5.3.0}/src/nexus/db/t2/memory_store.py

@@ -890,6 +890,92 @@ class MemoryStore:
                     delete_ids,
                 )
 
+    def _content_words(self, text: str) -> set[str]:
+        """Lowercased word set for Jaccard overlap: drop short tokens and
+        stopwords. Shared by write-time merge (``put_or_merge``); mirrors the
+        word-set logic inside ``find_overlapping_memories``."""
+        return {
+            w.lower()
+            for w in text.split()
+            if len(w) > 2 and w.lower() not in self._STOPWORDS
+        }
+
+    def put_or_merge(
+        self,
+        project: str,
+        title: str,
+        content: str,
+        tags: str = "",
+        ttl: int | None = 30,
+        agent: str | None = None,
+        session: str | None = None,
+        min_similarity: float = 0.5,
+    ) -> tuple[int, str]:
+        """Opt-in canonical-fact merge at write time (bead nexus-lhxz4).
+
+        MemForest-inspired (T3 research-memforest-nexus-leverage-2026-05-27,
+        idea #1): instead of accumulating near-duplicate entries that later
+        need a reactive ``memory_consolidate`` pass, fold the new content into
+        the most-overlapping existing entry at write time.
+
+        Returns ``(row_id, action)`` where ``action`` is ``"inserted"`` or
+        ``"merged"``.
+
+        Merge is **non-destructive**: when ``content``'s word set overlaps an
+        existing *different-title* entry in ``project`` at Jaccard
+        ``>= min_similarity``, the new content is appended to that entry under
+        a provenance separator (both texts preserved), its timestamp is
+        refreshed, and ``(existing_id, "merged")`` is returned — the requested
+        ``title`` is not created. Otherwise a normal upsert runs and
+        ``(row_id, "inserted")`` is returned.
+
+        Exact ``(project, title)`` collisions always take the normal upsert
+        path (identity update), never the cross-title merge. Empty content
+        (no word set) always inserts.
+
+        Selection is best-overlap-wins across the project's entries. There is
+        a benign TOCTOU window between the scan and the merge UPDATE (an entry
+        could change concurrently); accepted because the merge is opt-in and
+        non-destructive, mirroring ``merge_memories``' race posture.
+        """
+        new_words = self._content_words(content)
+        if new_words:
+            best_id: int | None = None
+            best_jaccard = 0.0
+            best_content = ""
+            for entry in self.get_all(project):
+                if entry.get("title") == title:
+                    continue  # identity upsert, not a cross-title merge
+                existing_words = self._content_words(entry.get("content", ""))
+                if not existing_words:
+                    continue
+                jaccard = len(new_words & existing_words) / len(
+                    new_words | existing_words
+                )
+                if jaccard > best_jaccard:
+                    best_jaccard = jaccard
+                    best_id = entry["id"]
+                    best_content = entry.get("content", "")
+            if best_id is not None and best_jaccard >= min_similarity:
+                timestamp = datetime.now(UTC).strftime("%Y-%m-%dT%H:%M:%SZ")
+                merged = (
+                    f"{best_content}\n\n"
+                    f"<!-- merged from {title!r} @ {timestamp} "
+                    f"(jaccard={best_jaccard:.2f}) -->\n{content}"
+                )
+                with self._lock, self.conn:
+                    self.conn.execute(
+                        "UPDATE memory SET content = ?, timestamp = ? "
+                        "WHERE id = ?",
+                        (merged, timestamp, best_id),
+                    )
+                return best_id, "merged"
+        row_id = self.put(
+            project, title, content,
+            tags=tags, ttl=ttl, agent=agent, session=session,
+        )
+        return row_id, "inserted"
+
     def flag_stale_memories(
         self,
         project: str,