sessionmemory 0.9.0__tar.gz → 0.11.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (39) hide show
  1. sessionmemory-0.9.0/README.md → sessionmemory-0.11.0/PKG-INFO +60 -19
  2. sessionmemory-0.9.0/PKG-INFO → sessionmemory-0.11.0/README.md +45 -34
  3. {sessionmemory-0.9.0 → sessionmemory-0.11.0}/pyproject.toml +12 -11
  4. {sessionmemory-0.9.0 → sessionmemory-0.11.0}/pyproject.toml.orig +21 -20
  5. {sessionmemory-0.9.0 → sessionmemory-0.11.0}/src/sessionmemory/cli.py +4 -2
  6. {sessionmemory-0.9.0 → sessionmemory-0.11.0}/src/sessionmemory/commands/_common.py +44 -0
  7. {sessionmemory-0.9.0 → sessionmemory-0.11.0}/src/sessionmemory/commands/log.py +18 -4
  8. {sessionmemory-0.9.0 → sessionmemory-0.11.0}/src/sessionmemory/commands/new.py +80 -17
  9. sessionmemory-0.11.0/src/sessionmemory/commands/path.py +42 -0
  10. {sessionmemory-0.9.0 → sessionmemory-0.11.0}/src/sessionmemory/commands/project.py +65 -32
  11. {sessionmemory-0.9.0 → sessionmemory-0.11.0}/src/sessionmemory/commands/reindex.py +4 -3
  12. sessionmemory-0.11.0/src/sessionmemory/commands/search.py +155 -0
  13. {sessionmemory-0.9.0 → sessionmemory-0.11.0}/src/sessionmemory/lib/backlog.py +37 -17
  14. {sessionmemory-0.9.0 → sessionmemory-0.11.0}/src/sessionmemory/lib/bootstrap.py +8 -3
  15. {sessionmemory-0.9.0 → sessionmemory-0.11.0}/src/sessionmemory/lib/config.py +3 -3
  16. {sessionmemory-0.9.0 → sessionmemory-0.11.0}/src/sessionmemory/lib/doctor.py +103 -19
  17. {sessionmemory-0.9.0 → sessionmemory-0.11.0}/src/sessionmemory/lib/embed.py +7 -1
  18. {sessionmemory-0.9.0 → sessionmemory-0.11.0}/src/sessionmemory/lib/field.py +7 -3
  19. {sessionmemory-0.9.0 → sessionmemory-0.11.0}/src/sessionmemory/lib/fieldindex.py +70 -11
  20. {sessionmemory-0.9.0 → sessionmemory-0.11.0}/src/sessionmemory/lib/frontmatter.py +3 -3
  21. {sessionmemory-0.9.0 → sessionmemory-0.11.0}/src/sessionmemory/lib/inject.py +80 -18
  22. {sessionmemory-0.9.0 → sessionmemory-0.11.0}/src/sessionmemory/lib/paths.py +12 -1
  23. {sessionmemory-0.9.0 → sessionmemory-0.11.0}/src/sessionmemory/lib/registry.py +75 -2
  24. sessionmemory-0.11.0/src/sessionmemory/lib/specs.py +402 -0
  25. sessionmemory-0.9.0/src/sessionmemory/commands/search.py +0 -94
  26. {sessionmemory-0.9.0 → sessionmemory-0.11.0}/src/sessionmemory/__init__.py +0 -0
  27. {sessionmemory-0.9.0 → sessionmemory-0.11.0}/src/sessionmemory/commands/__init__.py +0 -0
  28. {sessionmemory-0.9.0 → sessionmemory-0.11.0}/src/sessionmemory/commands/delete.py +0 -0
  29. {sessionmemory-0.9.0 → sessionmemory-0.11.0}/src/sessionmemory/commands/doctor.py +0 -0
  30. {sessionmemory-0.9.0 → sessionmemory-0.11.0}/src/sessionmemory/commands/export.py +0 -0
  31. {sessionmemory-0.9.0 → sessionmemory-0.11.0}/src/sessionmemory/commands/init.py +0 -0
  32. {sessionmemory-0.9.0 → sessionmemory-0.11.0}/src/sessionmemory/commands/inject.py +0 -0
  33. {sessionmemory-0.9.0 → sessionmemory-0.11.0}/src/sessionmemory/lib/__init__.py +0 -0
  34. {sessionmemory-0.9.0 → sessionmemory-0.11.0}/src/sessionmemory/lib/atomic.py +0 -0
  35. {sessionmemory-0.9.0 → sessionmemory-0.11.0}/src/sessionmemory/lib/export.py +0 -0
  36. {sessionmemory-0.9.0 → sessionmemory-0.11.0}/src/sessionmemory/lib/gitinfo.py +0 -0
  37. {sessionmemory-0.9.0 → sessionmemory-0.11.0}/src/sessionmemory/lib/ids.py +0 -0
  38. {sessionmemory-0.9.0 → sessionmemory-0.11.0}/src/sessionmemory/lib/log.py +0 -0
  39. {sessionmemory-0.9.0 → sessionmemory-0.11.0}/src/sessionmemory/lib/resolve.py +0 -0
