sessionmemory 0.5.0__tar.gz → 0.6.1__tar.gz

{sessionmemory-0.5.0 → sessionmemory-0.6.1}/PKG-INFO

@@ -1,10 +1,10 @@
 Metadata-Version: 2.3
 Name: sessionmemory
-Version: 0.5.0
+Version: 0.6.1
 Summary: Durable memory for coding agents, one folder of searchable pages per project.
 Author: Nathaniel Landau
 Author-email: Nathaniel Landau <github@natelandau.com>
-Requires-Dist: fastembed>=0.8.0
+Requires-Dist: fastembed>=0.8.1
 Requires-Dist: nclutils>=3.4.4
 Requires-Dist: pyyaml>=6.0.3
 Requires-Dist: sqlite-vec>=0.1.9
@@ -159,22 +159,19 @@ The CLI does two things. It finds pages by meaning, and it creates pages. Readin
 editing a page is a job for your editor or your agent's own tools.
 
 ```bash
-sessionmemory search "why does the same stripe event arrive twice" --limit 2 --cwd .
+sessionmemory search "stripe event delivered twice" --cwd .
 ```
 
 ```
 ~/repos/my-vault/projects/invoice-api/learnings/stripe-retries-a-webhook-for-72-hours-so-the-handler-must-be-idempotent.md
   Stripe retries a webhook for 72 hours, so the handler must be idempotent
   Stripe redelivers an unacknowledged webhook for up to 72 hours, so the handler records the event id and ignores a repeat.
-
-~/repos/my-vault/projects/invoice-api/learnings/the-nightly-reconciliation-job-must-start-after-the-02-00-bank-feed.md
-  The nightly reconciliation job must start after the 02:00 bank feed
-  The bank feed lands at 02:00 UTC; a reconciliation run before it reports every open invoice as unpaid.
 ```
 
 A result is a path, a title, and a summary. A paraphrase finds the page, because search
-ranks by meaning and not by words in common. A query that nothing answers returns no
-results rather than the nearest pages. Pass `--read` to print every hit in full.
+ranks by meaning and not by words in common. A hit has to stand out from the rest of the
+project's pages, so a query that nothing answers returns no results rather than the
+nearest pages. Pass `--read` to print every hit in full.
 
 ```bash
 sessionmemory new learning \
@@ -210,9 +207,12 @@ away. The project's folder has `learnings/` and `logs/`, searched by meaning, be
 
   - Before assuming nothing was written down, search: `sessionmemory search "<words>"`
     prints each hit's path, title, and summary, and `--read` prints every hit's whole
-    page in one call. A paraphrase still matches. No hits means nothing is recorded,
-    not that the query needs loosening.
-  - Past sessions, one page each: `sessionmemory search "<words>" --logs`.
+    page in one call. Search with a few distinctive words, such as names, identifiers,
+    or error text, rather than a sentence. No hits means nothing is recorded, not that
+    the query needs loosening.
+  - Past sessions, one page each: `sessionmemory search "<words>" --logs`. Search them
+    for why something was decided, what happened the last time an area changed, or
+    whether a fix was already tried.
   - Open work: read `backlog.md`. An item is one line under a `## <kind>` heading
     (feat, fix, refactor, perf, docs, test, build, ci), sized S, M, or L:
     `- [S] <imperative description> - <YYYY-MM-DD> [#topic]`. Add one with

{sessionmemory-0.5.0 → sessionmemory-0.6.1}/README.md

@@ -144,22 +144,19 @@ The CLI does two things. It finds pages by meaning, and it creates pages. Readin
 editing a page is a job for your editor or your agent's own tools.
 
 ```bash
-sessionmemory search "why does the same stripe event arrive twice" --limit 2 --cwd .
+sessionmemory search "stripe event delivered twice" --cwd .
 ```
 
 ```
 ~/repos/my-vault/projects/invoice-api/learnings/stripe-retries-a-webhook-for-72-hours-so-the-handler-must-be-idempotent.md
   Stripe retries a webhook for 72 hours, so the handler must be idempotent
   Stripe redelivers an unacknowledged webhook for up to 72 hours, so the handler records the event id and ignores a repeat.
-
-~/repos/my-vault/projects/invoice-api/learnings/the-nightly-reconciliation-job-must-start-after-the-02-00-bank-feed.md
-  The nightly reconciliation job must start after the 02:00 bank feed
-  The bank feed lands at 02:00 UTC; a reconciliation run before it reports every open invoice as unpaid.
 ```
 
 A result is a path, a title, and a summary. A paraphrase finds the page, because search
