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.
- {sessionmemory-0.20.0 → sessionmemory-0.21.0}/PKG-INFO +28 -1
- {sessionmemory-0.20.0 → sessionmemory-0.21.0}/README.md +27 -0
- {sessionmemory-0.20.0 → sessionmemory-0.21.0}/pyproject.toml +6 -11
- {sessionmemory-0.20.0 → sessionmemory-0.21.0}/pyproject.toml.orig +7 -7
- {sessionmemory-0.20.0 → sessionmemory-0.21.0}/src/sessionmemory/cli.py +49 -7
- {sessionmemory-0.20.0 → sessionmemory-0.21.0}/src/sessionmemory/commands/doctor.py +2 -0
- {sessionmemory-0.20.0 → sessionmemory-0.21.0}/src/sessionmemory/commands/reconcile.py +4 -3
- {sessionmemory-0.20.0 → sessionmemory-0.21.0}/src/sessionmemory/commands/reindex.py +28 -1
- {sessionmemory-0.20.0 → sessionmemory-0.21.0}/src/sessionmemory/commands/search.py +5 -32
- sessionmemory-0.21.0/src/sessionmemory/lib/agent_skill.md +212 -0
- sessionmemory-0.21.0/src/sessionmemory/lib/agentguide.py +29 -0
- {sessionmemory-0.20.0 → sessionmemory-0.21.0}/src/sessionmemory/lib/commits.py +91 -27
- {sessionmemory-0.20.0 → sessionmemory-0.21.0}/src/sessionmemory/lib/doctor.py +20 -3
- {sessionmemory-0.20.0 → sessionmemory-0.21.0}/src/sessionmemory/lib/fieldindex.py +181 -71
- {sessionmemory-0.20.0 → sessionmemory-0.21.0}/src/sessionmemory/lib/reconcile.py +65 -27
- {sessionmemory-0.20.0 → sessionmemory-0.21.0}/src/sessionmemory/__init__.py +0 -0
- {sessionmemory-0.20.0 → sessionmemory-0.21.0}/src/sessionmemory/commands/__init__.py +0 -0
- {sessionmemory-0.20.0 → sessionmemory-0.21.0}/src/sessionmemory/commands/_common.py +0 -0
- {sessionmemory-0.20.0 → sessionmemory-0.21.0}/src/sessionmemory/commands/delete.py +0 -0
- {sessionmemory-0.20.0 → sessionmemory-0.21.0}/src/sessionmemory/commands/export.py +0 -0
- {sessionmemory-0.20.0 → sessionmemory-0.21.0}/src/sessionmemory/commands/init.py +0 -0
- {sessionmemory-0.20.0 → sessionmemory-0.21.0}/src/sessionmemory/commands/inject.py +0 -0
- {sessionmemory-0.20.0 → sessionmemory-0.21.0}/src/sessionmemory/commands/local.py +0 -0
- {sessionmemory-0.20.0 → sessionmemory-0.21.0}/src/sessionmemory/commands/log.py +0 -0
- {sessionmemory-0.20.0 → sessionmemory-0.21.0}/src/sessionmemory/commands/new.py +0 -0
- {sessionmemory-0.20.0 → sessionmemory-0.21.0}/src/sessionmemory/commands/path.py +0 -0
- {sessionmemory-0.20.0 → sessionmemory-0.21.0}/src/sessionmemory/commands/project.py +0 -0
- {sessionmemory-0.20.0 → sessionmemory-0.21.0}/src/sessionmemory/entry.py +0 -0
- {sessionmemory-0.20.0 → sessionmemory-0.21.0}/src/sessionmemory/lib/__init__.py +0 -0
- {sessionmemory-0.20.0 → sessionmemory-0.21.0}/src/sessionmemory/lib/atomic.py +0 -0
- {sessionmemory-0.20.0 → sessionmemory-0.21.0}/src/sessionmemory/lib/backlog.py +0 -0
- {sessionmemory-0.20.0 → sessionmemory-0.21.0}/src/sessionmemory/lib/bootstrap.py +0 -0
- {sessionmemory-0.20.0 → sessionmemory-0.21.0}/src/sessionmemory/lib/changes.py +0 -0
- {sessionmemory-0.20.0 → sessionmemory-0.21.0}/src/sessionmemory/lib/config.py +0 -0
- {sessionmemory-0.20.0 → sessionmemory-0.21.0}/src/sessionmemory/lib/embed.py +0 -0
- {sessionmemory-0.20.0 → sessionmemory-0.21.0}/src/sessionmemory/lib/export.py +0 -0
- {sessionmemory-0.20.0 → sessionmemory-0.21.0}/src/sessionmemory/lib/field.py +0 -0
- {sessionmemory-0.20.0 → sessionmemory-0.21.0}/src/sessionmemory/lib/frontmatter.py +0 -0
- {sessionmemory-0.20.0 → sessionmemory-0.21.0}/src/sessionmemory/lib/gitinfo.py +0 -0
- {sessionmemory-0.20.0 → sessionmemory-0.21.0}/src/sessionmemory/lib/ids.py +0 -0
- {sessionmemory-0.20.0 → sessionmemory-0.21.0}/src/sessionmemory/lib/inject.py +0 -0
- {sessionmemory-0.20.0 → sessionmemory-0.21.0}/src/sessionmemory/lib/localdeclined.py +0 -0
- {sessionmemory-0.20.0 → sessionmemory-0.21.0}/src/sessionmemory/lib/localmanifest.py +0 -0
- {sessionmemory-0.20.0 → sessionmemory-0.21.0}/src/sessionmemory/lib/localmd.py +0 -0
- {sessionmemory-0.20.0 → sessionmemory-0.21.0}/src/sessionmemory/lib/localtree.py +0 -0
- {sessionmemory-0.20.0 → sessionmemory-0.21.0}/src/sessionmemory/lib/log.py +0 -0
- {sessionmemory-0.20.0 → sessionmemory-0.21.0}/src/sessionmemory/lib/paths.py +0 -0
- {sessionmemory-0.20.0 → sessionmemory-0.21.0}/src/sessionmemory/lib/registration.py +0 -0
- {sessionmemory-0.20.0 → sessionmemory-0.21.0}/src/sessionmemory/lib/registry.py +0 -0
- {sessionmemory-0.20.0 → sessionmemory-0.21.0}/src/sessionmemory/lib/resolve.py +0 -0
- {sessionmemory-0.20.0 → sessionmemory-0.21.0}/src/sessionmemory/lib/settingsdiff.py +0 -0
- {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.
|
|
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.
|
|
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.
|
|
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 =
|
|
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
|
|
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.
|
|
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.
|
|
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 =
|
|
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
|
-
|
|
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 = [
|
|
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
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
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
|
-
|
|
42
|
-
|
|
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=
|
|
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
|
-
|
|
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(
|
|
31
|
-
|
|
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
|
-
|
|
69
|
+
field_dir,
|
|
95
70
|
build_embedder(),
|
|
96
71
|
text,
|
|
97
72
|
limit=limit,
|
|
98
|
-
|
|
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")
|