@@ -1,3 +1,18 @@
1
+ Metadata-Version: 2.3
2
+ Name: sessionmemory
3
+ Version: 0.11.0
4
+ Summary: Durable memory for coding agents, one folder of searchable pages per project.
5
+ Author: Nathaniel Landau
6
+ Author-email: Nathaniel Landau <github@natelandau.com>
7
+ Requires-Dist: fastembed>=0.9.0
8
+ Requires-Dist: nclutils>=4.0.0
9
+ Requires-Dist: pyyaml>=6.0.3
10
+ Requires-Dist: sqlite-vec>=0.1.9
11
+ Requires-Dist: tomli-w>=1.2.0
12
+ Requires-Dist: typer>=0.27.3
13
+ Requires-Python: >=3.13, <3.15
14
+ Description-Content-Type: text/markdown
15
+
1
16
  # sessionmemory
2
17
 
3
18
  Durable memory for coding agents, one folder of searchable pages per project.
@@ -158,6 +173,19 @@ ranks by meaning and not by words in common. A hit has to stand out from the res
158
173
  project's pages, so a query that nothing answers returns no results rather than the
159
174
  nearest pages. Pass `--read` to print every hit in full.
160
175
 
176
+ Specs are searched the same way with `--specs`, which finds a design record by its title,
177
+ summary, and headings:
178
+
179
+ ```bash
180
+ sessionmemory search "queue for rendering PDFs" --specs --cwd .
181
+ ```
182
+
183
+ ```
184
+ ~/repos/my-vault/projects/invoice-api/specs/2026-10-13-render-invoice-pdfs-in-a-worker-pool.md
185
+ Render invoice PDFs in a worker pool
186
+ Rendering a large invoice PDF blocks the request thread. Render in a pool of worker processes instead of a queue.
187
+ ```
188
+
161
189
  ```bash
162
190
  sessionmemory new learning \
163
191
  --title "Stripe retries a webhook for 72 hours, so the handler must be idempotent" \
@@ -166,8 +194,7 @@ sessionmemory new learning \
166
194
  ```
167
195
 
168
196
  ```
169
- ✓ created stripe-retries-a-webhook-for-72-hours-so-the-handler-must-be-idempotent.md
170
- └─ ~/repos/my-vault/projects/invoice-api/learnings/stripe-retries-a-webhook-for-72-hours-so-the-handler-must-be-idempotent.md
197
+ ~/repos/my-vault/projects/invoice-api/learnings/stripe-retries-a-webhook-for-72-hours-so-the-handler-must-be-idempotent.md
171
198
  ```
172
199
 
173
200
  The vault path is shortened to `~` here; the command prints absolute paths.
@@ -179,7 +206,7 @@ and the summary is what a search result shows. Both state the fact and not the t
179
206
  ## What a session sees
180
207
 
181
208
  `sessionmemory inject` prints the block a session starts with. This is the block for a
182
- project holding four learnings, one spec, one plan, one reference doc, and two open
209
+ project holding one learning, three specs, one reference doc, one runbook, and four open
183
210
  backlog items:
184
211
 
