sessionmemory 0.20.0__tar.gz → 0.21.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 (52) hide show
  1. {sessionmemory-0.20.0 → sessionmemory-0.21.0}/PKG-INFO +28 -1
  2. {sessionmemory-0.20.0 → sessionmemory-0.21.0}/README.md +27 -0
  3. {sessionmemory-0.20.0 → sessionmemory-0.21.0}/pyproject.toml +6 -11
  4. {sessionmemory-0.20.0 → sessionmemory-0.21.0}/pyproject.toml.orig +7 -7
  5. {sessionmemory-0.20.0 → sessionmemory-0.21.0}/src/sessionmemory/cli.py +49 -7
  6. {sessionmemory-0.20.0 → sessionmemory-0.21.0}/src/sessionmemory/commands/doctor.py +2 -0
  7. {sessionmemory-0.20.0 → sessionmemory-0.21.0}/src/sessionmemory/commands/reconcile.py +4 -3
  8. {sessionmemory-0.20.0 → sessionmemory-0.21.0}/src/sessionmemory/commands/reindex.py +28 -1
  9. {sessionmemory-0.20.0 → sessionmemory-0.21.0}/src/sessionmemory/commands/search.py +5 -32
  10. sessionmemory-0.21.0/src/sessionmemory/lib/agent_skill.md +212 -0
  11. sessionmemory-0.21.0/src/sessionmemory/lib/agentguide.py +29 -0
  12. {sessionmemory-0.20.0 → sessionmemory-0.21.0}/src/sessionmemory/lib/commits.py +91 -27
  13. {sessionmemory-0.20.0 → sessionmemory-0.21.0}/src/sessionmemory/lib/doctor.py +20 -3
  14. {sessionmemory-0.20.0 → sessionmemory-0.21.0}/src/sessionmemory/lib/fieldindex.py +181 -71
  15. {sessionmemory-0.20.0 → sessionmemory-0.21.0}/src/sessionmemory/lib/reconcile.py +65 -27
  16. {sessionmemory-0.20.0 → sessionmemory-0.21.0}/src/sessionmemory/__init__.py +0 -0
  17. {sessionmemory-0.20.0 → sessionmemory-0.21.0}/src/sessionmemory/commands/__init__.py +0 -0
  18. {sessionmemory-0.20.0 → sessionmemory-0.21.0}/src/sessionmemory/commands/_common.py +0 -0
  19. {sessionmemory-0.20.0 → sessionmemory-0.21.0}/src/sessionmemory/commands/delete.py +0 -0
  20. {sessionmemory-0.20.0 → sessionmemory-0.21.0}/src/sessionmemory/commands/export.py +0 -0
  21. {sessionmemory-0.20.0 → sessionmemory-0.21.0}/src/sessionmemory/commands/init.py +0 -0
  22. {sessionmemory-0.20.0 → sessionmemory-0.21.0}/src/sessionmemory/commands/inject.py +0 -0
  23. {sessionmemory-0.20.0 → sessionmemory-0.21.0}/src/sessionmemory/commands/local.py +0 -0
  24. {sessionmemory-0.20.0 → sessionmemory-0.21.0}/src/sessionmemory/commands/log.py +0 -0
  25. {sessionmemory-0.20.0 → sessionmemory-0.21.0}/src/sessionmemory/commands/new.py +0 -0
  26. {sessionmemory-0.20.0 → sessionmemory-0.21.0}/src/sessionmemory/commands/path.py +0 -0
  27. {sessionmemory-0.20.0 → sessionmemory-0.21.0}/src/sessionmemory/commands/project.py +0 -0
  28. {sessionmemory-0.20.0 → sessionmemory-0.21.0}/src/sessionmemory/entry.py +0 -0
  29. {sessionmemory-0.20.0 → sessionmemory-0.21.0}/src/sessionmemory/lib/__init__.py +0 -0
  30. {sessionmemory-0.20.0 → sessionmemory-0.21.0}/src/sessionmemory/lib/atomic.py +0 -0
  31. {sessionmemory-0.20.0 → sessionmemory-0.21.0}/src/sessionmemory/lib/backlog.py +0 -0
  32. {sessionmemory-0.20.0 → sessionmemory-0.21.0}/src/sessionmemory/lib/bootstrap.py +0 -0
  33. {sessionmemory-0.20.0 → sessionmemory-0.21.0}/src/sessionmemory/lib/changes.py +0 -0
  34. {sessionmemory-0.20.0 → sessionmemory-0.21.0}/src/sessionmemory/lib/config.py +0 -0
  35. {sessionmemory-0.20.0 → sessionmemory-0.21.0}/src/sessionmemory/lib/embed.py +0 -0
  36. {sessionmemory-0.20.0 → sessionmemory-0.21.0}/src/sessionmemory/lib/export.py +0 -0
  37. {sessionmemory-0.20.0 → sessionmemory-0.21.0}/src/sessionmemory/lib/field.py +0 -0
  38. {sessionmemory-0.20.0 → sessionmemory-0.21.0}/src/sessionmemory/lib/frontmatter.py +0 -0
  39. {sessionmemory-0.20.0 → sessionmemory-0.21.0}/src/sessionmemory/lib/gitinfo.py +0 -0
  40. {sessionmemory-0.20.0 → sessionmemory-0.21.0}/src/sessionmemory/lib/ids.py +0 -0
  41. {sessionmemory-0.20.0 → sessionmemory-0.21.0}/src/sessionmemory/lib/inject.py +0 -0
  42. {sessionmemory-0.20.0 → sessionmemory-0.21.0}/src/sessionmemory/lib/localdeclined.py +0 -0
  43. {sessionmemory-0.20.0 → sessionmemory-0.21.0}/src/sessionmemory/lib/localmanifest.py +0 -0
  44. {sessionmemory-0.20.0 → sessionmemory-0.21.0}/src/sessionmemory/lib/localmd.py +0 -0
  45. {sessionmemory-0.20.0 → sessionmemory-0.21.0}/src/sessionmemory/lib/localtree.py +0 -0
  46. {sessionmemory-0.20.0 → sessionmemory-0.21.0}/src/sessionmemory/lib/log.py +0 -0
  47. {sessionmemory-0.20.0 → sessionmemory-0.21.0}/src/sessionmemory/lib/paths.py +0 -0
  48. {sessionmemory-0.20.0 → sessionmemory-0.21.0}/src/sessionmemory/lib/registration.py +0 -0
  49. {sessionmemory-0.20.0 → sessionmemory-0.21.0}/src/sessionmemory/lib/registry.py +0 -0
  50. {sessionmemory-0.20.0 → sessionmemory-0.21.0}/src/sessionmemory/lib/resolve.py +0 -0
  51. {sessionmemory-0.20.0 → sessionmemory-0.21.0}/src/sessionmemory/lib/settingsdiff.py +0 -0
  52. {sessionmemory-0.20.0 → sessionmemory-0.21.0}/src/sessionmemory/lib/specs.py +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.3
