sessionmemory 0.6.0__tar.gz → 0.7.0__tar.gz

{sessionmemory-0.6.0 → sessionmemory-0.7.0}/PKG-INFO

@@ -1,10 +1,10 @@
 Metadata-Version: 2.3
 Name: sessionmemory
-Version: 0.6.0
+Version: 0.7.0
 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 \
@@ -205,14 +202,17 @@ project holding four learnings, one spec, one plan, and two open backlog items:
 Durable memory for this project lives in a vault of markdown pages. Nothing below is
 loaded for you: the titles are what the vault holds, and each is one `sessionmemory search`
 away. The project's folder has `learnings/` and `logs/`, searched by meaning, beside
-`specs/` and `backlog.md`, which are ordinary files you Read and Edit.
+`specs/`, `runbooks/`, and `backlog.md`, which are ordinary files you Read and Edit.
 `sessionmemory project --json` prints every path.
 
   - 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
@@ -225,6 +225,10 @@ away. The project's folder has `learnings/` and `logs/`, searched by meaning, be
     directory and read any spec whose name matches, so a decision already made is not
     made again. `sessionmemory new spec --title "..." --cwd .` creates one and prints its
     path. Edit it directly after that.
+  - Runbooks: `runbooks/` holds step-by-step procedures to follow by hand, such as
+    configuring a service, rotating a credential, or recovering from an outage.
+    Whenever you write one, create it with `sessionmemory new runbook --title "..." --cwd .`,
+    which prints its path, never in another folder or the repository.
   - Learnings are captured at session end, not by you mid-session. When the user asks
     to keep one now: `sessionmemory new learning --title "..." --summary "..." --cwd .`
     creates the page and prints the path to write prose into. Title and summary state

{sessionmemory-0.6.0 → sessionmemory-0.7.0}/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 \
@@ -190,14 +187,17 @@ project holding four learnings, one spec, one plan, and two open backlog items:
 Durable memory for this project lives in a vault of markdown pages. Nothing below is
 loaded for you: the titles are what the vault holds, and each is one `sessionmemory search`
 away. The project's folder has `learnings/` and `logs/`, searched by meaning, beside
-`specs/` and `backlog.md`, which are ordinary files you Read and Edit.
+`specs/`, `runbooks/`, and `backlog.md`, which are ordinary files you Read and Edit.
 `sessionmemory project --json` prints every path.
 
   - 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
@@ -210,6 +210,10 @@ away. The project's folder has `learnings/` and `logs/`, searched by meaning, be
     directory and read any spec whose name matches, so a decision already made is not
     made again. `sessionmemory new spec --title "..." --cwd .` creates one and prints its
     path. Edit it directly after that.
+  - Runbooks: `runbooks/` holds step-by-step procedures to follow by hand, such as
+    configuring a service, rotating a credential, or recovering from an outage.
+    Whenever you write one, create it with `sessionmemory new runbook --title "..." --cwd .`,
+    which prints its path, never in another folder or the repository.
   - Learnings are captured at session end, not by you mid-session. When the user asks
     to keep one now: `sessionmemory new learning --title "..." --summary "..." --cwd .`
     creates the page and prints the path to write prose into. Title and summary state