185
212
  ```
@@ -189,8 +216,9 @@ Durable memory for this project lives in a vault of markdown pages. Nothing belo
189
216
  loaded for you: the titles are what the vault holds, and each is one `sessionmemory search`
190
217
  away. The project's folder has `learnings/` and `logs/`, searched by meaning, beside
191
218
  `specs/`, `runbooks/`, `reference/`, and `backlog.md`, which are ordinary files you Read
192
- and Edit.
193
- `sessionmemory project --json` prints every path.
219
+ and Edit. `sessionmemory path <kind>` prints one path, where kind is project, learnings,
220
+ logs, specs, runbooks, reference, or backlog; `sessionmemory project --json` prints
221
+ them all for a script.
194
222
 
195
223
  - Before assuming nothing was written down, search: `sessionmemory search "<words>"`
196
224
  prints each hit's path, title, and summary, and `--read` prints every hit's whole
@@ -200,18 +228,27 @@ and Edit.
200
228
  - Past sessions, one page each: `sessionmemory search "<words>" --logs`. Search them
201
229
  for why something was decided, what happened the last time an area changed, or
202
230
  whether a fix was already tried.
203
- - Open work: read `backlog.md`. An item is one line under a `## <kind>` heading
204
- (feat, fix, refactor, perf, docs, test, build, ci), sized S, M, or L:
205
- `- [S] <imperative description> - <YYYY-MM-DD> [#topic]`. Add one with
231
+ - Open work: read `backlog.md`. Any top-level bullet is an open item. Under a
232
+ `## <kind>` heading (feat, fix, refactor, perf, docs, test, build, ci, decide), the
233
+ full shape is sized S, M, or L: `- [S] <imperative description> - <YYYY-MM-DD> [#topic]`.
234
+ Add one with
206
235
  `sessionmemory new backlog --kind <kind> --size <S|M|L> --title "..." --topic <topic> --cwd .`,
207
- which creates the file or heading when missing. Delete a finished line, and one
236
+ which writes that shape and creates the file or heading when missing. Questions
237
+ for the user to answer go under `## decide`. Delete a finished line, and one
208
238
  that will never be done, directly; never tick or annotate it. Git history is the
209
239
  record of what was finished.
210
240
  - Specs: `specs/` holds one design record per feature, named `<date>-<topic>.md`
211
- and kept after the work ships. Before designing or changing a feature, list the
212
- directory and read any spec whose name matches, so a decision already made is not
213
- made again. `sessionmemory new spec --title "..." --cwd .` creates one and prints its
214
- path. Edit it directly after that.
241
+ and kept after the work ships. Before designing or changing a feature, search
242
+ them: `sessionmemory search "<words>" --specs` (listing the directory works too), so a
243
+ decision already made is not made again. `sessionmemory new spec --title "..." --cwd .`
244
+ creates one and prints its path. Open every spec with a short paragraph directly
245
+ under the `# ` title saying what it is for. A search shows the frontmatter
246
+ `summary`, else a goal or purpose section's first paragraph, else that opening one.
247
+ A spec carries a `status`: `draft`, `shipped`, `superseded`, or `abandoned`. Set
248
+ `status: shipped` when its work ships; a spec with no frontmatter block gets one
249
+ holding only `status`. Replace one with
250
+ `sessionmemory new spec --title "..." --supersedes <old filename> --cwd .`, which marks
251
+ the old spec superseded.
215
252
  - Runbooks: `runbooks/` holds step-by-step procedures to follow by hand, such as
216
253
  configuring a service, rotating a credential, or recovering from an outage.
217
254
  Whenever you write one, create it with `sessionmemory new runbook --title "..." --cwd .`,
@@ -222,26 +259,30 @@ and Edit.
222
259
  whose name matches. Keep a doc current by editing it in place. Create one with
223
260
  `sessionmemory new reference --title "..." --cwd .`, which prints its path. Public
224
261
  documentation stays in the repository.
262
+ - The hooks commit the vault. Do not commit it, and do not tell the user vault
263
+ changes are left uncommitted.
225
264
  - Learnings are captured at session end, not by you mid-session. When the user asks
226
- to keep one now: `sessionmemory new learning --title "..." --summary "..." --cwd .`
265
+ you to remember something about this project, or to keep a learning now, never
266
+ use your own memory files: `sessionmemory new learning --title "..." --summary "..." --cwd .`
227
267
  creates the page and prints the path to write prose into. Title and summary state
228
268
  the fact, not the topic. Keep a page under 8KB; more detail is another page.
229
269
 
230
270
  ## What this project knows
231
271
 
232
- - Invoice numbers come from a Postgres sequence, never from max(id) plus one
233
- - pytest-asyncio needs asyncio_mode = auto or every async test is skipped
234
272
  - Stripe retries a webhook for 72 hours, so the handler must be idempotent
235
- - The nightly reconciliation job must start after the 02:00 bank feed
236
273
 
237
274
  ## Reference docs
238
275
 
239
276
  reference/hosting.md
240
277
 
278
+ ## Runbooks
279
+
280
+ runbooks/rotate-the-stripe-webhook-signing-secret.md
281
+
241
282
  ## Open work