2
2
  Name: sessionmemory
3
- Version: 0.20.0
3
+ Version: 0.21.0
4
4
  Summary: Durable memory for coding agents, one folder of searchable pages per project.
5
5
  Author: Nathaniel Landau
6
6
  Author-email: Nathaniel Landau <github@natelandau.com>
@@ -335,6 +335,33 @@ to the same block, so that each session reads the guidance itself:
335
335
  `sessionmemory inject --cwd .` and follow the guidance it prints.
336
336
  ```
337
337
 
338
+ ## Get an agent's help with the vault
339
+
340
+ An AI agent can do the upkeep of the vault for you: fix what `sessionmemory doctor`
341
+ reports, clean up projects whose repository is gone, and keep the private files in step
342
+ with each checkout. To start, print a prompt and paste it into the agent:
343
+
344
+ ```bash
345
+ sessionmemory --prompt
346
+ ```
347
+
348
+ ```
349
+ Help me manage my sessionmemory vault.
350
+
351
+ 1. Run `sessionmemory --skill` and read all of it. It explains how the vault works and how to manage it.
352
+ 2. Run `sessionmemory doctor --json`.
353
+ 3. Give me a brief overview of the vault's state: its projects, and what doctor found in each.
354
+ 4. Ask me what I want help with, and offer a few suggestions based on what you found.
355
+
356
+ Ask me before you delete, move, or overwrite anything.
357
+ ```
358
+
359
+ `sessionmemory --skill` prints the guide that the agent reads. It explains the layout of
360
+ the vault, the registry, the commands, the fix for each `doctor` finding, and the rules
361
+ the agent obeys. One rule is that the agent asks you before it deletes, moves, or
362
+ overwrites a file. The guide covers the whole vault. If the agent starts in a registered
363
+ project, it asks whether to work on that project or on the whole vault.
364
+
338
365
  ## Documentation
339
366
 
340
367
  | Page | What it covers |
@@ -320,6 +320,33 @@ to the same block, so that each session reads the guidance itself:
320
320
  `sessionmemory inject --cwd .` and follow the guidance it prints.
321
321
  ```
322
322
 