-ranks by meaning and not by words in common. A query that nothing answers returns no
-results rather than the nearest pages. Pass `--read` to print every hit in full.
+ranks by meaning and not by words in common. A hit has to stand out from the rest of the
+project's pages, so a query that nothing answers returns no results rather than the
+nearest pages. Pass `--read` to print every hit in full.
 
 ```bash
 sessionmemory new learning \
@@ -195,9 +192,12 @@ away. The project's folder has `learnings/` and `logs/`, searched by meaning, be
 
   - Before assuming nothing was written down, search: `sessionmemory search "<words>"`
     prints each hit's path, title, and summary, and `--read` prints every hit's whole
-    page in one call. A paraphrase still matches. No hits means nothing is recorded,
-    not that the query needs loosening.
-  - Past sessions, one page each: `sessionmemory search "<words>" --logs`.
+    page in one call. Search with a few distinctive words, such as names, identifiers,
+    or error text, rather than a sentence. No hits means nothing is recorded, not that
+    the query needs loosening.
+  - Past sessions, one page each: `sessionmemory search "<words>" --logs`. Search them
+    for why something was decided, what happened the last time an area changed, or
+    whether a fix was already tried.
   - Open work: read `backlog.md`. An item is one line under a `## <kind>` heading
     (feat, fix, refactor, perf, docs, test, build, ci), sized S, M, or L:
     `- [S] <imperative description> - <YYYY-MM-DD> [#topic]`. Add one with