242
283
 
243
- 2 open backlog items
244
- 1 spec in specs/
284
+ 4 open backlog items
285
+ 3 specs in specs/
245
286
  ```
246
287
 
247
288
  A page body never enters that block, so its cost grows with the number of pages and not
@@ -1,18 +1,3 @@
1
- Metadata-Version: 2.3
2
- Name: sessionmemory
3
- Version: 0.9.0
4
- Summary: Durable memory for coding agents, one folder of searchable pages per project.
5
- Author: Nathaniel Landau
6
- Author-email: Nathaniel Landau <github@natelandau.com>
7
- Requires-Dist: fastembed>=0.8.1
8
- Requires-Dist: nclutils>=3.4.4
9
- Requires-Dist: pyyaml>=6.0.3
10
- Requires-Dist: sqlite-vec>=0.1.9
11
- Requires-Dist: tomli-w>=1.2.0
12
- Requires-Dist: typer>=0.27.2
13
- Requires-Python: >=3.13, <3.15
14
- Description-Content-Type: text/markdown
15
-
16
1
  # sessionmemory
17
2
 
18
3
  Durable memory for coding agents, one folder of searchable pages per project.
@@ -173,6 +158,19 @@ ranks by meaning and not by words in common. A hit has to stand out from the res
173
158
  project's pages, so a query that nothing answers returns no results rather than the
174
159
  nearest pages. Pass `--read` to print every hit in full.
175
160
 
161
+ Specs are searched the same way with `--specs`, which finds a design record by its title,
162
+ summary, and headings:
163
+
164
+ ```bash
165
+ sessionmemory search "queue for rendering PDFs" --specs --cwd .
166
+ ```
167
+
168
+ ```
169
+ ~/repos/my-vault/projects/invoice-api/specs/2026-10-13-render-invoice-pdfs-in-a-worker-pool.md
170
+ Render invoice PDFs in a worker pool
171
+ Rendering a large invoice PDF blocks the request thread. Render in a pool of worker processes instead of a queue.
172
+ ```
173
+
176
174
  ```bash
177
175
  sessionmemory new learning \
178
176
  --title "Stripe retries a webhook for 72 hours, so the handler must be idempotent" \
@@ -181,8 +179,7 @@ sessionmemory new learning \
181
179
  ```
182
180
 
183
181
  ```
184
- ✓ created stripe-retries-a-webhook-for-72-hours-so-the-handler-must-be-idempotent.md
185
- └─ ~/repos/my-vault/projects/invoice-api/learnings/stripe-retries-a-webhook-for-72-hours-so-the-handler-must-be-idempotent.md
182
+ ~/repos/my-vault/projects/invoice-api/learnings/stripe-retries-a-webhook-for-72-hours-so-the-handler-must-be-idempotent.md
186
183
  ```
187
184
 
188
185
  The vault path is shortened to `~` here; the command prints absolute paths.
@@ -194,7 +191,7 @@ and the summary is what a search result shows. Both state the fact and not the t
194
191
  ## What a session sees
195
192
 
196
193
  `sessionmemory inject` prints the block a session starts with. This is the block for a
197
- project holding four learnings, one spec, one plan, one reference doc, and two open
194
+ project holding one learning, three specs, one reference doc, one runbook, and four open
198
195
  backlog items:
199
196
 
200
197
  ```
@@ -204,8 +201,9 @@ Durable memory for this project lives in a vault of markdown pages. Nothing belo
204
201
  loaded for you: the titles are what the vault holds, and each is one `sessionmemory search`
205
202
  away. The project's folder has `learnings/` and `logs/`, searched by meaning, beside
206
203
  `specs/`, `runbooks/`, `reference/`, and `backlog.md`, which are ordinary files you Read
207
- and Edit.
208
- `sessionmemory project --json` prints every path.
204
+ and Edit. `sessionmemory path <kind>` prints one path, where kind is project, learnings,
205
+ logs, specs, runbooks, reference, or backlog; `sessionmemory project --json` prints
206
+ them all for a script.
209
207
 
210
208
  - Before assuming nothing was written down, search: `sessionmemory search "<words>"`
211
209
  prints each hit's path, title, and summary, and `--read` prints every hit's whole
@@ -215,18 +213,27 @@ and Edit.
215
213
  - Past sessions, one page each: `sessionmemory search "<words>" --logs`. Search them
216
214
  for why something was decided, what happened the last time an area changed, or
217
215
  whether a fix was already tried.