323
+ ## Get an agent's help with the vault
324
+
325
+ An AI agent can do the upkeep of the vault for you: fix what `sessionmemory doctor`
326
+ reports, clean up projects whose repository is gone, and keep the private files in step
327
+ with each checkout. To start, print a prompt and paste it into the agent:
328
+
329
+ ```bash
330
+ sessionmemory --prompt
331
+ ```
332
+
333
+ ```
334
+ Help me manage my sessionmemory vault.
335
+
336
+ 1. Run `sessionmemory --skill` and read all of it. It explains how the vault works and how to manage it.
337
+ 2. Run `sessionmemory doctor --json`.
338
+ 3. Give me a brief overview of the vault's state: its projects, and what doctor found in each.
339
+ 4. Ask me what I want help with, and offer a few suggestions based on what you found.
340
+
341
+ Ask me before you delete, move, or overwrite anything.
342
+ ```
343
+
344
+ `sessionmemory --skill` prints the guide that the agent reads. It explains the layout of
345
+ the vault, the registry, the commands, the fix for each `doctor` finding, and the rules
346
+ the agent obeys. One rule is that the agent asks you before it deletes, moves, or
347
+ overwrites a file. The guide covers the whole vault. If the agent starts in a registered
348
+ project, it asks whether to work on that project or on the whole vault.
349
+
323
350
  ## Documentation
324
351
 
325
352
  | Page | What it covers |
@@ -11,7 +11,7 @@ description = "Durable memory for coding agents, one folder of searchable pages
11
11
  name = "sessionmemory"
12
12
  readme = "README.md"
13
13
  requires-python = ">=3.13,<3.15"
14
- version = "0.20.0"
14
+ version = "0.21.0"
15
15
 
16
16
  [[project.authors]]
17
17
  name = "Nathaniel Landau"