{sessionmemory-0.6.0 → sessionmemory-0.7.0}/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.6.0"
+version = "0.7.0"
 
 [[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.6.0 → sessionmemory-0.7.0}/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.6.0"
+    version = "0.7.0"
 
     [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.6.0 → sessionmemory-0.7.0}/src/sessionmemory/commands/new.py

@@ -18,7 +18,9 @@ from sessionmemory.commands._common import (
 from sessionmemory.lib import backlog, field, paths
 from sessionmemory.lib.config import now, today
 
-app = typer.Typer(no_args_is_help=True, help="Create a learning, spec, plan, or backlog item.")
+app = typer.Typer(
+    no_args_is_help=True, help="Create a learning, spec, plan, runbook, or backlog item."
+)
 
 # Typer lists an Enum's members in --help and rejects anything else at parse time, so the
 # allowed sets are spelled once, in lib/backlog, and mirrored here as choices.
@@ -112,6 +114,23 @@ def new_plan(
     )
 
 
+@app.command("runbook")
+def new_runbook(
+    title: str = TITLE,
+    body: str = BODY,
+    body_file: Path | None = BODY_FILE,
+    cwd: Path | None = CWD,
+    *,
+    as_json: bool = JSON,
+) -> None:
+    """Create a runbook for this project."""
+    vault = require_vault()
+    slug = require_project(vault, cwd)
+    _new_document(
+        paths.runbooks_dir(vault, slug), title, resolve_body(body, body_file), as_json=as_json
+    )
+
+
 @app.command("backlog", help="Add one open item to this project's backlog.md.")
 def new_backlog(
     kind: Kind = KIND,

{sessionmemory-0.6.0 → sessionmemory-0.7.0}/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.6.0 → sessionmemory-0.7.0}/src/sessionmemory/lib/bootstrap.py

@@ -46,7 +46,7 @@ One folder per project under `projects/`. Inside each:
 
 - `learnings/` is a field: flat markdown pages, embedded and searchable.
 - `logs/` is a second field, one page per session, searched on request.
-- `specs/`, `plans/`, and `backlog.md` are plain files, never indexed.
+- `specs/`, `plans/`, `runbooks/`, and `backlog.md` are plain files, never indexed.
 - `backlog.md` is the list of open items for the project, one line each, sized by
   effort and grouped by commit type.
 

{sessionmemory-0.6.0 → sessionmemory-0.7.0}/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.6.0 → sessionmemory-0.7.0}/src/sessionmemory/lib/inject.py

@@ -68,14 +68,17 @@ GUIDANCE = """## Using this vault
 Durable memory for this project lives in a vault of markdown pages. Nothing below is
 loaded for you: the titles are what the vault holds, and each is one `{command} search`
 away. The project's folder has `learnings/` and `logs/`, searched by meaning, beside
-`specs/` and `backlog.md`, which are ordinary files you Read and Edit.
+`specs/`, `runbooks/`, and `backlog.md`, which are ordinary files you Read and Edit.
 `{command} project --json` prints every path.
 
   - 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
@@ -88,6 +91,10 @@ away. The project's folder has `learnings/` and `logs/`, searched by meaning, be
     directory and read any spec whose name matches, so a decision already made is not
     made again. `{command} new spec --title "..." --cwd .` creates one and prints its
     path. Edit it directly after that.
+  - Runbooks: `runbooks/` holds step-by-step procedures to follow by hand, such as
+    configuring a service, rotating a credential, or recovering from an outage.
+    Whenever you write one, create it with `{command} new runbook --title "..." --cwd .`,
+    which prints its path, never in another folder or the repository.
   - Learnings are captured at session end, not by you mid-session. When the user asks
     to keep one now: `{command} new learning --title "..." --summary "..." --cwd .`
     creates the page and prints the path to write prose into. Title and summary state

{sessionmemory-0.6.0 → sessionmemory-0.7.0}/src/sessionmemory/lib/paths.py

@@ -1,7 +1,8 @@
 """Where a project's files live inside the vault.
 
 `learnings/` and `logs/` are fields: flat directories of pages, each with its own
-index. `specs/`, `plans/`, and `backlog.md` sit beside them and are never indexed. A
+index. `specs/`, `plans/`, `runbooks/`, and `backlog.md` sit beside them and are never
+indexed. A
 project's files are found by its slug and nothing else; there is no global scope.
 """
 
@@ -19,6 +20,7 @@ LEARNINGS_DIR = "learnings"
 LOGS_DIR = "logs"
 SPECS_DIR = "specs"
 PLANS_DIR = "plans"
+RUNBOOKS_DIR = "runbooks"
 BACKLOG_FILE = "backlog.md"
 
 FIELD_DIRS: tuple[str, ...] = (LEARNINGS_DIR, LOGS_DIR)
@@ -49,6 +51,11 @@ def plans_dir(vault: Path, slug: str) -> Path:
     return project_dir(vault, slug) / PLANS_DIR
 
 
+def runbooks_dir(vault: Path, slug: str) -> Path:
+    """Return the project's runbooks folder."""
+    return project_dir(vault, slug) / RUNBOOKS_DIR
+
+
 def backlog_path(vault: Path, slug: str) -> Path:
     """Return the project's backlog checklist file."""
     return project_dir(vault, slug) / BACKLOG_FILE
@@ -65,6 +72,7 @@ def project_paths(vault: Path, slug: str) -> dict[str, str]:
         "logs": str(logs_dir(vault, slug)),
         "specs": str(specs_dir(vault, slug)),
         "plans": str(plans_dir(vault, slug)),
+        "runbooks": str(runbooks_dir(vault, slug)),
         "backlog": str(backlog_path(vault, slug)),
     }