218
- - Open work: read `backlog.md`. An item is one line under a `## <kind>` heading
219
- (feat, fix, refactor, perf, docs, test, build, ci), sized S, M, or L:
220
- `- [S] <imperative description> - <YYYY-MM-DD> [#topic]`. Add one with
216
+ - Open work: read `backlog.md`. Any top-level bullet is an open item. Under a
217
+ `## <kind>` heading (feat, fix, refactor, perf, docs, test, build, ci, decide), the
218
+ full shape is sized S, M, or L: `- [S] <imperative description> - <YYYY-MM-DD> [#topic]`.
219
+ Add one with
221
220
  `sessionmemory new backlog --kind <kind> --size <S|M|L> --title "..." --topic <topic> --cwd .`,
222
- which creates the file or heading when missing. Delete a finished line, and one
221
+ which writes that shape and creates the file or heading when missing. Questions
222
+ for the user to answer go under `## decide`. Delete a finished line, and one
223
223
  that will never be done, directly; never tick or annotate it. Git history is the
224
224
  record of what was finished.
225
225
  - Specs: `specs/` holds one design record per feature, named `<date>-<topic>.md`
226
- and kept after the work ships. Before designing or changing a feature, list the
227
- directory and read any spec whose name matches, so a decision already made is not
228
- made again. `sessionmemory new spec --title "..." --cwd .` creates one and prints its
229
- path. Edit it directly after that.
226
+ and kept after the work ships. Before designing or changing a feature, search
227
+ them: `sessionmemory search "<words>" --specs` (listing the directory works too), so a
228
+ decision already made is not made again. `sessionmemory new spec --title "..." --cwd .`
229
+ creates one and prints its path. Open every spec with a short paragraph directly
230
+ under the `# ` title saying what it is for. A search shows the frontmatter
231
+ `summary`, else a goal or purpose section's first paragraph, else that opening one.
232
+ A spec carries a `status`: `draft`, `shipped`, `superseded`, or `abandoned`. Set
233
+ `status: shipped` when its work ships; a spec with no frontmatter block gets one
234
+ holding only `status`. Replace one with
235
+ `sessionmemory new spec --title "..." --supersedes <old filename> --cwd .`, which marks
236
+ the old spec superseded.
230
237
  - Runbooks: `runbooks/` holds step-by-step procedures to follow by hand, such as
231
238
  configuring a service, rotating a credential, or recovering from an outage.
232
239
  Whenever you write one, create it with `sessionmemory new runbook --title "..." --cwd .`,
@@ -237,26 +244,30 @@ and Edit.
237
244
  whose name matches. Keep a doc current by editing it in place. Create one with
238
245
  `sessionmemory new reference --title "..." --cwd .`, which prints its path. Public
239
246
  documentation stays in the repository.
247
+ - The hooks commit the vault. Do not commit it, and do not tell the user vault
248
+ changes are left uncommitted.
240
249
  - Learnings are captured at session end, not by you mid-session. When the user asks
241
- to keep one now: `sessionmemory new learning --title "..." --summary "..." --cwd .`
250
+ you to remember something about this project, or to keep a learning now, never
251
+ use your own memory files: `sessionmemory new learning --title "..." --summary "..." --cwd .`
242
252
  creates the page and prints the path to write prose into. Title and summary state
243
253
  the fact, not the topic. Keep a page under 8KB; more detail is another page.
244
254
 
245
255
  ## What this project knows
246
256
 
247
- - Invoice numbers come from a Postgres sequence, never from max(id) plus one
248
- - pytest-asyncio needs asyncio_mode = auto or every async test is skipped
249
257
  - Stripe retries a webhook for 72 hours, so the handler must be idempotent
250
- - The nightly reconciliation job must start after the 02:00 bank feed
251
258
 
252
259
  ## Reference docs
253
260
 
254
261
  reference/hosting.md
255
262
 
263
+ ## Runbooks
264
+
265
+ runbooks/rotate-the-stripe-webhook-signing-secret.md
266
+
256
267
  ## Open work
257
268
 