@@ -25,7 +25,7 @@ dev = [
25
25
  "commitizen>=4.19.3",
26
26
  "coverage>=7.17.3",
27
27
  "duty>=1.10.1",
28
- "gate-cache>=0.8.0",
28
+ "gate-cache>=0.9.0",
29
29
  "prek>=0.5.11",
30
30
  "pytest-clarity>=1.0.1",
31
31
  "pytest-cov>=7.1.0",
@@ -61,7 +61,7 @@ exclude_lines = [
61
61
  "if TYPE_CHECKING",
62
62
  "pragma: no cover",
63
63
  ]
64
- fail_under = 95
64
+ fail_under = 90
65
65
  show_missing = true
66
66
  skip_covered = true
67
67
  skip_empty = true
@@ -85,19 +85,14 @@ source = [
85
85
  output = ".cache/coverage.xml"
86
86
 
87
87
  [tool.pytest.ini_options]
88
- addopts = "--color=yes --doctest-modules --strict-config --strict-markers -n auto --dist loadfile"
88
+ addopts = "--color=yes -n auto --dist worksteal"
89
89
  cache_dir = ".cache/pytest"
90
90
  cli_runner_patch_result = true
91
91
  columns = 1000
92
- filterwarnings = [
93
- "error",
94
- "ignore:.*Pydantic.*:UserWarning",
95
- "ignore::DeprecationWarning:",
96
- ]
97
- markers = ["serial"]
92
+ filterwarnings = ["error"]
98
93
  set_columns = true
94
+ strict = true
99
95
  testpaths = ["tests"]
100
- xfail_strict = true
101
96
 
102
97
  [tool.ruff]
103
98
  exclude = [
@@ -12,7 +12,7 @@
12
12
  name = "sessionmemory"
13
13
  readme = "README.md"
14
14
  requires-python = ">=3.13,<3.15"
15
- version = "0.20.0"
15
+ version = "0.21.0"
16
16
 
17
17
  [project.scripts]
18
18
  sessionmemory = "sessionmemory.entry:main"
@@ -22,7 +22,7 @@
22
22
  "commitizen>=4.19.3",
23
23
  "coverage>=7.17.3",
24
24
  "duty>=1.10.1",
25
- "gate-cache>=0.8.0",
25
+ "gate-cache>=0.9.0",
26
26
  "prek>=0.5.11",
27
27
  "pytest-clarity>=1.0.1",
28
28
  "pytest-cov>=7.1.0",
@@ -58,7 +58,7 @@
58
58
  'if TYPE_CHECKING',
59
59
  'pragma: no cover',
60
60
  ]
61
- fail_under = 95
61
+ fail_under = 90
62
62
  show_missing = true
63
63
  skip_covered = true
64
64
  skip_empty = true
@@ -82,15 +82,15 @@
82
82
 
83
83
  [tool.pytest.ini_options]
84
84
 
85
- addopts = "--color=yes --doctest-modules --strict-config --strict-markers -n auto --dist loadfile"
85
+ # worksteal rebalances the tail, so one slow file never pins the run to one worker
86
+ addopts = "--color=yes -n auto --dist worksteal"
86
87
  cache_dir = ".cache/pytest"
87
88
  cli_runner_patch_result = true
88
89
  columns = 1000
89
- filterwarnings = ['error', 'ignore:.*Pydantic.*:UserWarning', 'ignore::DeprecationWarning:']
90
- markers = ["serial"]
90
+ filterwarnings = ["error"]
91
91
  set_columns = true
92
+ strict = true
92
93
  testpaths = ["tests"]
93
- xfail_strict = true
94
94
 
95
95
  [tool.ruff] # https://github.com/charliermarsh/ruff
96
96
 
@@ -2,6 +2,8 @@
2
2
 
3
3
  from __future__ import annotations
4
4
 
5
+ from typing import TYPE_CHECKING
6
+
5
7
  import typer
6
8
 
7
9
  from sessionmemory.commands import delete as delete_commands
@@ -19,6 +21,9 @@ from sessionmemory.commands import reindex as reindex_commands
19
21
  from sessionmemory.commands import search as search_commands
20
22
  from sessionmemory.commands._common import VersionedGroup, emit_value
21
23
 
24
+ if TYPE_CHECKING:
25
+ from collections.abc import Callable
26
+
22
27
  app = typer.Typer(
23
28
  cls=VersionedGroup,
24
29
  no_args_is_help=True,
@@ -33,13 +38,36 @@ MAINTENANCE = "Maintenance"
33
38
  PLUGIN = "Plugin internals"
34
39
 
35
40
 
36
- def _print_version(value: bool) -> None: # noqa: FBT001
37
- """Print the installed version bare and exit, for a caller that compares it."""
38
- if value:
39
- import importlib.metadata
41
+ def _version() -> str:
42
+ import importlib.metadata
43
+
44
+ return importlib.metadata.version("sessionmemory")
45
+
46
+
47
+ def _agent_skill() -> str:
48
+ from sessionmemory.lib import agentguide
49
+
50
+ return agentguide.skill()
51
+
52
+
53
+ def _agent_prompt() -> str:
54
+ from sessionmemory.lib import agentguide
55
+
56
+ return agentguide.PROMPT
57
+
40
58
 
41
- emit_value(importlib.metadata.version("sessionmemory"))
42
- raise typer.Exit
59
+ def _print_and_exit(text: Callable[[], str]) -> Callable[[bool], None]:
60
+ """Build an eager root option's callback that prints one bare value and exits.
61
+
62
+ The value is computed only when the flag is given, so an unused flag costs no import.
63
+ """
64
+
65
+ def callback(value: bool) -> None: # noqa: FBT001
66
+ if value:
67
+ emit_value(text())
68
+ raise typer.Exit
69
+
70
+ return callback
43
71
 
44
72
 
45
73
  @app.callback()
@@ -47,10 +75,24 @@ def _root(
47
75
  version: bool = typer.Option( # noqa: FBT001
48
76
  False, # noqa: FBT003
49
77
  "--version",
50
- callback=_print_version,
78
+ callback=_print_and_exit(_version),
51
79
  is_eager=True,
52
80
  help="Print the version and exit.",
53
81
  ),
82
+ skill: bool = typer.Option( # noqa: FBT001
83
+ False, # noqa: FBT003
84
+ "--skill",
85
+ callback=_print_and_exit(_agent_skill),
86
+ is_eager=True,
87
+ help="Print a guide that teaches an AI agent to manage the vault, and exit.",
88
+ ),
89
+ prompt: bool = typer.Option( # noqa: FBT001
90
+ False, # noqa: FBT003
91
+ "--prompt",
92
+ callback=_print_and_exit(_agent_prompt),
93
+ is_eager=True,
94
+ help="Print a prompt to paste into an AI agent for help managing the vault, and exit.",
95
+ ),
54
96
  ) -> None:
55
97
  """Manage a project's memory in a vault of markdown pages."""
56
98
 
@@ -17,6 +17,7 @@ if TYPE_CHECKING:
17
17
  from pathlib import Path
18
18
 
19
19
  VAULT_GROUP = "(vault)"
20
+ AGENT_HINT = "For an AI agent's help, paste the output of: sessionmemory --prompt"
20
21
 
21
22
 
22
23
  def _print_report(vault: Path, findings: list[doctor.Finding]) -> None:
@@ -62,3 +63,4 @@ def doctor_command(*, as_json: bool = JSON_OPTION) -> None:
62
63
  return
63
64
  pp.info(f"{len(findings)} suggestion{'s' if len(findings) != 1 else ''}")
64
65
  _print_report(vault, findings)
66
+ pp.info(AGENT_HINT)
@@ -88,7 +88,8 @@ def reconcile_command(
88
88
  "dropped": report.dropped,
89
89
  "in_progress": report.in_progress,
90
90
  "unchecked": report.unchecked,
91
- "notes": report.notes,
91
+ "notes": list(report.notes),
92
+ "note_logs": report.notes,
92
93
  }
93
94
  for report in reports
94
95
  ]
@@ -100,7 +101,7 @@ def reconcile_command(
100
101
  for report in reports:
101
102
  if report.changed:
102
103
  pp.info(f"{report.name} {verb}", details=[path.name for path in report.changed])
103
- for note in report.notes:
104
- pp.warning(f"{report.name}: {note}")
104
+ for note, logs in report.notes.items():
105
+ pp.warning(f"{report.name}: {note}", details=logs)
105
106
  if dry_run:
106
107
  pp.dryrun("no log was rewritten")
@@ -27,6 +27,11 @@ ALL = typer.Option(False, "--all", help="Reindex every project in the vault.")
27
27
  COUNT_STYLES = {"added": "green", "updated": "yellow", "removed": "red", "unchanged": ""}
28
28
 
29
29
 
30
+ def _changed(counts: fieldindex.Refresh) -> bool:
31
+ """Return whether a refresh added, updated, or removed any page."""
32
+ return bool(counts.added or counts.updated or counts.removed)
33
+
34
+
30
35
  def _report(rows: list[tuple[str, str, fieldindex.Refresh]], *, show_project: bool) -> Table:
31
36
  """Lay out each field's counts as a grid, with column totals in the footer.
32
37
 
@@ -54,6 +59,25 @@ def _report(rows: list[tuple[str, str, fieldindex.Refresh]], *, show_project: bo
54
59
  return table
55
60
 
56
61
 
62
+ def _print_vault_report(rows: list[tuple[str, str, fieldindex.Refresh]]) -> None:
63
+ """Print the grid for the projects a refresh changed, then count the rest.
64
+
65
+ A large vault's full grid outgrows the terminal, so a project with nothing to refresh
66
+ is only counted.
67
+
68
+ Args:
69
+ rows: One `(project, field, counts)` triple per field, in display order.
70
+ """
71
+ changed = {slug for slug, _, counts in rows if _changed(counts)}
72
+ current = len({slug for slug, *_ in rows} - changed)
73
+ if changed:
74
+ pp.console().print(_report([r for r in rows if r[0] in changed], show_project=True))
75
+ if current:
76
+ noun = "project" if current == 1 else "projects"
77
+ prefix = "all " if not changed and current > 1 else ""
78
+ pp.info(f"{prefix}{current} {noun} already up to date", style="default")
79
+
80
+
57
81
  def reindex_command(
58
82
  cwd: Path | None = CWD_OPTION, *, all_projects: bool = ALL, as_json: bool = JSON_OPTION
59
83
  ) -> None:
@@ -95,4 +119,7 @@ def reindex_command(
95
119
  for slug, name, directory in fields:
96
120
  status.update(Text(f"reindexing {slug}/{name}"))
97
121
  rows.append((slug, name, fieldindex.refresh(directory, embedder)))
98
- pp.console().print(_report(rows, show_project=all_projects))
122
+ if all_projects:
123
+ _print_vault_report(rows)
124
+ else:
125
+ pp.console().print(_report(rows, show_project=False))
@@ -27,32 +27,8 @@ INCLUDE_RETIRED = typer.Option(
27
27
  "--include-retired",
28
28
  help="With --specs, also show superseded and abandoned specs.",
29
29
  )
30
- LIMIT = typer.Option(10, "--limit", "-n", help="Maximum number of results.")
31
- # Hidden because the defaults were measured against labeled queries; these exist for
32
- # re-measuring them, not for loosening a search that found nothing.
33
- MAX_DISTANCE = typer.Option(
34
- None,
35
- "--max-distance",
36
- min=0.0,
37
- max=2.0,
38
- help=(
39
- "Farthest cosine distance that still counts as a hit. "
40
- f"Default {fieldindex.DEFAULT_MAX_DISTANCE}, or {fieldindex.SPECS_MAX_DISTANCE} with --specs."
41
- ),
42
- show_default=False,
43
- hidden=True,
44
- )
45
- MIN_MARGIN = typer.Option(
46
- None,
47
- "--min-margin",
48
- min=0.0,
49
- max=2.0,
50
- help=(
51
- "How much nearer than the median page searched a hit must sit. 0 turns this off. "
52
- f"Default {fieldindex.DEFAULT_MIN_MARGIN}, or {fieldindex.SPECS_MIN_MARGIN} with --specs."
53
- ),
54
- show_default=False,
55
- hidden=True,
30
+ LIMIT = typer.Option(
31
+ fieldindex.DEFAULT_LIMIT, "--limit", "-n", min=0, help="Maximum number of results."
56
32
  )
57
33
  READ = typer.Option(False, "--read", help="Print each hit's whole file under its path.") # noqa: FBT003
58
34
 
@@ -73,8 +49,6 @@ def search_command( # noqa: PLR0913
73
49
  specs_flag: bool = SPECS,
74
50
  include_retired: bool = INCLUDE_RETIRED,
75
51
  limit: int = LIMIT,
76
- max_distance: float | None = MAX_DISTANCE,
77
- min_margin: float | None = MIN_MARGIN,
78
52
  read: bool = READ,
79
53
  cwd: Path | None = CWD_OPTION,
80
54
  as_json: bool = JSON_OPTION,
@@ -90,14 +64,13 @@ def search_command( # noqa: PLR0913
90
64
  vault = require_vault()
91
65
  slug = require_project(vault, cwd)
92
66
  field_name = _field_name(specs_flag=specs_flag, logs=logs)
67
+ field_dir = paths.project_dir(vault, slug) / field_name
93
68
  hits = fieldindex.search(
94
- paths.project_dir(vault, slug) / field_name,
69
+ field_dir,
95
70
  build_embedder(),
96
71
  text,
97
72
  limit=limit,
98
- max_distance=max_distance,
99
- min_margin=min_margin,
100
- exclude=specs.is_retired if specs_flag and not include_retired else None,
73
+ exclude=None if include_retired else fieldindex.default_exclude(field_dir),
101
74
  )
102
75
 
103
76
  if as_json:
@@ -0,0 +1,212 @@
1
+ # Managing a sessionmemory vault
2
+
3
+ You are helping a person manage their sessionmemory vault: the store of a coding agent's
4
+ durable memory, kept as markdown. This guide covers the vault as a whole: its projects,
5
+ its health, its indexes, and the private files it keeps. It does not cover writing memory
6
+ during a coding session, or the plugin's `/sessionmemory:*` slash commands. Those have
7
+ their own instructions.
8
+
9
+ ## Rules
10
+
11
+ - Work on the whole vault unless the person names one project. If the current directory
12
+ belongs to a registered project (`sessionmemory project --json` exits 0), ask whether
13
+ to focus on that project or on the whole vault.
14
+ - Never run `sessionmemory init`. It is the person's bootstrap command. If no vault is
15
+ configured, say so and stop.
16
+ - Ask before you do anything that removes, moves, or overwrites content: deleting a file,
17
+ editing or removing a registry entry, renaming or splitting a page, rewriting logs, and
18
+ any `sessionmemory local` command other than `status`. Say what you will change, then
19
+ wait for a yes.
20
+ - The CLI creates pages, searches them, and reports on them. It never repairs. Make each
21
+ fix yourself with your own file tools, then run `sessionmemory doctor --json` again to confirm.
22
+ - Add `--json` to every command whose output you parse. JSON output is never styled.
23
+ - Never write a credential into the vault. It is a git repository and is committed.
24
+ Record where a credential lives instead.
25
+ - Do not commit the vault. When the sessionmemory plugin is installed, its hooks commit
26
+ the vault at session start and session end. Otherwise, committing is the person's job.
27
+ - Git history recovers anything deleted. Before you delete, check with `git status` in
28
+ the vault that earlier work is committed. If it is not, tell the person and wait for
29
+ them to commit it.
30
+
31
+ ## Find the vault
32
+
33
+ The CLI reads `SESSIONMEMORY_VAULT`, then `[vault] root` in
34
+ `~/.claude/sessionmemory.toml`. The variable wins when both are set. Inside a registered
35
+ checkout, `project_dir` in `sessionmemory project --json` output is
36
+ `<vault>/projects/<slug>`. Do not rely on `doctor` output for the vault's location: a
37
+ clean vault reports no findings, and so no paths.
38
+
39
+ ## Vault layout
40
+
41
+ ```
42
+ <vault>/
43
+ _system/vault.toml marks the directory as a vault
44
+ _system/registry.toml registered projects: slug, git remotes, checkout root
45
+ projects/<slug>/
46
+ learnings/<name>.md a field: one fact per page, searched by meaning
47
+ logs/<date>-<time>.md a field: one page per past session
48
+ specs/<date>-<name>.md one design record per feature, indexed for search
49
+ plans/<date>-<name>.md scratch, never committed
50
+ runbooks/<name>.md step-by-step procedures to follow by hand
51
+ reference/<name>.md private docs about the project
52
+ backlog.md open work, one top-level bullet per item
53
+ local/ private files linked into each checkout
54
+ */<model>.sqlite3 search indexes: derived, gitignored, disposable
55
+ ```
56
+
57
+ A project's files are found by its slug only. Nothing is shared between projects, and no
58
+ command searches across projects.
59
+
60
+ ## Projects and the registry
61
+
62
+ `_system/registry.toml` holds one table per project:
63
+
64
+ ```toml
65
+ [projects.invoice-api]
66
+ remotes = ["github.com/acme/invoice-api"]
67
+ root = "/Users/me/repos/invoice-api"
68
+ reviewed = "2026-10-01"
69
+ ```
70
+
71
+ - `sessionmemory project --json --cwd <dir>` shows which project owns a directory, and
72
+ every vault path for it.
73
+ - `sessionmemory project register --cwd <dir>` registers a directory. The plugin does
74
+ this for a git repository at session start, so run it by hand only for a folder outside
75
+ git or to choose a slug with `--slug`.
76
+ - `sessionmemory project mark-reviewed --cwd <dir>` records today as the date the
77
+ project's learnings were last reviewed.
78
+ - To list every project, read `registry.toml`, and list `projects/` too: a folder there
79
+ with no registry entry is left behind by a project that was unregistered.
80
+ - A project whose checkout moved: edit its `root`. A project that is gone for good:
81
+ remove its table, and delete `projects/<slug>/` only if the person also wants its pages
82
+ gone. A slug is permanent once pages carry it. Renaming one is manual work.
83
+
84
+ ## Pages
85
+
86
+ A learnings page has frontmatter with `title`, `uuid`, `summary`, `created`, and
87
+ `updated`, then a prose body. The title is what a session sees at its start, and the
88
+ summary is what a search shows, so a page missing either one cannot be found. Logs pages
89
+ can have no frontmatter. Rules for a page in `learnings/` or `logs/`:
90
+
91
+ - A filename is lowercase ASCII letters, digits, and hyphens, starting and ending with a
92
+ letter or digit. Any other name is not a page: it is never indexed or searched.
93
+ - A page is at most 8192 bytes. Only the first 8192 bytes are embedded, so a longer
94
+ page's tail is invisible to search. Split it into two pages, each with its own title and
95
+ summary.
96
+ - Dates in frontmatter are quoted: `created: '2026-09-02T10:00:00Z'`.
97
+ - A page that is wrong or out of date is deleted, not marked. Pages have no status.
98
+
99
+ A spec is the one file with a status: `draft`, `shipped`, `superseded`, or `abandoned`,
100
+ or no status, which means current. A superseded spec names its replacement with
101
+ `superseded_by: <filename>`.
102
+
103
+ `backlog.md` has no checkboxes. Every top-level bullet is an open item, and indented
104
+ bullets under it are its detail. Finished work is deleted with its detail, never ticked.
105
+
106
+ ## Commands for managing the vault
107
+
108
+ | Command | Use it to |
109
+ | ----------------------------------------------- | ----------------------------------------------------- |
110
+ | `sessionmemory doctor --json` | Report everything off in the vault. Never edits. |
111
+ | `sessionmemory reindex --all --json` | Bring every project's indexes up to date. |
112
+ | `sessionmemory reindex --cwd <dir> --json` | Bring one project's indexes up to date. |
113
+ | `sessionmemory reconcile --dry-run --cwd <dir>` | Preview fixing commit lists in one project's logs. |
114
+ | `sessionmemory reconcile --cwd <dir>` | Rewrite those commit lists. Ask first. |
115
+ | `sessionmemory delete <file>...` | Delete vault files and their index rows. Ask first. |
116
+ | `sessionmemory search "<words>" --cwd <dir>` | Find learnings by meaning. Add `--logs` or `--specs`. |
117
+ | `sessionmemory path --json --cwd <dir>` | Print every vault path for one project. |
118
+ | `sessionmemory export --cwd <dir>` | Write a project's learnings as a `.memoryfield.zip`. |
119
+ | `sessionmemory local status --json --cwd <dir>` | Compare a checkout's private files with the vault. |
120
+
121
+ Commands other than `doctor`, `delete`, and `reindex --all` act on one project, chosen by
122
+ `--cwd`, a directory inside that project's checkout. Run `sessionmemory <command> --help`
123
+ for every option.
124
+
125
+ `delete` asks for no confirmation and has no dry run. Ask the person first, every time.
126
+
127
+ `reconcile` leaves a line it cannot prove right as it is and counts it as unchecked. Each
128
+ warning gives the reason and lists the logs that hold the line. With `--json`,
129
+ `note_logs` maps each reason in `notes` to those logs. Show the warnings to the person.
130
+ Edit a line only when its warning names the fix, and ask first.
131
+
132
+ ## Doctor findings and their fixes
133
+
134
+ `sessionmemory doctor --json` prints a list of findings, each with `check`, `path`,
135
+ `message`, and `project`. `project` is empty for a finding about the vault itself. Every
136
+ finding is a suggestion, and the command always exits 0.
137
+
138
+ | Check | What is wrong | Fix |
139
+ | ------------- | ------------------------------------------------------- | -------------------------------------------------------------------------- |
140
+ | `filename` | A page's name breaks the filename rule | Rename the file to a conforming name. |
141
+ | `size` | A page is over 8192 bytes | Split it into two pages, each with a title and summary. |
142
+ | `frontmatter` | Frontmatter cannot be parsed, or lacks title or summary | Correct the block. Write a missing title or summary from the body. |
143
+ | `datetime` | A frontmatter date is unquoted | Quote the value. |
144
+ | `project` | A registered root no longer exists | Ask whether it moved (edit `root`) or is gone (remove the entry). |
145
+ | `registry` | `registry.toml` cannot be read | Fix the TOML by hand. Every other command fails until then. |
146
+ | `backlog` | A backlog line is ticked `- [x]` | Delete the line and its detail. |
147
+ | `reference` | A file names a vault file that does not exist | Correct the name, write the missing file, or remove the mention. |
148
+ | `spec` | A spec's `status` or `superseded_by` is not usable | Set a valid status, or name the real replacement spec. |
149
+ | `commits` | A log lists commits no branch holds | Run `reconcile --dry-run`, show the person, then `reconcile`. |
150
+ | `index` | An index is behind its files or cannot be opened | Run `sessionmemory reindex --all`. |
151
+ | `local` | A private file or its link has a problem | Follow the remedy in the message. Ask before moving or overwriting a file. |
152
+ | `doctor` | A check itself failed | Report the message. The other checks still ran. |
153
+
154
+ The message of each finding names its specific remedy. Prefer it over the table above.
155
+
156
+ Work through findings as the person directs. Group them by project when you report, and
157
+ lead with the ones that hide memory from search: `filename`, `frontmatter`, `size`, then
158
+ `registry` and `project`.
159
+
160
+ ## Private local files
161
+
162
+ Each project's `local/` folder holds files that must never reach the project's
163
+ repository: `CLAUDE.local.md`, private skills under `.claude/skills/`, private rules under
164
+ `.claude/rules/`, other paths adopted by name, and `.claude/settings.local.json`. Each
165
+ checkout holds an absolute symlink to the vault copy, ignored through git's
166
+ `info/exclude`. The settings file is copied, not linked, and the person picks which copy
167
+ wins.
168
+
169
+ - `sessionmemory local status --json --cwd <dir>` reports each entry's state. It changes
170
+ nothing.
171
+ - `sessionmemory local sync --cwd <dir>` creates missing links and replaces broken ones.
172
+ Without a terminal it asks nothing and reports what is still pending.
173
+ - `sessionmemory local adopt <entry> --cwd <dir>` moves a checkout's file into the vault
174
+ and links it back.
175
+ - `sessionmemory local decline <entry> --cwd <dir>` records that an entry stays out of
176
+ the vault, so nothing offers it again.
177
+ - `sessionmemory local sync --keep-settings checkout|vault --cwd <dir>` writes one
178
+ settings copy over the other. Show the person the difference that `local sync` reports
179
+ and let them choose.
180
+
181
+ ## The index
182
+
183
+ Each field, and `specs/`, has one SQLite index file named for the embedding model. It is
184
+ derived from the markdown and safe to delete. `sessionmemory search` refreshes the index
185
+ it reads, so a stale index is never wrong for long. After cloning a vault, or when
186
+ `doctor` reports an index problem, run `sessionmemory reindex --all`.
187
+
188
+ ## Settings
189
+
190
+ Settings live in `~/.claude/sessionmemory.toml`, and a project can override any key in
191
+ `<checkout>/.claude/sessionmemory.toml`. Every key is optional.
192
+
193
+ | Key | Default | What it does |
194
+ | ---------------- | ------- | -------------------------------------------------------- |
195
+ | `vault.root` | unset | Where the vault is |
196
+ | `inject.enabled` | `true` | Show the vault's titles at session start |
197
+ | `sweep.enabled` | `true` | Record each session into the vault when it ends |
198
+ | `local.link` | `true` | Link private files into the checkout at session start |
199
+ | `log.level` | `info` | The plugin's log level: debug, info, warning, error, off |
200
+
201
+ `hooks/vault-path.py --log` in the plugin prints where the plugin's hooks log.
202
+
203
+ ## Suggestions to offer
204
+
205
+ When the person asks what is worth doing, look for:
206
+
207
+ - Doctor findings, grouped by project, starting with the ones that hide memory.
208
+ - Registered projects whose checkout is gone, and project folders with no registry entry.
209
+ - A project with many learnings whose `reviewed` date is missing or more than 30 days
210
+ old. Suggest the person run `/sessionmemory:review` in that project.
211
+ - A long `backlog.md`. Suggest the person run `/sessionmemory:backlog` in that project.
212
+ - Index problems across projects, fixed by one `sessionmemory reindex --all`.
@@ -0,0 +1,29 @@
1
+ """Text that teaches an AI agent to manage the vault on a person's behalf.
2
+
3
+ The guide is a markdown file shipped inside the package rather than a plugin skill, so an
4
+ agent with no plugin installed, or a different agent entirely, reads the same text.
5
+ """
6
+
7
+ from __future__ import annotations
8
+
9
+ from importlib import resources
10
+
11
+ PROMPT = """\
12
+ Help me manage my sessionmemory vault.
13
+
14
+ 1. Run `sessionmemory --skill` and read all of it. It explains how the vault works and how to manage it.
15
+ 2. Run `sessionmemory doctor --json`.
16
+ 3. Give me a brief overview of the vault's state: its projects, and what doctor found in each.
17
+ 4. Ask me what I want help with, and offer a few suggestions based on what you found.
18
+
19
+ Ask me before you delete, move, or overwrite anything."""
20
+
21
+
22
+ def skill() -> str:
23
+ """Return the guide an agent reads before it manages the vault.
24
+
25
+ Returns:
26
+ str: The guide as markdown.
27
+ """
28
+ guide = resources.files(__package__).joinpath("agent_skill.md").read_text(encoding="utf-8")
29
+ return guide.rstrip("\n")