sessionmemory 0.2.0__tar.gz → 0.3.1__tar.gz

{sessionmemory-0.2.0 → sessionmemory-0.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: sessionmemory
-Version: 0.2.0
+Version: 0.3.1
 Summary: Durable memory for coding agents, one folder of searchable pages per project.
 Author: Nathaniel Landau
 Author-email: Nathaniel Landau <github@natelandau.com>
@@ -39,58 +39,79 @@ speaks the format.
 
 ## Requirements
 
-- Python 3.13 or 3.14
-- [uv](https://docs.astral.sh/uv/)
+- [uv](https://docs.astral.sh/uv/). It installs the CLI, and the plugin runs its hooks
+  through it.
+- Python 3.13 or 3.14. `uv` downloads one when none is installed.
 - git. The vault is a git repository, and a project is registered by its git remote.
 - Claude Code, to run the plugin. The CLI works on its own without it.
 
 The first search downloads the `nomic-embed-text-v1.5` embedding model, about 520MB, and
 caches it under `~/.cache/sessionmemory/models`. Nothing else touches the network.
 
-## Install the CLI
+## Install
 
-Clone the repository and install its dependencies. Keep the clone: it is the source the
-plugin installs from, and it is where you pull updates.
+Installation is three steps: the CLI, the plugin, and a vault for them to share.
+
+### 1. Install the CLI
+
+The CLI is published on PyPI. Install it as a tool, which puts `sessionmemory` on your
+`PATH`:
 
 ```bash
-git clone https://github.com/natelandau/sessionmemory ~/repos/sessionmemory
-cd ~/repos/sessionmemory
-uv sync
+uv tool install sessionmemory
 ```
 
-To put a `sessionmemory` command on your `PATH`, install the package as a tool:
+To upgrade it later, run `uv tool upgrade sessionmemory`.
+
+### 2. Install the Claude Code plugin
+
+In Claude Code, add this repository as a marketplace and install the plugin from it:
 
-```bash
-uv tool install .
+```
+/plugin marketplace add natelandau/sessionmemory
+/plugin install sessionmemory@sessionmemory
 ```
 
-Without that step, run the CLI as `uv run sessionmemory` from the clone, or through the
-`bin/sessionmemory` shim, which works from any directory.
+The hooks run the `sessionmemory` from step 1 when its version is at or past the
+plugin's own. Keep the two in step: after `/plugin update sessionmemory@sessionmemory`,
+run `uv tool upgrade sessionmemory` as well. A plugin newer than the tool falls back to
+a copy of the CLI it carries, in a Python environment of its own that the first such
+session builds.
 
-## Create a vault
+### 3. Create a vault
 
 The vault is its own directory. Make it a git repository of its own, so your pages and
-this code do not share a history.
+this code do not share a history. Then initialize it:
 
 ```bash
 mkdir -p ~/repos/my-vault
 cd ~/repos/my-vault
 git init
-export SESSIONMEMORY_VAULT=~/repos/my-vault
-sessionmemory init
+sessionmemory init ~/repos/my-vault
 ```
 
-Put the `export` in your shell profile, and give it an absolute path. Every directory the
-CLI prints is built from that value.
-
 `sessionmemory init` writes the three files a vault needs. A marker in `_system/vault.toml`
 identifies the directory as a vault. A `.gitignore` keeps the derived index out of your
 history. A README explains the layout to whoever opens the vault later. `sessionmemory init`
 never overwrites a file, so you can run it again safely.
 
-Until a directory holds that marker, every command refuses to touch it. The refusal
-protects you. If `SESSIONMEMORY_VAULT` points at your home directory by mistake, the
-first page written scatters a `projects/` tree into it.
+Then tell the CLI and the hooks where the vault is. Both read the same two places, in the
+same order: the `SESSIONMEMORY_VAULT` environment variable, then `vault.root` in
+`~/.claude/sessionmemory.toml`. Record the root in the file, since a session launched
+from a GUI or an IDE does not read your shell profile:
+
+```toml
+[vault]
+root = "~/repos/my-vault"
+```
+
+The variable wins when both are set, so exporting it in one shell points that shell at a
+different vault without touching the file. The
+[plugin documentation](docs/plugin.md#settings) lists every other key that file accepts.
+
+Until a directory holds the marker that `sessionmemory init` writes, every command refuses
+to touch it. The refusal protects you. If the root points at your home directory by
+mistake, the first page written scatters a `projects/` tree into it.
 
 Nothing commits the vault on a timer. The plugin commits it when a session starts and
 again when a session ends, so a page reaches git within the session that wrote it.
@@ -102,8 +123,21 @@ Pushing that history to a remote stays yours to do.
 
 ## Register a project
 
-A project gets memory when its repository is registered. Registration is the only
-decision, and it happens once, from inside the repository:
+A project gets memory when its repository is registered. With the plugin installed, the
+first session you open in a git repository registers it. The session begins with one
+line that names the slug:
+
+```
+This repository was registered with the vault as project 'invoice-api'.
+```
+
+The slug comes from the git remote, or from the directory name when the repository has
+no remote. There is nothing else to choose: no tags, no scope, no note type.
+
+Only a git repository is registered for you. A slug is permanent once pages carry it. A
+session opened in your home directory or a scratch folder must not leave a project named
+after it in the vault. To register a directory outside git, or to choose the slug
+yourself, run the command once:
 
 ```bash
 cd ~/repos/invoice-api
@@ -115,10 +149,9 @@ sessionmemory project --register --cwd .
   └─ root: ~/repos/invoice-api
 ```
 
-`--register` reads the git remote and the repository root, and derives the slug from
-them. There is nothing else to choose: no tags, no scope, no note type. The slug is
-permanent once pages carry it, so an unregistered directory is told to run this command
-rather than registered for you.
+From then on, a session that starts in a registered repository receives that project's
+memory. A session that ends or compacts hands its transcript to a background pass, which
+records what was worth keeping.
 
 ## Search and write pages
 
@@ -161,33 +194,6 @@ The command writes the frontmatter and prints the path. Write the body into that
 or pass it with `--body-file`. The title is what every future session sees at its start,
 and the summary is what a search result shows. Both state the fact and not the topic.
 
-## Install the Claude Code plugin
-
-Add the clone as a marketplace, then install the plugin from it:
-
-```
-/plugin marketplace add ~/repos/sessionmemory
-/plugin install sessionmemory@sessionmemory
-```
-
-The GitHub shorthand `natelandau/sessionmemory` works as a marketplace source too.
-Either way, Claude Code copies the plugin into its own cache and runs the hooks from that
-copy, not from your clone. After you pull changes into the clone, run
-`/plugin update sessionmemory@sessionmemory` to refresh the copy.
-
-A hook does not start from an interactive shell. A session launched from a GUI or an IDE
-cannot see a root exported in `.zshrc`, so record the vault root in
-`~/.claude/sessionmemory.toml` as well:
-
-```toml
-[vault]
-root = "~/repos/my-vault"
-```
-
-From then on, a session that starts in a registered repository receives that project's
-memory. A session that ends or compacts hands its transcript to a background pass, which
-records what was worth keeping.
-
 ## What a session sees
 
 `sessionmemory inject` prints the block a session starts with. This is the block for a
@@ -196,18 +202,27 @@ project holding four learnings, one spec, one plan, and two open backlog items:
 ```
 ## Using this vault
 
-Durable memory for this project lives in a vault of markdown pages. Below is the
-list of what it already knows; each title is one `sessionmemory search` away.
-
-  - A title below matches what you are doing: `sessionmemory search "<words>"` returns
-    the page's path, and you Read it. Search before assuming nothing was written down.
-  - Past sessions: `sessionmemory search "<words>" --logs`. Open work: read `backlog.md`
-    in the project's vault folder (`sessionmemory project --json` prints every path).
-  - Something worth keeping past this session: `sessionmemory new learning --title "..."
-    --summary "..." --cwd .` creates the page and prints the path to write prose into.
-    Keep a page under 8KB; more detail is another page.
-  - Specs and plans: `sessionmemory new spec|plan --title "..." --cwd .` creates the file.
-    Edit `backlog.md`, specs, and plans directly; the CLI only creates pages.
+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/`, `plans/`, 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`.
+  - 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, tick, or
+    delete lines directly. If the file is missing, create it with a `# Backlog` heading.
+  - Specs and plans: `sessionmemory new spec|plan --title "..." --cwd .` creates the file
+    and prints its path. Edit it directly after that.
+  - 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
+    the fact, not the topic. Keep a page under 8KB; more detail is another page.
 
 ## What this project knows
 
@@ -238,6 +253,8 @@ with their length. The titles say what exists. `sessionmemory search` returns wh
 ## Development
 
 ```bash
+git clone https://github.com/natelandau/sessionmemory
+cd sessionmemory
 uv sync                  # install dependencies
 uv run duty lint         # ruff, ty, typos, yamllint, shellcheck, prek
 uv run duty test         # pytest with coverage

{sessionmemory-0.2.0 → sessionmemory-0.3.1}/README.md

@@ -24,58 +24,79 @@ speaks the format.
 
 ## Requirements
 
-- Python 3.13 or 3.14
-- [uv](https://docs.astral.sh/uv/)
+- [uv](https://docs.astral.sh/uv/). It installs the CLI, and the plugin runs its hooks
+  through it.
+- Python 3.13 or 3.14. `uv` downloads one when none is installed.
 - git. The vault is a git repository, and a project is registered by its git remote.
 - Claude Code, to run the plugin. The CLI works on its own without it.
 
 The first search downloads the `nomic-embed-text-v1.5` embedding model, about 520MB, and
 caches it under `~/.cache/sessionmemory/models`. Nothing else touches the network.
 
-## Install the CLI
+## Install
 
-Clone the repository and install its dependencies. Keep the clone: it is the source the
-plugin installs from, and it is where you pull updates.
+Installation is three steps: the CLI, the plugin, and a vault for them to share.
+
+### 1. Install the CLI
+
+The CLI is published on PyPI. Install it as a tool, which puts `sessionmemory` on your
+`PATH`:
 
 ```bash
-git clone https://github.com/natelandau/sessionmemory ~/repos/sessionmemory
-cd ~/repos/sessionmemory
-uv sync
+uv tool install sessionmemory
 ```
 
-To put a `sessionmemory` command on your `PATH`, install the package as a tool:
+To upgrade it later, run `uv tool upgrade sessionmemory`.
+
+### 2. Install the Claude Code plugin
+
+In Claude Code, add this repository as a marketplace and install the plugin from it:
 
-```bash
-uv tool install .
+```
+/plugin marketplace add natelandau/sessionmemory
+/plugin install sessionmemory@sessionmemory
 ```
 
-Without that step, run the CLI as `uv run sessionmemory` from the clone, or through the
-`bin/sessionmemory` shim, which works from any directory.
+The hooks run the `sessionmemory` from step 1 when its version is at or past the
+plugin's own. Keep the two in step: after `/plugin update sessionmemory@sessionmemory`,
+run `uv tool upgrade sessionmemory` as well. A plugin newer than the tool falls back to
+a copy of the CLI it carries, in a Python environment of its own that the first such
+session builds.
 
-## Create a vault
+### 3. Create a vault
 
 The vault is its own directory. Make it a git repository of its own, so your pages and
-this code do not share a history.
+this code do not share a history. Then initialize it:
 
 ```bash
 mkdir -p ~/repos/my-vault
 cd ~/repos/my-vault
 git init
-export SESSIONMEMORY_VAULT=~/repos/my-vault
-sessionmemory init
+sessionmemory init ~/repos/my-vault
 ```
 
-Put the `export` in your shell profile, and give it an absolute path. Every directory the
-CLI prints is built from that value.
-
 `sessionmemory init` writes the three files a vault needs. A marker in `_system/vault.toml`
 identifies the directory as a vault. A `.gitignore` keeps the derived index out of your
 history. A README explains the layout to whoever opens the vault later. `sessionmemory init`
 never overwrites a file, so you can run it again safely.
 
-Until a directory holds that marker, every command refuses to touch it. The refusal
-protects you. If `SESSIONMEMORY_VAULT` points at your home directory by mistake, the
-first page written scatters a `projects/` tree into it.
+Then tell the CLI and the hooks where the vault is. Both read the same two places, in the
+same order: the `SESSIONMEMORY_VAULT` environment variable, then `vault.root` in
+`~/.claude/sessionmemory.toml`. Record the root in the file, since a session launched
+from a GUI or an IDE does not read your shell profile:
+
+```toml
+[vault]
+root = "~/repos/my-vault"
+```
+
+The variable wins when both are set, so exporting it in one shell points that shell at a
+different vault without touching the file. The
+[plugin documentation](docs/plugin.md#settings) lists every other key that file accepts.
+
+Until a directory holds the marker that `sessionmemory init` writes, every command refuses
+to touch it. The refusal protects you. If the root points at your home directory by
+mistake, the first page written scatters a `projects/` tree into it.
 
 Nothing commits the vault on a timer. The plugin commits it when a session starts and
 again when a session ends, so a page reaches git within the session that wrote it.
@@ -87,8 +108,21 @@ Pushing that history to a remote stays yours to do.
 
 ## Register a project
 
-A project gets memory when its repository is registered. Registration is the only
-decision, and it happens once, from inside the repository:
+A project gets memory when its repository is registered. With the plugin installed, the
+first session you open in a git repository registers it. The session begins with one
+line that names the slug:
+
+```
+This repository was registered with the vault as project 'invoice-api'.
+```
+
+The slug comes from the git remote, or from the directory name when the repository has
+no remote. There is nothing else to choose: no tags, no scope, no note type.
+
+Only a git repository is registered for you. A slug is permanent once pages carry it. A
+session opened in your home directory or a scratch folder must not leave a project named
+after it in the vault. To register a directory outside git, or to choose the slug
+yourself, run the command once:
 
 ```bash
 cd ~/repos/invoice-api
@@ -100,10 +134,9 @@ sessionmemory project --register --cwd .
   └─ root: ~/repos/invoice-api
 ```
 
-`--register` reads the git remote and the repository root, and derives the slug from
-them. There is nothing else to choose: no tags, no scope, no note type. The slug is
-permanent once pages carry it, so an unregistered directory is told to run this command
-rather than registered for you.
+From then on, a session that starts in a registered repository receives that project's
+memory. A session that ends or compacts hands its transcript to a background pass, which
+records what was worth keeping.
 
 ## Search and write pages
 
@@ -146,33 +179,6 @@ The command writes the frontmatter and prints the path. Write the body into that
 or pass it with `--body-file`. The title is what every future session sees at its start,
 and the summary is what a search result shows. Both state the fact and not the topic.
 
-## Install the Claude Code plugin
-
-Add the clone as a marketplace, then install the plugin from it:
-
-```
-/plugin marketplace add ~/repos/sessionmemory
-/plugin install sessionmemory@sessionmemory
-```
-
-The GitHub shorthand `natelandau/sessionmemory` works as a marketplace source too.
-Either way, Claude Code copies the plugin into its own cache and runs the hooks from that
-copy, not from your clone. After you pull changes into the clone, run
-`/plugin update sessionmemory@sessionmemory` to refresh the copy.
-
-A hook does not start from an interactive shell. A session launched from a GUI or an IDE
-cannot see a root exported in `.zshrc`, so record the vault root in
-`~/.claude/sessionmemory.toml` as well:
-
-```toml
-[vault]
-root = "~/repos/my-vault"
-```
-
-From then on, a session that starts in a registered repository receives that project's
-memory. A session that ends or compacts hands its transcript to a background pass, which
-records what was worth keeping.
-
 ## What a session sees
 
 `sessionmemory inject` prints the block a session starts with. This is the block for a
@@ -181,18 +187,27 @@ project holding four learnings, one spec, one plan, and two open backlog items:
 ```
 ## Using this vault
 
-Durable memory for this project lives in a vault of markdown pages. Below is the
-list of what it already knows; each title is one `sessionmemory search` away.
-
-  - A title below matches what you are doing: `sessionmemory search "<words>"` returns
-    the page's path, and you Read it. Search before assuming nothing was written down.
-  - Past sessions: `sessionmemory search "<words>" --logs`. Open work: read `backlog.md`
-    in the project's vault folder (`sessionmemory project --json` prints every path).
-  - Something worth keeping past this session: `sessionmemory new learning --title "..."
-    --summary "..." --cwd .` creates the page and prints the path to write prose into.
-    Keep a page under 8KB; more detail is another page.
-  - Specs and plans: `sessionmemory new spec|plan --title "..." --cwd .` creates the file.
-    Edit `backlog.md`, specs, and plans directly; the CLI only creates pages.
+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/`, `plans/`, 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`.
+  - 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, tick, or
+    delete lines directly. If the file is missing, create it with a `# Backlog` heading.
+  - Specs and plans: `sessionmemory new spec|plan --title "..." --cwd .` creates the file
+    and prints its path. Edit it directly after that.
+  - 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
+    the fact, not the topic. Keep a page under 8KB; more detail is another page.
 
 ## What this project knows
 
@@ -223,6 +238,8 @@ with their length. The titles say what exists. `sessionmemory search` returns wh
 ## Development
 
 ```bash
+git clone https://github.com/natelandau/sessionmemory
+cd sessionmemory
 uv sync                  # install dependencies
 uv run duty lint         # ruff, ty, typos, yamllint, shellcheck, prek
 uv run duty test         # pytest with coverage

{sessionmemory-0.2.0 → sessionmemory-0.3.1}/pyproject.toml

@@ -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.2.0"
+version = "0.3.1"
 
 [[project.authors]]
 name = "Nathaniel Landau"
@@ -50,6 +50,7 @@ bump_message = "bump(release): v$current_version → v$new_version"
 changelog_merge_prerelease = true
 tag_format = "v$version"
 update_changelog_on_bump = true
+version_files = [".claude-plugin/plugin.json:version"]
 version_provider = "uv"
 
 [tool.coverage.report]

{sessionmemory-0.2.0 → sessionmemory-0.3.1}/pyproject.toml.orig

@@ -12,7 +12,7 @@
     name = "sessionmemory"
     readme = "README.md"
     requires-python = ">=3.13,<3.15"
-    version = "0.2.0"
+    version = "0.3.1"
 
     [project.scripts]
         sessionmemory = "sessionmemory.cli:main"
@@ -47,6 +47,7 @@
     changelog_merge_prerelease = true
     tag_format                 = "v$version"
     update_changelog_on_bump   = true
+    version_files              = [".claude-plugin/plugin.json:version"]
     version_provider           = "uv"
 
 [tool.coverage.report] # https://coverage.readthedocs.io/en/latest/config.html#report

{sessionmemory-0.2.0 → sessionmemory-0.3.1}/src/sessionmemory/cli.py

@@ -2,6 +2,8 @@
 
 from __future__ import annotations
 
+import importlib.metadata
+
 import typer
 from nclutils import pp
 
@@ -15,15 +17,30 @@ from sessionmemory.commands import new as new_commands
 from sessionmemory.commands import project
 from sessionmemory.commands import reindex as reindex_commands
 from sessionmemory.commands import search as search_commands
+from sessionmemory.commands._common import emit_value
 
 app = typer.Typer(no_args_is_help=True, add_completion=False)
 
 
+def _print_version(value: bool) -> None:  # noqa: FBT001
+    """Print the installed version bare and exit, for a caller that compares it."""
+    if value:
+        emit_value(importlib.metadata.version("sessionmemory"))
+        raise typer.Exit
+
+
 @app.callback()
 def _root(
     verbosity: int = typer.Option(
         0, "-v", "--verbose", count=True, help="Increase output verbosity. Repeat for more."
     ),
+    version: bool = typer.Option(  # noqa: ARG001, FBT001
+        False,  # noqa: FBT003
+        "--version",
+        callback=_print_version,
+        is_eager=True,
+        help="Print the version and exit.",
+    ),
 ) -> None:
     """Manage a project's memory in a vault of markdown pages."""
     pp.configure(verbosity=verbosity)

{sessionmemory-0.2.0 → sessionmemory-0.3.1}/src/sessionmemory/commands/_common.py

@@ -13,7 +13,12 @@ from nclutils import pp
 
 from sessionmemory.lib import embed, registry
 from sessionmemory.lib.bootstrap import is_empty
-from sessionmemory.lib.config import VaultNotConfiguredError, is_initialized, vault_root
+from sessionmemory.lib.config import (
+    CONFIG_FILE,
+    VaultNotConfiguredError,
+    is_initialized,
+    vault_root,
+)
 from sessionmemory.lib.paths import SYSTEM_DIR
 from sessionmemory.lib.resolve import resolve as resolve_project
 
@@ -23,6 +28,13 @@ if TYPE_CHECKING:
 EMBEDDER_ENV_VAR = "SESSIONMEMORY_EMBEDDER"
 
 
+# The two ways to name the vault, offered together whenever neither is set.
+VAULT_FIX = [
+    "export SESSIONMEMORY_VAULT=/path/to/your/vault",
+    f"or set [vault] root in {CONFIG_FILE}",
+]
+
+
 def build_embedder() -> Embedder:
     """Build the embedder commands use: the stub under test, the real model otherwise.
 
@@ -123,7 +135,7 @@ def require_vault() -> Path:
     try:
         vault = vault_root()
     except VaultNotConfiguredError as error:
-        pp.error(str(error), details=["export SESSIONMEMORY_VAULT=/path/to/your/vault"])
+        pp.error(str(error), details=VAULT_FIX)
         raise typer.Exit(1) from error
 
     if not is_initialized(vault):

{sessionmemory-0.2.0 → sessionmemory-0.3.1}/src/sessionmemory/commands/init.py

@@ -9,12 +9,12 @@ from pathlib import Path  # noqa: TC003
 import typer
 from nclutils import pp
 
-from sessionmemory.commands._common import emit_json
+from sessionmemory.commands._common import VAULT_FIX, emit_json
 from sessionmemory.lib.bootstrap import InitResult, NotAVaultError, initialize
 from sessionmemory.lib.config import VaultNotConfiguredError, vault_root
 
 DIRECTORY_ARGUMENT = typer.Argument(
-    None, help="Where to create the vault. Defaults to SESSIONMEMORY_VAULT."
+    None, help="Where to create the vault. Defaults to the configured vault root."
 )
 FORCE_OPTION = typer.Option(
     False,  # noqa: FBT003
@@ -60,12 +60,12 @@ def init(
 
     A vault cannot be created through `require_vault`, since that helper refuses an
     uninitialized directory and this command is what fixes that. When no directory is
-    given, `SESSIONMEMORY_VAULT` is read directly instead.
+    given, the configured root is read directly instead.
 
     Raises:
-        Exit: When no directory is given and the environment variable is unset or names
-            a missing directory, or when the target directory holds unrelated files and
-            `--force` is not given.
+        Exit: When no directory is given and no vault root is configured or the
+            configured one names a missing directory, or when the target directory holds
+            unrelated files and `--force` is not given.
     """
     if directory is not None:
         # Every other reader resolves the vault path, so a relative or symlinked path
@@ -76,7 +76,7 @@ def init(
         try:
             vault = vault_root()
         except VaultNotConfiguredError as error:
-            pp.error(str(error), details=["export SESSIONMEMORY_VAULT=/path/to/your/vault"])
+            pp.error(str(error), details=VAULT_FIX)
             raise typer.Exit(1) from error
 
     try:

{sessionmemory-0.2.0 → sessionmemory-0.3.1}/src/sessionmemory/commands/log.py

@@ -22,16 +22,20 @@ TITLE = typer.Option(..., "--title", help="The log's title.")
 SUMMARY = typer.Option("", "--summary", help="One sentence a search result shows.")
 BODY = typer.Option("", "--body", help="Markdown body. Replaces what is there.")
 BODY_FILE = typer.Option(None, "--body-file", help="Read the body from a file, or stdin for '-'.")
+TRANSCRIPT = typer.Option("", "--transcript", help="Path to this session's transcript on disk.")
+URL = typer.Option("", "--url", help="Where this session can be opened online.")
 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 log_command(
+def log_command(  # noqa: PLR0913, PLR0917
     session_id: str = SESSION_ID,
     title: str = TITLE,
     summary: str = SUMMARY,
     body: str = BODY,
     body_file: Path | None = BODY_FILE,
+    transcript: str = TRANSCRIPT,
+    url: str = URL,
     cwd: Path | None = CWD,
     *,
     as_json: bool = JSON,
@@ -54,6 +58,8 @@ def log_command(
             body=body,
             now=now(),
             today=today(),
+            transcript=transcript,
+            session_url=url,
         )
     except field.PageError as error:
         fail(str(error))

{sessionmemory-0.2.0 → sessionmemory-0.3.1}/src/sessionmemory/commands/project.py

@@ -284,6 +284,12 @@ def _register(
     )
     registry.save(vault, projects)
 
+    # The folder is created here rather than on the first page write because the
+    # plugin's sweep runs inside it, and a project's first sweep is what writes its
+    # first page.
+    for field in paths_lib.FIELD_DIRS:
+        (paths_lib.project_dir(vault, resolved_slug) / field).mkdir(parents=True, exist_ok=True)
+
     # Registering inside another project is legitimate, but an accidental one looks
     # exactly like a deliberate one, so the nesting is reported rather than assumed.
     if enclosing is not None:

{sessionmemory-0.2.0 → sessionmemory-0.3.1}/src/sessionmemory/lib/config.py

@@ -11,6 +11,9 @@ from sessionmemory.lib.paths import SYSTEM_DIR
 
 VAULT_ENV_VAR = "SESSIONMEMORY_VAULT"
 
+# The plugin's settings file, read here only for `[vault] root`.
+CONFIG_FILE = Path("~/.claude/sessionmemory.toml")
+
 VAULT_MARKER = "vault.toml"
 
 
@@ -19,7 +22,11 @@ class VaultNotConfiguredError(RuntimeError):
 
 
 def vault_root() -> Path:
-    """Return the vault directory named by the environment.
+    """Return the vault directory named by the environment or the config file.
+
+    `SESSIONMEMORY_VAULT` wins. When it is unset, `[vault] root` in `CONFIG_FILE` is read
+    instead, so a plugin user who recorded the root there once has the CLI and the hooks
+    agree on where the vault is. The precedence is the hooks' own.
 
     The path is resolved, so every directory the CLI prints is absolute, such as the
     `project_dir` in `sessionmemory project --json`. A relative value would otherwise be
@@ -29,21 +36,52 @@ def vault_root() -> Path:
         Path: The resolved vault directory.
 
     Raises:
-        VaultNotConfiguredError: If the variable is unset or names a missing directory.
+        VaultNotConfiguredError: If neither source names a vault, the config file cannot
+            be parsed, or the named directory is missing.
     """
     raw = os.environ.get(VAULT_ENV_VAR)
+    source = VAULT_ENV_VAR
+    if not raw:
+        raw = _configured_root()
+        source = str(CONFIG_FILE)
     if not raw:
         msg = f"{VAULT_ENV_VAR} is not set. Point it at your vault repository."
         raise VaultNotConfiguredError(msg)
 
     root = Path(raw).expanduser().resolve()
     if not root.is_dir():
-        msg = f"{VAULT_ENV_VAR} is {root}, which does not exist or is not a directory."
+        msg = f"{source} names {root}, which does not exist or is not a directory."
         raise VaultNotConfiguredError(msg)
 
     return root
 
 
+def _configured_root() -> str | None:
+    """Return `[vault] root` from the config file, or None when it names nothing.
+
+    A value that is not a string is treated as absent, as the hooks treat it. An
+    unparsable file raises rather than reading as absent, because a person at a keyboard
+    fixes a named parse error faster than a "not set" message that is not true.
+
+    Raises:
+        VaultNotConfiguredError: If the file exists but cannot be read or parsed.
+    """
+    path = CONFIG_FILE.expanduser()
+    try:
+        data = tomllib.loads(path.read_text(encoding="utf-8"))
+    except FileNotFoundError:
+        return None
+    except (tomllib.TOMLDecodeError, OSError, UnicodeDecodeError) as error:
+        msg = f"{CONFIG_FILE} could not be read: {error}"
+        raise VaultNotConfiguredError(msg) from error
+
+    vault = data.get("vault")
+    if not isinstance(vault, dict):
+        return None
+    root = vault.get("root")
+    return root if isinstance(root, str) and root else None
+
+
 def today() -> str:
     """Return today's date as an ISO string.
 

{sessionmemory-0.2.0 → sessionmemory-0.3.1}/src/sessionmemory/lib/field.py

@@ -15,7 +15,13 @@ from typing import TYPE_CHECKING, Any
 
 from sessionmemory.lib import atomic
 from sessionmemory.lib.frontmatter import FrontmatterError, parse, serialize
-from sessionmemory.lib.ids import id_candidates, slugify
+from sessionmemory.lib.ids import (
+    DATE_PREFIX_WIDTH,
+    MAX_ID_LENGTH,
+    id_candidates,
+    slugify,
+    strip_date,
+)
 
 if TYPE_CHECKING:
     from collections.abc import Mapping
@@ -176,6 +182,28 @@ def new_page(directory: Path, *, title: str, summary: str, body: str, now: str)
 def new_document(
     directory: Path, *, title: str, body: str, now: str, stem: str | None = None
 ) -> Path:
-    """Create a spec, plan, or log: a titled, dated file that is not a memory page."""
+    """Create a spec, plan, or log: a titled, dated file that is not a memory page.
+
+    The filename leads with the creation date unless the caller fixes the stem, so a
+    directory listing reads in the order the documents were written.
+
+    Raises:
+        PageError: If the title yields no slug or no name is free.
+    """
+    if stem is None:
+        stem = dated_stem(title, now[: len("2026-01-01")])
     meta = {"title": title, "created": now, "updated": now}
     return _create(directory, meta, body, stem=stem)
+
+
+def dated_stem(title: str, day: str) -> str:
+    """Return `<day>-<slug>`, with the slug shortened so the whole stem fits the id limit.
+
+    Raises:
+        PageError: If the title yields no slug.
+    """
+    try:
+        slug = slugify(strip_date(title, day), max_length=MAX_ID_LENGTH - DATE_PREFIX_WIDTH)
+    except ValueError as error:
+        raise PageError(str(error)) from error
+    return f"{day}-{slug}"

{sessionmemory-0.2.0 → sessionmemory-0.3.1}/src/sessionmemory/lib/inject.py

@@ -16,6 +16,7 @@ if TYPE_CHECKING:
     from pathlib import Path
 
 OPEN_ITEM = "- [ ]"
+_LEADING_PUNCTUATION = "`'\"([{<*_~"
 
 
 @dataclass(frozen=True)
@@ -29,9 +30,14 @@ class Injection:
     plans: tuple[str, ...]
 
 
+def _sort_key(title: str) -> str:
+    """Order by the first letter or digit, so a title opening with a code span sorts with its word."""
+    return title.lstrip(_LEADING_PUNCTUATION).casefold()
+
+
 def _titles(directory: Path) -> tuple[str, ...]:
     titles = [field.read_page(path).title or path.stem for path in field.iter_pages(directory)]
-    return tuple(sorted(titles, key=str.casefold))
+    return tuple(sorted(titles, key=_sort_key))
 
 
 def _open_backlog(path: Path) -> int:
@@ -57,18 +63,27 @@ def build(vault: Path, slug: str) -> Injection:
 
 GUIDANCE = """## Using this vault
 
-Durable memory for this project lives in a vault of markdown pages. Below is the
-list of what it already knows; each title is one `{command} search` away.
-
-  - A title below matches what you are doing: `{command} search "<words>"` returns
-    the page's path, and you Read it. Search before assuming nothing was written down.
-  - Past sessions: `{command} search "<words>" --logs`. Open work: read `backlog.md`
-    in the project's vault folder (`{command} project --json` prints every path).
-  - Something worth keeping past this session: `{command} new learning --title "..."
-    --summary "..." --cwd .` creates the page and prints the path to write prose into.
-    Keep a page under 8KB; more detail is another page.
-  - Specs and plans: `{command} new spec|plan --title "..." --cwd .` creates the file.
-    Edit `backlog.md`, specs, and plans directly; the CLI only creates pages."""
+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/`, `plans/`, 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`.
+  - 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, tick, or
+    delete lines directly. If the file is missing, create it with a `# Backlog` heading.
+  - Specs and plans: `{command} new spec|plan --title "..." --cwd .` creates the file
+    and prints its path. Edit it directly after that.
+  - 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
+    the fact, not the topic. Keep a page under 8KB; more detail is another page."""
 
 
 def render(injection: Injection, *, command: str = "sessionmemory") -> str:

{sessionmemory-0.2.0 → sessionmemory-0.3.1}/src/sessionmemory/lib/log.py

@@ -7,17 +7,21 @@ searched on request without diluting the learnings field.
 
 from __future__ import annotations
 
+import re
 import uuid
 from dataclasses import dataclass
 from typing import TYPE_CHECKING
 
 from sessionmemory.lib import field, paths
-from sessionmemory.lib.ids import slugify, strip_date
 
 if TYPE_CHECKING:
     from pathlib import Path
 
 SESSION_FIELD = "session_id"
+TRANSCRIPT_FIELD = "transcript"
+URL_FIELD = "session_url"
+
+_ISO_DATE = re.compile(r"(?<!\d)\d{4}-\d{2}-\d{2}(?!\d)")
 
 
 @dataclass(frozen=True)
@@ -36,6 +40,17 @@ def find_session_log(vault: Path, slug: str, session_id: str) -> Path | None:
     return None
 
 
+def log_date(title: str, today: str) -> str:
+    """The day a log is filed under: the first date its title names, else `today`.
+
+    A log records a session, and the sweep titles it for the moment the session began,
+    so a session that runs past midnight is swept on a day its title does not name.
+    Filing it under the title's date keeps the filename from carrying both.
+    """
+    match = _ISO_DATE.search(title)
+    return match.group(0) if match else today
+
+
 def upsert_log(  # noqa: PLR0913
     vault: Path,
     *,
@@ -46,20 +61,30 @@ def upsert_log(  # noqa: PLR0913
     body: str,
     now: str,
     today: str,
+    transcript: str = "",
+    session_url: str = "",
 ) -> Upserted:
-    """Write this session's log, replacing the page it already has rather than adding one."""
+    """Write this session's log, replacing the page it already has rather than adding one.
+
+    `transcript` and `session_url` are written only when given, and an update never
+    clears one the page already carries, since a later sweep of the same session may
+    be handed less than the first one was.
+    """
+    source = {
+        key: value
+        for key, value in ((TRANSCRIPT_FIELD, transcript), (URL_FIELD, session_url))
+        if value
+    }
     existing = find_session_log(vault, slug, session_id)
     if existing is not None:
         page = field.read_page(existing)
         meta = dict(page.meta)
-        meta.update({"title": title, "summary": summary, "updated": now})
+        meta.update({"title": title, "summary": summary, "updated": now, **source})
         field.write_page(existing, meta, body)
         return Upserted(path=existing, created=False)
 
-    try:
-        stem = f"{today}-{slugify(strip_date(title, today))}"
-    except ValueError as error:
-        raise field.PageError(str(error)) from error
+    day = log_date(title, today)
+    stem = field.dated_stem(title, day)
     path = field.claim_filename(paths.logs_dir(vault, slug), title, stem=stem)
     meta = {
         "title": title,
@@ -68,6 +93,7 @@ def upsert_log(  # noqa: PLR0913
         "created": now,
         "updated": now,
         SESSION_FIELD: session_id,
+        **source,
     }
     field.write_page(path, meta, body)
     return Upserted(path=path, created=True)