258
- 2 open backlog items
259
- 1 spec in specs/
269
+ 4 open backlog items
270
+ 3 specs in specs/
260
271
  ```
261
272
 
262
273
  A page body never enters that block, so its cost grows with the number of pages and not
@@ -1,17 +1,17 @@
1
1
  [project]
2
2
  dependencies = [
3
- "fastembed>=0.8.1",
4
- "nclutils>=3.4.4",
3
+ "fastembed>=0.9.0",
4
+ "nclutils>=4.0.0",
5
5
  "pyyaml>=6.0.3",
6
6
  "sqlite-vec>=0.1.9",
7
7
  "tomli-w>=1.2.0",
8
- "typer>=0.27.2",
8
+ "typer>=0.27.3",
9
9
  ]
10
10
  description = "Durable memory for coding agents, one folder of searchable pages per project."
11
11
  name = "sessionmemory"
12
12
  readme = "README.md"
13
13
  requires-python = ">=3.13,<3.15"
14
- version = "0.9.0"
14
+ version = "0.11.0"
15
15
 
16
16
  [[project.authors]]
17
17
  name = "Nathaniel Landau"
@@ -22,10 +22,11 @@ sessionmemory = "sessionmemory.cli:main"
22
22
 
23
23
  [dependency-groups]
24
24
  dev = [
25
- "commitizen>=4.19.0",
25
+ "commitizen>=4.19.2",
26
26
  "coverage>=7.16.2",
27
- "duty>=1.10.0",
28
- "prek>=0.5.4",
27
+ "duty>=1.10.1",
28
+ "gate-cache>=0.6.0",
29
+ "prek>=0.5.5",
29
30
  "pytest-clarity>=1.0.1",
30
31
  "pytest-cov>=7.1.0",
31
32
  "pytest-devtools>=1.3.0",
@@ -33,17 +34,17 @@ dev = [
33
34
  "pytest-xdist>=3.8.0",
34
35
  "pytest>=9.1.1",
35
36
  "rich>=15.0.0",
36
- "ruff>=0.16.10",
37
+ "ruff>=0.17.0",
37
38
  "shellcheck-py>=0.11.0.1",
38
- "ty>=0.0.84",
39
+ "ty>=0.0.86",
39
40
  "types-pyyaml>=6.0.12.20260906",
40
- "typos>=1.50.3",
41
+ "typos>=1.51.1",
41
42
  "yamllint>=1.38.0",
42
43
  ]
43
44
 
44
45
  [build-system]
45
46
  build-backend = "uv_build"
46
- requires = ["uv_build>=0.12.5,<0.13.0"]
47
+ requires = ["uv_build>=0.13.0,<0.14"]
47
48
 
48
49
  [tool.commitizen]
49
50
  bump_message = "bump(release): v$current_version → v$new_version"
@@ -1,28 +1,29 @@
1
1
  [project]
2
2
  authors = [{ name = "Nathaniel Landau", email = "github@natelandau.com" }]
3
3
  dependencies = [
4
- "fastembed>=0.8.1",
5
- "nclutils>=3.4.4",
4
+ "fastembed>=0.9.0",
5
+ "nclutils>=4.0.0",
6
6
  "pyyaml>=6.0.3",
7
7
  "sqlite-vec>=0.1.9",
8
8
  "tomli-w>=1.2.0",
9
- "typer>=0.27.2",
9
+ "typer>=0.27.3",
10
10
  ]
11
11
  description = "Durable memory for coding agents, one folder of searchable pages per project."
12
12
  name = "sessionmemory"
13
13
  readme = "README.md"
14
14
  requires-python = ">=3.13,<3.15"
15
- version = "0.9.0"
15
+ version = "0.11.0"
16
16
 
17
17
  [project.scripts]
18
18
  sessionmemory = "sessionmemory.cli:main"
19
19
 
20
20
  [dependency-groups]
21
21
  dev = [
22
- "commitizen>=4.19.0",
22
+ "commitizen>=4.19.2",
23
23
  "coverage>=7.16.2",
24
- "duty>=1.10.0",
25
- "prek>=0.5.4",
24
+ "duty>=1.10.1",
25
+ "gate-cache>=0.6.0",
26
+ "prek>=0.5.5",
26
27
  "pytest-clarity>=1.0.1",
27
28
  "pytest-cov>=7.1.0",
28
29
  "pytest-devtools>=1.3.0",
@@ -30,17 +31,17 @@
30
31
  "pytest-xdist>=3.8.0",
31
32
  "pytest>=9.1.1",
32
33
  "rich>=15.0.0",
33
- "ruff>=0.16.10",
34
+ "ruff>=0.17.0",
34
35
  "shellcheck-py>=0.11.0.1",
35
- "ty>=0.0.84",
36
+ "ty>=0.0.86",
36
37
  "types-pyyaml>=6.0.12.20260906",
37
- "typos>=1.50.3",
38
+ "typos>=1.51.1",
38
39
  "yamllint>=1.38.0",
39
- ]
40
+ ]
40
41
 
41
42
  [build-system]
42
43
  build-backend = "uv_build"
43
- requires = ["uv_build>=0.12.5,<0.13.0"]
44
+ requires = ["uv_build>=0.13.0,<0.14"]
44
45
 
45
46
  [tool.commitizen]
46
47
  bump_message = "bump(release): v$current_version → v$new_version"
@@ -81,15 +82,15 @@
81
82
 
82
83
  [tool.pytest.ini_options]
83
84
 
84
- addopts = "--color=yes --doctest-modules --strict-config --strict-markers -n auto --dist loadfile"
85
- cache_dir = ".cache/pytest"
85
+ addopts = "--color=yes --doctest-modules --strict-config --strict-markers -n auto --dist loadfile"
86
+ cache_dir = ".cache/pytest"
86
87
  cli_runner_patch_result = true
87
- columns = 1000
88
- filterwarnings = ['error', 'ignore:.*Pydantic.*:UserWarning', 'ignore::DeprecationWarning:']
89
- markers = ["serial"]
90
- set_columns = true
91
- testpaths = ["tests"]
92
- xfail_strict = true
88
+ columns = 1000
89
+ filterwarnings = ['error', 'ignore:.*Pydantic.*:UserWarning', 'ignore::DeprecationWarning:']
90
+ markers = ["serial"]
91
+ set_columns = true
92
+ testpaths = ["tests"]
93
+ xfail_strict = true
93
94
 
94
95
  [tool.ruff] # https://github.com/charliermarsh/ruff
95
96
 
@@ -14,12 +14,13 @@ from sessionmemory.commands import init as init_commands
14
14
  from sessionmemory.commands import inject as inject_commands
15
15
  from sessionmemory.commands import log as log_commands
16
16
  from sessionmemory.commands import new as new_commands
17
+ from sessionmemory.commands import path as path_commands
17
18
  from sessionmemory.commands import project
18
19
  from sessionmemory.commands import reindex as reindex_commands
19
20
  from sessionmemory.commands import search as search_commands
20
- from sessionmemory.commands._common import emit_value
21
+ from sessionmemory.commands._common import VersionedGroup, emit_value
21
22
 
22
- app = typer.Typer(no_args_is_help=True, add_completion=False)
23
+ app = typer.Typer(cls=VersionedGroup, no_args_is_help=True, add_completion=False)
23
24
 
24
25
 
25
26
  def _print_version(value: bool) -> None: # noqa: FBT001
@@ -62,6 +63,7 @@ app.command("inject", help="Print what this project's session should start with.
62
63
  app.command("log", help="Record this session's work in one upserted page.")(
63
64
  log_commands.log_command
64
65
  )
66
+ app.command("path", help="Print one of this project's vault paths.")(path_commands.path_command)
65
67
  app.command("project", help="Report this directory's project, or register it.")(
66
68
  project.project_command
67
69
  )
@@ -2,6 +2,7 @@
2
2
 
3
3
  from __future__ import annotations
4
4
 
5
+ import importlib.metadata
5
6
  import json
6
7
  import os
7
8
  import sys
@@ -9,8 +10,13 @@ from pathlib import Path
9
10
  from typing import TYPE_CHECKING, NoReturn
10
11
 
11
12
  import typer
13
+ import typer.core
12
14
  from nclutils import pp
13
15
 
16
+ # Typer vendors Click, so the `click` package's classes never match its errors.
17
+ from typer._click import core as click_core
18
+ from typer._click import exceptions as click_exceptions
19
+
14
20
  from sessionmemory.lib import embed, registry
15
21
  from sessionmemory.lib.bootstrap import is_empty
16
22
  from sessionmemory.lib.config import (
@@ -35,6 +41,44 @@ VAULT_FIX = [
35
41
  ]
36
42
 
37
43
 
44
+ class VersionedGroup(typer.core.TyperGroup):
45
+ """A command group whose unknown-command error names the installed version."""
46
+
47
+ def resolve_command(
48
+ self, ctx: click_core.Context, args: list[str]
49
+ ) -> tuple[str | None, click_core.Command | None, list[str]]:
50
+ """Name the installed version and how to upgrade in an unknown command's error."""
51
+ try:
52
+ return super().resolve_command(ctx, args)
53
+ except click_exceptions.UsageError as error:
54
+ # Typer 0.27 raises a plain UsageError via ctx.fail with no typed signal for a miss.
55
+ if args and self.get_command(ctx, args[0]) is None:
56
+ error.message += f"\n{_unknown_command_hint(error.message)}"
57
+ raise
58
+
59
+
60
+ def _unknown_command_hint(message: str) -> str:
61
+ """Return the lines naming the installed version and how to upgrade.
62
+
63
+ A miss Typer can correct is a typo, so a newer release is only offered as the cause
64
+ when no close match was suggested.
65
+ """
66
+ try:
67
+ version = importlib.metadata.version("sessionmemory")
68
+ except importlib.metadata.PackageNotFoundError:
69
+ version = ""
70
+ suggested = "Did you mean" in message
71
+ if version and suggested:
72
+ cause = f"Installed sessionmemory is {version}.\n"
73
+ elif version:
74
+ cause = f"Installed sessionmemory is {version}; a newer release may have it.\n"
75
+ elif suggested:
76
+ cause = ""
77
+ else:
78
+ cause = "A newer release may have it.\n"
79
+ return f"{cause}Upgrade with: uv tool upgrade sessionmemory"
80
+
81
+
38
82
  def build_embedder() -> Embedder:
39
83
  """Build the embedder commands use: the stub under test, the real model otherwise.
40
84
 
@@ -2,13 +2,14 @@
2
2
 
3
3
  from __future__ import annotations
4
4
 
5
+ import os
5
6
  from pathlib import Path # noqa: TC003
6
7
 
7
8
  import typer
8
- from nclutils import pp
9
9
 
10
10
  from sessionmemory.commands._common import (
11
11
  emit_json,
12
+ emit_value,
12
13
  fail,
13
14
  require_project,
14
15
  require_vault,
@@ -17,15 +18,23 @@ from sessionmemory.commands._common import (
17
18
  from sessionmemory.lib import field, log
18
19
  from sessionmemory.lib.config import now, today
19
20
 
21
+ # The sweep hook sets this name; hooks import nothing from src, so it is defined on both sides.
22
+ LOG_TITLE_ENV = "SESSIONMEMORY_LOG_TITLE"
20
23
  SESSION_ID = typer.Option(..., "--session-id", help="This session's identifier.")
21
- TITLE = typer.Option(..., "--title", help="The log's title.")
24
+ TITLE = typer.Option(
25
+ "", "--title", help=f"The log's title. Required unless {LOG_TITLE_ENV} is set, which wins."
26
+ )
22
27
  SUMMARY = typer.Option("", "--summary", help="One sentence a search result shows.")
23
28
  BODY = typer.Option("", "--body", help="Markdown body. Replaces what is there.")
24
29
  BODY_FILE = typer.Option(None, "--body-file", help="Read the body from a file, or stdin for '-'.")
25
30
  TRANSCRIPT = typer.Option("", "--transcript", help="Path to this session's transcript on disk.")
26
31
  URL = typer.Option("", "--url", help="Where this session can be opened online.")
27
32
  CWD = typer.Option(None, "--cwd", help="Directory to resolve the project from.")
28
- JSON = typer.Option(False, "--json", help="Emit JSON instead of prose.") # noqa: FBT003
33
+ JSON = typer.Option(
34
+ False, # noqa: FBT003
35
+ "--json",
36
+ help="Emit JSON naming the path and whether the page was created or updated.",
37
+ )
29
38
 
30
39
 
31
40
  def log_command( # noqa: PLR0913, PLR0917
@@ -42,9 +51,14 @@ def log_command( # noqa: PLR0913, PLR0917
42
51
  ) -> None:
43
52
  """Record this session's work in the one page that belongs to it.
44
53
 
54
+ Prints only the page's path, as every `new` command does, so a caller can capture it.
55
+
45
56
  Raises:
46
57
  Exit: When the directory is not a registered project or the page cannot be written.
47
58
  """
59
+ title = os.environ.get(LOG_TITLE_ENV, "").strip() or title.strip()
60
+ if not title:
61
+ fail("a log needs --title")
48
62
  body = resolve_body(body, body_file)
49
63
  vault = require_vault()
50
64
  slug = require_project(vault, cwd)
@@ -67,4 +81,4 @@ def log_command( # noqa: PLR0913, PLR0917
67
81
  if as_json:
68
82
  emit_json({"path": str(result.path), "action": action})
69
83
  return
70
- pp.success(f"{action} {result.path.name}", details=[str(result.path)])
84
+ emit_value(str(result.path))