{sessionmemory-0.5.0 → sessionmemory-0.6.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 dependencies = [
-    "fastembed>=0.8.0",
+    "fastembed>=0.8.1",
     "nclutils>=3.4.4",
     "pyyaml>=6.0.3",
     "sqlite-vec>=0.1.9",
@@ -11,7 +11,7 @@ description = "Durable memory for coding agents, one folder of searchable pages
 name = "sessionmemory"
 readme = "README.md"
 requires-python = ">=3.13,<3.15"
-version = "0.5.0"
+version = "0.6.1"
 
 [[project.authors]]
 name = "Nathaniel Landau"
@@ -22,22 +22,22 @@ sessionmemory = "sessionmemory.cli:main"
 
 [dependency-groups]
 dev = [
-    "commitizen>=4.18.0",
-    "coverage>=7.16.0",
-    "duty>=1.9.0",
-    "prek>=0.5.2",
+    "commitizen>=4.19.0",
+    "coverage>=7.16.2",
+    "duty>=1.10.0",
+    "prek>=0.5.4",
     "pytest-clarity>=1.0.1",
     "pytest-cov>=7.1.0",
     "pytest-devtools>=1.3.0",
-    "pytest-mock>=3.15.1",
+    "pytest-mock>=3.16.0",
     "pytest-xdist>=3.8.0",
     "pytest>=9.1.1",
     "rich>=15.0.0",
-    "ruff>=0.16.5",
+    "ruff>=0.16.10",
     "shellcheck-py>=0.11.0.1",
-    "ty>=0.0.78",
-    "types-pyyaml>=6.0.12.20260815",
-    "typos>=1.50.1",
+    "ty>=0.0.84",
+    "types-pyyaml>=6.0.12.20260906",
+    "typos>=1.50.3",
     "yamllint>=1.38.0",
 ]
 

{sessionmemory-0.5.0 → sessionmemory-0.6.1}/pyproject.toml.orig

@@ -1,7 +1,7 @@
 [project]
     authors = [{ name = "Nathaniel Landau", email = "github@natelandau.com" }]
     dependencies = [
-        "fastembed>=0.8.0",
+        "fastembed>=0.8.1",
         "nclutils>=3.4.4",
         "pyyaml>=6.0.3",
         "sqlite-vec>=0.1.9",
@@ -12,29 +12,29 @@
     name = "sessionmemory"
     readme = "README.md"
     requires-python = ">=3.13,<3.15"
-    version = "0.5.0"
+    version = "0.6.1"
 
     [project.scripts]
         sessionmemory = "sessionmemory.cli:main"
 
 [dependency-groups]
     dev = [
-        "commitizen>=4.18.0",
-        "coverage>=7.16.0",
-        "duty>=1.9.0",
-        "prek>=0.5.2",
+        "commitizen>=4.19.0",
+        "coverage>=7.16.2",
+        "duty>=1.10.0",
+        "prek>=0.5.4",
         "pytest-clarity>=1.0.1",
         "pytest-cov>=7.1.0",
         "pytest-devtools>=1.3.0",
-        "pytest-mock>=3.15.1",
+        "pytest-mock>=3.16.0",
         "pytest-xdist>=3.8.0",
         "pytest>=9.1.1",
         "rich>=15.0.0",
-        "ruff>=0.16.5",
+        "ruff>=0.16.10",
         "shellcheck-py>=0.11.0.1",
-        "ty>=0.0.78",
-        "types-pyyaml>=6.0.12.20260815",
-        "typos>=1.50.1",
+        "ty>=0.0.84",
+        "types-pyyaml>=6.0.12.20260906",
+        "typos>=1.50.3",
         "yamllint>=1.38.0",
     ]
 

{sessionmemory-0.5.0 → sessionmemory-0.6.1}/src/sessionmemory/commands/search.py

@@ -27,17 +27,25 @@ MAX_DISTANCE = typer.Option(
     max=2.0,
     help="Farthest cosine distance that still counts as a hit.",
 )
+MIN_MARGIN = typer.Option(
+    fieldindex.DEFAULT_MIN_MARGIN,
+    "--min-margin",
+    min=0.0,
+    max=2.0,
+    help="How much nearer than the field's median page a hit must sit. 0 turns this off.",
+)
 READ = typer.Option(False, "--read", help="Print each hit's whole file under its path.")  # noqa: FBT003
 CWD = typer.Option(None, "--cwd", help="Directory to resolve the project from.")
 JSON = typer.Option(False, "--json", help="Emit JSON instead of prose.")  # noqa: FBT003
 
 
-def search_command(
+def search_command(  # noqa: PLR0913
     query: str = QUERY,
     *,
     logs: bool = LOGS,
     limit: int = LIMIT,
     max_distance: float = MAX_DISTANCE,
+    min_margin: float = MIN_MARGIN,
     read: bool = READ,
     cwd: Path | None = CWD,
     as_json: bool = JSON,
@@ -49,7 +57,12 @@ def search_command(
     slug = require_project(vault, cwd)
     directory = paths.logs_dir(vault, slug) if logs else paths.learnings_dir(vault, slug)
     hits = fieldindex.search(
-        directory, build_embedder(), query, limit=limit, max_distance=max_distance
+        directory,
+        build_embedder(),
+        query,
+        limit=limit,
+        max_distance=max_distance,
+        min_margin=min_margin,
     )
 
     if as_json:
@@ -67,9 +80,7 @@ def search_command(
         emit_json(payload)
         return
     if not hits:
-        pp.info(
-            f"no results within distance {max_distance}; raise --max-distance to see farther pages"
-        )
+        pp.info("no results: nothing recorded matches this query")
         return
     # A path, a title, a summary, and a page are all things a caller copies or parses,
     # so nothing here may be styled.

{sessionmemory-0.5.0 → sessionmemory-0.6.1}/src/sessionmemory/lib/fieldindex.py

@@ -14,6 +14,7 @@ import datetime
 import hashlib
 import json
 import sqlite3
+import statistics
 from dataclasses import dataclass
 from typing import TYPE_CHECKING
 
@@ -26,11 +27,22 @@ if TYPE_CHECKING:
 
     from sessionmemory.lib.embed import Embedder
 
-# Measured on a real vault with nomic-embed-text-v1.5: a page that answers the query sits
-# under 0.25, a related neighbor under 0.40, and the nearest page to an unrelated query
-# sits at 0.45 or beyond. It matches the reference implementation's default for the model.
+# The reference implementation's default cutoff for nomic-embed-text-v1.5. On its own it
+# admits most unrelated queries, so it is only a ceiling and the margin below decides.
 DEFAULT_MAX_DISTANCE = 0.45
 
+# Measured with nomic-embed-text-v1.5 on 120 labeled queries across four projects' learnings
+# and logs: a page that answers the query sits at least this much nearer than the field's
+# median page, and the nearest page to an unrelated query does not. The rule is relative
+# because phrasing a query as a question lowers every distance at once, and because a log,
+# which summarizes a whole session, sits near every query about its project.
+DEFAULT_MIN_MARGIN = 0.11
+
+# A median over fewer pages than this is noise, so a small field measures against the
+# median background seen across the labeled queries instead.
+MIN_BACKGROUND_PAGES = 8
+FALLBACK_BACKGROUND = 0.49
+
 _SCHEMA = """
 CREATE TABLE IF NOT EXISTS pages (
     filename      TEXT PRIMARY KEY,
@@ -165,11 +177,14 @@ def search(
     *,
     limit: int,
     max_distance: float = DEFAULT_MAX_DISTANCE,
+    min_margin: float = DEFAULT_MIN_MARGIN,
 ) -> list[Hit]:
-    """Return the pages within `max_distance` of `query`, nearest first, refreshing the index first.
+    """Return the pages that stand out as nearest to `query`, nearest first, refreshing the index first.
 
-    A cutoff rather than a bare top-k, so a query nothing answers returns nothing instead
-    of the nearest pages dressed up as hits.
+    A hit sits within `max_distance` and at least `min_margin` nearer than the field's
+    median page. A cutoff rather than a bare top-k, so a query nothing answers returns
+    nothing instead of the nearest pages dressed up as hits. A `min_margin` of 0 leaves
+    only the absolute cutoff.
     """
     if not field_dir.is_dir():
         return []
@@ -177,16 +192,25 @@ def search(
     try:
         _refresh(conn, field_dir, embedder)
         rows = conn.execute(
-            "SELECT * FROM ("
-            " SELECT filename, frontmatter, vec_distance_cosine(embedding, ?) AS distance"
-            " FROM pages)"
-            " WHERE distance <= ? ORDER BY distance LIMIT ?",
-            (sqlite_vec.serialize_float32(embedder.encode_query(query)), max_distance, limit),
+            "SELECT filename, frontmatter, vec_distance_cosine(embedding, ?) AS distance"
+            " FROM pages ORDER BY distance",
+            (sqlite_vec.serialize_float32(embedder.encode_query(query)),),
         ).fetchall()
     finally:
         conn.close()
+    ceiling = max_distance
+    if min_margin > 0:
+        distances = [float(row["distance"]) for row in rows]
+        background = (
+            statistics.median(distances)
+            if len(distances) >= MIN_BACKGROUND_PAGES
+            else FALLBACK_BACKGROUND
+        )
+        ceiling = min(ceiling, background - min_margin)
     hits = []
     for row in rows:
+        if float(row["distance"]) > ceiling or len(hits) == limit:
+            break
         meta = json.loads(row["frontmatter"])
         title = meta.get("title")
         summary = meta.get("summary")

{sessionmemory-0.5.0 → sessionmemory-0.6.1}/src/sessionmemory/lib/inject.py

@@ -73,9 +73,12 @@ away. The project's folder has `learnings/` and `logs/`, searched by meaning, be
 
   - Before assuming nothing was written down, search: `{command} search "<words>"`
     prints each hit's path, title, and summary, and `--read` prints every hit's whole
-    page in one call. A paraphrase still matches. No hits means nothing is recorded,
-    not that the query needs loosening.
-  - Past sessions, one page each: `{command} search "<words>" --logs`.
+    page in one call. Search with a few distinctive words, such as names, identifiers,
+    or error text, rather than a sentence. No hits means nothing is recorded, not that
+    the query needs loosening.
+  - Past sessions, one page each: `{command} search "<words>" --logs`. Search them
+    for why something was decided, what happened the last time an area changed, or
+    whether a fix was already tried.
   - Open work: read `backlog.md`. An item is one line under a `## <kind>` heading
     (feat, fix, refactor, perf, docs, test, build, ci), sized S, M, or L:
     `- [S] <imperative description> - <YYYY-MM-DD> [#topic]`. Add one with