sessionmemory 0.7.0__tar.gz → 0.8.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.7.0 → sessionmemory-0.8.0}/PKG-INFO +52 -3
- {sessionmemory-0.7.0 → sessionmemory-0.8.0}/README.md +51 -2
- {sessionmemory-0.7.0 → sessionmemory-0.8.0}/pyproject.toml +1 -1
- {sessionmemory-0.7.0 → sessionmemory-0.8.0}/pyproject.toml.orig +1 -1
- {sessionmemory-0.7.0 → sessionmemory-0.8.0}/src/sessionmemory/commands/new.py +24 -1
- {sessionmemory-0.7.0 → sessionmemory-0.8.0}/src/sessionmemory/lib/bootstrap.py +2 -1
- {sessionmemory-0.7.0 → sessionmemory-0.8.0}/src/sessionmemory/lib/field.py +32 -2
- {sessionmemory-0.7.0 → sessionmemory-0.8.0}/src/sessionmemory/lib/inject.py +34 -1
- {sessionmemory-0.7.0 → sessionmemory-0.8.0}/src/sessionmemory/lib/paths.py +10 -3
- {sessionmemory-0.7.0 → sessionmemory-0.8.0}/src/sessionmemory/__init__.py +0 -0
- {sessionmemory-0.7.0 → sessionmemory-0.8.0}/src/sessionmemory/cli.py +0 -0
- {sessionmemory-0.7.0 → sessionmemory-0.8.0}/src/sessionmemory/commands/__init__.py +0 -0
- {sessionmemory-0.7.0 → sessionmemory-0.8.0}/src/sessionmemory/commands/_common.py +0 -0
- {sessionmemory-0.7.0 → sessionmemory-0.8.0}/src/sessionmemory/commands/delete.py +0 -0
- {sessionmemory-0.7.0 → sessionmemory-0.8.0}/src/sessionmemory/commands/doctor.py +0 -0
- {sessionmemory-0.7.0 → sessionmemory-0.8.0}/src/sessionmemory/commands/export.py +0 -0
- {sessionmemory-0.7.0 → sessionmemory-0.8.0}/src/sessionmemory/commands/init.py +0 -0
- {sessionmemory-0.7.0 → sessionmemory-0.8.0}/src/sessionmemory/commands/inject.py +0 -0
- {sessionmemory-0.7.0 → sessionmemory-0.8.0}/src/sessionmemory/commands/log.py +0 -0
- {sessionmemory-0.7.0 → sessionmemory-0.8.0}/src/sessionmemory/commands/project.py +0 -0
- {sessionmemory-0.7.0 → sessionmemory-0.8.0}/src/sessionmemory/commands/reindex.py +0 -0
- {sessionmemory-0.7.0 → sessionmemory-0.8.0}/src/sessionmemory/commands/search.py +0 -0
- {sessionmemory-0.7.0 → sessionmemory-0.8.0}/src/sessionmemory/lib/__init__.py +0 -0
- {sessionmemory-0.7.0 → sessionmemory-0.8.0}/src/sessionmemory/lib/atomic.py +0 -0
- {sessionmemory-0.7.0 → sessionmemory-0.8.0}/src/sessionmemory/lib/backlog.py +0 -0
- {sessionmemory-0.7.0 → sessionmemory-0.8.0}/src/sessionmemory/lib/config.py +0 -0
- {sessionmemory-0.7.0 → sessionmemory-0.8.0}/src/sessionmemory/lib/doctor.py +0 -0
- {sessionmemory-0.7.0 → sessionmemory-0.8.0}/src/sessionmemory/lib/embed.py +0 -0
- {sessionmemory-0.7.0 → sessionmemory-0.8.0}/src/sessionmemory/lib/export.py +0 -0
- {sessionmemory-0.7.0 → sessionmemory-0.8.0}/src/sessionmemory/lib/fieldindex.py +0 -0
- {sessionmemory-0.7.0 → sessionmemory-0.8.0}/src/sessionmemory/lib/frontmatter.py +0 -0
- {sessionmemory-0.7.0 → sessionmemory-0.8.0}/src/sessionmemory/lib/gitinfo.py +0 -0
- {sessionmemory-0.7.0 → sessionmemory-0.8.0}/src/sessionmemory/lib/ids.py +0 -0
- {sessionmemory-0.7.0 → sessionmemory-0.8.0}/src/sessionmemory/lib/log.py +0 -0
- {sessionmemory-0.7.0 → sessionmemory-0.8.0}/src/sessionmemory/lib/registry.py +0 -0
- {sessionmemory-0.7.0 → sessionmemory-0.8.0}/src/sessionmemory/lib/resolve.py +0 -0
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
Metadata-Version: 2.3
|
|
2
2
|
Name: sessionmemory
|
|
3
|
-
Version: 0.
|
|
3
|
+
Version: 0.8.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>
|
|
@@ -194,7 +194,8 @@ and the summary is what a search result shows. Both state the fact and not the t
|
|
|
194
194
|
## What a session sees
|
|
195
195
|
|
|
196
196
|
`sessionmemory inject` prints the block a session starts with. This is the block for a
|
|
197
|
-
project holding four learnings, one spec, one plan, and two open
|
|
197
|
+
project holding four learnings, one spec, one plan, one reference doc, and two open
|
|
198
|
+
backlog items:
|
|
198
199
|
|
|
199
200
|
```
|
|
200
201
|
## Using this vault
|
|
@@ -202,7 +203,8 @@ project holding four learnings, one spec, one plan, and two open backlog items:
|
|
|
202
203
|
Durable memory for this project lives in a vault of markdown pages. Nothing below is
|
|
203
204
|
loaded for you: the titles are what the vault holds, and each is one `sessionmemory search`
|
|
204
205
|
away. The project's folder has `learnings/` and `logs/`, searched by meaning, beside
|
|
205
|
-
`specs/`, `runbooks/`, and `backlog.md`, which are ordinary files you Read
|
|
206
|
+
`specs/`, `runbooks/`, `reference/`, and `backlog.md`, which are ordinary files you Read
|
|
207
|
+
and Edit.
|
|
206
208
|
`sessionmemory project --json` prints every path.
|
|
207
209
|
|
|
208
210
|
- Before assuming nothing was written down, search: `sessionmemory search "<words>"`
|
|
@@ -229,6 +231,12 @@ away. The project's folder has `learnings/` and `logs/`, searched by meaning, be
|
|
|
229
231
|
configuring a service, rotating a credential, or recovering from an outage.
|
|
230
232
|
Whenever you write one, create it with `sessionmemory new runbook --title "..." --cwd .`,
|
|
231
233
|
which prints its path, never in another folder or the repository.
|
|
234
|
+
- Reference: `reference/` holds this project's private docs, such as hosting
|
|
235
|
+
settings, where each credential lives, or a data dictionary, kept out of its
|
|
236
|
+
repository. Any it holds are listed below; before working in an area, read the one
|
|
237
|
+
whose name matches. Keep a doc current by editing it in place. Create one with
|
|
238
|
+
`sessionmemory new reference --title "..." --cwd .`, which prints its path. Public
|
|
239
|
+
documentation stays in the repository.
|
|
232
240
|
- Learnings are captured at session end, not by you mid-session. When the user asks
|
|
233
241
|
to keep one now: `sessionmemory new learning --title "..." --summary "..." --cwd .`
|
|
234
242
|
creates the page and prints the path to write prose into. Title and summary state
|
|
@@ -241,6 +249,10 @@ away. The project's folder has `learnings/` and `logs/`, searched by meaning, be
|
|
|
241
249
|
- Stripe retries a webhook for 72 hours, so the handler must be idempotent
|
|
242
250
|
- The nightly reconciliation job must start after the 02:00 bank feed
|
|
243
251
|
|
|
252
|
+
## Reference docs
|
|
253
|
+
|
|
254
|
+
reference/hosting.md
|
|
255
|
+
|
|
244
256
|
## Open work
|
|
245
257
|
|
|
246
258
|
2 open backlog items
|
|
@@ -250,6 +262,43 @@ away. The project's folder has `learnings/` and `logs/`, searched by meaning, be
|
|
|
250
262
|
A page body never enters that block, so its cost grows with the number of pages and not
|
|
251
263
|
with their length. The titles say what exists. `sessionmemory search` returns what they say.
|
|
252
264
|
|
|
265
|
+
## Add rules to your CLAUDE.md
|
|
266
|
+
|
|
267
|
+
The guidance block above tells a session how to read and write the vault. It does not
|
|
268
|
+
control where other skills and plugins write their files. A planning skill writes its
|
|
269
|
+
plans and specs to the path it chose for itself, often under the repository's `docs/`.
|
|
270
|
+
Rules in a `CLAUDE.md` file send that work to the vault.
|
|
271
|
+
|
|
272
|
+
Put the rules in your user file, `~/.claude/CLAUDE.md`, so that they apply in every
|
|
273
|
+
registered project. A project `CLAUDE.md` is committed with the code. Other contributors
|
|
274
|
+
read it, and they have no access to your vault.
|
|
275
|
+
|
|
276
|
+
Copy this block into the file:
|
|
277
|
+
|
|
278
|
+
```markdown
|
|
279
|
+
## Session memory
|
|
280
|
+
|
|
281
|
+
- Write every plan, spec, and design document into the sessionmemory vault, including
|
|
282
|
+
the ones a skill or plugin generates. Create them with
|
|
283
|
+
`sessionmemory new spec --title "..." --cwd .` and
|
|
284
|
+
`sessionmemory new plan --title "..." --cwd .`. Never write them under the
|
|
285
|
+
repository's `docs/`, which holds public documentation.
|
|
286
|
+
- Write every runbook (a step-by-step procedure to follow by hand) with
|
|
287
|
+
`sessionmemory new runbook --title "..." --cwd .`.
|
|
288
|
+
- Keep documentation that describes the code and is safe to publish in the repository.
|
|
289
|
+
Put private documentation about a project, such as hosting settings or where each
|
|
290
|
+
credential lives, in the vault with `sessionmemory new reference --title "..." --cwd .`,
|
|
291
|
+
and edit that file in place afterward.
|
|
292
|
+
```
|
|
293
|
+
|
|
294
|
+
If you use the CLI without the plugin, no hook injects the guidance block. Add this rule
|
|
295
|
+
to the same block, so that each session reads the guidance itself:
|
|
296
|
+
|
|
297
|
+
```markdown
|
|
298
|
+
- At the start of each session in a registered project, run
|
|
299
|
+
`sessionmemory inject --cwd .` and follow the guidance it prints.
|
|
300
|
+
```
|
|
301
|
+
|
|
253
302
|
## Documentation
|
|
254
303
|
|
|
255
304
|
| Page | What it covers |
|
|
@@ -179,7 +179,8 @@ and the summary is what a search result shows. Both state the fact and not the t
|
|
|
179
179
|
## What a session sees
|
|
180
180
|
|
|
181
181
|
`sessionmemory inject` prints the block a session starts with. This is the block for a
|
|
182
|
-
project holding four learnings, one spec, one plan, and two open
|
|
182
|
+
project holding four learnings, one spec, one plan, one reference doc, and two open
|
|
183
|
+
backlog items:
|
|
183
184
|
|
|
184
185
|
```
|
|
185
186
|
## Using this vault
|
|
@@ -187,7 +188,8 @@ project holding four learnings, one spec, one plan, and two open backlog items:
|
|
|
187
188
|
Durable memory for this project lives in a vault of markdown pages. Nothing below is
|
|
188
189
|
loaded for you: the titles are what the vault holds, and each is one `sessionmemory search`
|
|
189
190
|
away. The project's folder has `learnings/` and `logs/`, searched by meaning, beside
|
|
190
|
-
`specs/`, `runbooks/`, and `backlog.md`, which are ordinary files you Read
|
|
191
|
+
`specs/`, `runbooks/`, `reference/`, and `backlog.md`, which are ordinary files you Read
|
|
192
|
+
and Edit.
|
|
191
193
|
`sessionmemory project --json` prints every path.
|
|
192
194
|
|
|
193
195
|
- Before assuming nothing was written down, search: `sessionmemory search "<words>"`
|
|
@@ -214,6 +216,12 @@ away. The project's folder has `learnings/` and `logs/`, searched by meaning, be
|
|
|
214
216
|
configuring a service, rotating a credential, or recovering from an outage.
|
|
215
217
|
Whenever you write one, create it with `sessionmemory new runbook --title "..." --cwd .`,
|
|
216
218
|
which prints its path, never in another folder or the repository.
|
|
219
|
+
- Reference: `reference/` holds this project's private docs, such as hosting
|
|
220
|
+
settings, where each credential lives, or a data dictionary, kept out of its
|
|
221
|
+
repository. Any it holds are listed below; before working in an area, read the one
|
|
222
|
+
whose name matches. Keep a doc current by editing it in place. Create one with
|
|
223
|
+
`sessionmemory new reference --title "..." --cwd .`, which prints its path. Public
|
|
224
|
+
documentation stays in the repository.
|
|
217
225
|
- Learnings are captured at session end, not by you mid-session. When the user asks
|
|
218
226
|
to keep one now: `sessionmemory new learning --title "..." --summary "..." --cwd .`
|
|
219
227
|
creates the page and prints the path to write prose into. Title and summary state
|
|
@@ -226,6 +234,10 @@ away. The project's folder has `learnings/` and `logs/`, searched by meaning, be
|
|
|
226
234
|
- Stripe retries a webhook for 72 hours, so the handler must be idempotent
|
|
227
235
|
- The nightly reconciliation job must start after the 02:00 bank feed
|
|
228
236
|
|
|
237
|
+
## Reference docs
|
|
238
|
+
|
|
239
|
+
reference/hosting.md
|
|
240
|
+
|
|
229
241
|
## Open work
|
|
230
242
|
|
|
231
243
|
2 open backlog items
|
|
@@ -235,6 +247,43 @@ away. The project's folder has `learnings/` and `logs/`, searched by meaning, be
|
|
|
235
247
|
A page body never enters that block, so its cost grows with the number of pages and not
|
|
236
248
|
with their length. The titles say what exists. `sessionmemory search` returns what they say.
|
|
237
249
|
|
|
250
|
+
## Add rules to your CLAUDE.md
|
|
251
|
+
|
|
252
|
+
The guidance block above tells a session how to read and write the vault. It does not
|
|
253
|
+
control where other skills and plugins write their files. A planning skill writes its
|
|
254
|
+
plans and specs to the path it chose for itself, often under the repository's `docs/`.
|
|
255
|
+
Rules in a `CLAUDE.md` file send that work to the vault.
|
|
256
|
+
|
|
257
|
+
Put the rules in your user file, `~/.claude/CLAUDE.md`, so that they apply in every
|
|
258
|
+
registered project. A project `CLAUDE.md` is committed with the code. Other contributors
|
|
259
|
+
read it, and they have no access to your vault.
|
|
260
|
+
|
|
261
|
+
Copy this block into the file:
|
|
262
|
+
|
|
263
|
+
```markdown
|
|
264
|
+
## Session memory
|
|
265
|
+
|
|
266
|
+
- Write every plan, spec, and design document into the sessionmemory vault, including
|
|
267
|
+
the ones a skill or plugin generates. Create them with
|
|
268
|
+
`sessionmemory new spec --title "..." --cwd .` and
|
|
269
|
+
`sessionmemory new plan --title "..." --cwd .`. Never write them under the
|
|
270
|
+
repository's `docs/`, which holds public documentation.
|
|
271
|
+
- Write every runbook (a step-by-step procedure to follow by hand) with
|
|
272
|
+
`sessionmemory new runbook --title "..." --cwd .`.
|
|
273
|
+
- Keep documentation that describes the code and is safe to publish in the repository.
|
|
274
|
+
Put private documentation about a project, such as hosting settings or where each
|
|
275
|
+
credential lives, in the vault with `sessionmemory new reference --title "..." --cwd .`,
|
|
276
|
+
and edit that file in place afterward.
|
|
277
|
+
```
|
|
278
|
+
|
|
279
|
+
If you use the CLI without the plugin, no hook injects the guidance block. Add this rule
|
|
280
|
+
to the same block, so that each session reads the guidance itself:
|
|
281
|
+
|
|
282
|
+
```markdown
|
|
283
|
+
- At the start of each session in a registered project, run
|
|
284
|
+
`sessionmemory inject --cwd .` and follow the guidance it prints.
|
|
285
|
+
```
|
|
286
|
+
|
|
238
287
|
## Documentation
|
|
239
288
|
|
|
240
289
|
| 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.8.0"
|
|
15
15
|
|
|
16
16
|
[[project.authors]]
|
|
17
17
|
name = "Nathaniel Landau"
|
|
@@ -19,7 +19,8 @@ from sessionmemory.lib import backlog, field, paths
|
|
|
19
19
|
from sessionmemory.lib.config import now, today
|
|
20
20
|
|
|
21
21
|
app = typer.Typer(
|
|
22
|
-
no_args_is_help=True,
|
|
22
|
+
no_args_is_help=True,
|
|
23
|
+
help="Create a learning, spec, plan, runbook, reference doc, or backlog item.",
|
|
23
24
|
)
|
|
24
25
|
|
|
25
26
|
# Typer lists an Enum's members in --help and rejects anything else at parse time, so the
|
|
@@ -131,6 +132,28 @@ def new_runbook(
|
|
|
131
132
|
)
|
|
132
133
|
|
|
133
134
|
|
|
135
|
+
@app.command("reference")
|
|
136
|
+
def new_reference(
|
|
137
|
+
title: str = TITLE,
|
|
138
|
+
body: str = BODY,
|
|
139
|
+
body_file: Path | None = BODY_FILE,
|
|
140
|
+
cwd: Path | None = CWD,
|
|
141
|
+
*,
|
|
142
|
+
as_json: bool = JSON,
|
|
143
|
+
) -> None:
|
|
144
|
+
"""Create a reference doc for this project."""
|
|
145
|
+
body = resolve_body(body, body_file)
|
|
146
|
+
vault = require_vault()
|
|
147
|
+
slug = require_project(vault, cwd)
|
|
148
|
+
try:
|
|
149
|
+
path = field.new_reference(
|
|
150
|
+
paths.reference_dir(vault, slug), title=title, body=body, now=now()
|
|
151
|
+
)
|
|
152
|
+
except field.PageError as error:
|
|
153
|
+
fail(str(error))
|
|
154
|
+
_report(path, as_json=as_json)
|
|
155
|
+
|
|
156
|
+
|
|
134
157
|
@app.command("backlog", help="Add one open item to this project's backlog.md.")
|
|
135
158
|
def new_backlog(
|
|
136
159
|
kind: Kind = KIND,
|
|
@@ -46,7 +46,8 @@ One folder per project under `projects/`. Inside each:
|
|
|
46
46
|
|
|
47
47
|
- `learnings/` is a field: flat markdown pages, embedded and searchable.
|
|
48
48
|
- `logs/` is a second field, one page per session, searched on request.
|
|
49
|
-
- `specs/`, `plans/`, `runbooks/`, and `backlog.md` are plain files, never
|
|
49
|
+
- `specs/`, `plans/`, `runbooks/`, `reference/`, and `backlog.md` are plain files, never
|
|
50
|
+
indexed.
|
|
50
51
|
- `backlog.md` is the list of open items for the project, one line each, sized by
|
|
51
52
|
effort and grouped by commit type.
|
|
52
53
|
|
|
@@ -157,8 +157,8 @@ def claim_filename(directory: Path, title: str, *, stem: str | None = None) -> P
|
|
|
157
157
|
raise PageError(msg)
|
|
158
158
|
|
|
159
159
|
|
|
160
|
-
def
|
|
161
|
-
|
|
160
|
+
def _fill(path: Path, meta: dict[str, Any], body: str) -> Path:
|
|
161
|
+
"""Write a freshly claimed file, releasing the claim if the write does not land."""
|
|
162
162
|
try:
|
|
163
163
|
atomic.write_text(path, serialize(meta, body))
|
|
164
164
|
except BaseException:
|
|
@@ -167,6 +167,10 @@ def _create(directory: Path, meta: dict[str, Any], body: str, *, stem: str | Non
|
|
|
167
167
|
return path
|
|
168
168
|
|
|
169
169
|
|
|
170
|
+
def _create(directory: Path, meta: dict[str, Any], body: str, *, stem: str | None) -> Path:
|
|
171
|
+
return _fill(claim_filename(directory, str(meta["title"]), stem=stem), meta, body)
|
|
172
|
+
|
|
173
|
+
|
|
170
174
|
def new_page(directory: Path, *, title: str, summary: str, body: str, now: str) -> Path:
|
|
171
175
|
"""Create a memory page with the five fields the spec defines."""
|
|
172
176
|
meta = {
|
|
@@ -193,6 +197,32 @@ def new_document(directory: Path, *, title: str, body: str, now: str, day: str)
|
|
|
193
197
|
return _create(directory, meta, body, stem=dated_stem(title, day))
|
|
194
198
|
|
|
195
199
|
|
|
200
|
+
def new_reference(directory: Path, *, title: str, body: str, now: str) -> Path:
|
|
201
|
+
"""Create a reference doc: a titled, undated file kept current by editing in place.
|
|
202
|
+
|
|
203
|
+
The name is the title's slug alone, since a date would claim an age the doc stops
|
|
204
|
+
having at its first edit. A taken name is refused rather than suffixed, because a
|
|
205
|
+
second copy of a living doc splits it into two that drift apart.
|
|
206
|
+
|
|
207
|
+
Raises:
|
|
208
|
+
PageError: If the title yields no slug or the name is taken.
|
|
209
|
+
"""
|
|
210
|
+
try:
|
|
211
|
+
stem = slugify(title)
|
|
212
|
+
except ValueError as error:
|
|
213
|
+
raise PageError(str(error)) from error
|
|
214
|
+
path = directory / f"{stem}.md"
|
|
215
|
+
if not atomic.claim(path):
|
|
216
|
+
existing = read_page(path).title
|
|
217
|
+
if existing and existing != title:
|
|
218
|
+
# Two titles can share a slug once it is cut to the id limit.
|
|
219
|
+
msg = f"{path.name} in {directory} already holds {existing!r}; choose another title"
|
|
220
|
+
else:
|
|
221
|
+
msg = f"{path.name} already exists in {directory}; edit it instead"
|
|
222
|
+
raise PageError(msg)
|
|
223
|
+
return _fill(path, {"title": title, "created": now, "updated": now}, body)
|
|
224
|
+
|
|
225
|
+
|
|
196
226
|
def dated_stem(title: str, day: str) -> str:
|
|
197
227
|
"""Return `<day>-<slug>`, with the slug shortened so the whole stem fits the id limit.
|
|
198
228
|
|
|
@@ -26,6 +26,7 @@ class Injection:
|
|
|
26
26
|
titles: tuple[str, ...]
|
|
27
27
|
open_backlog: int
|
|
28
28
|
specs: int
|
|
29
|
+
reference: tuple[str, ...]
|
|
29
30
|
|
|
30
31
|
|
|
31
32
|
def _sort_key(title: str) -> str:
|
|
@@ -48,18 +49,39 @@ def _spec_count(directory: Path) -> int:
|
|
|
48
49
|
return sum(1 for _ in field.iter_pages(directory))
|
|
49
50
|
|
|
50
51
|
|
|
52
|
+
def _reference_docs(directory: Path) -> tuple[str, ...]:
|
|
53
|
+
"""List every markdown file, conformant name or not, since a doc moved in by hand keeps its name."""
|
|
54
|
+
if not directory.is_dir():
|
|
55
|
+
return ()
|
|
56
|
+
return tuple(
|
|
57
|
+
sorted(
|
|
58
|
+
path.name
|
|
59
|
+
for path in directory.iterdir()
|
|
60
|
+
if path.is_file()
|
|
61
|
+
and path.suffix.lower() == ".md"
|
|
62
|
+
# A dotfile is hidden metadata, such as a macOS `._` resource fork, not a doc.
|
|
63
|
+
and not path.name.startswith(".")
|
|
64
|
+
and not field.is_debris(path.name)
|
|
65
|
+
)
|
|
66
|
+
)
|
|
67
|
+
|
|
68
|
+
|
|
51
69
|
def build(vault: Path, slug: str) -> Injection:
|
|
52
70
|
"""Read the project's pages and files; the index is never consulted here.
|
|
53
71
|
|
|
54
72
|
Specs are counted rather than listed. A spec outlives the work it describes, so a
|
|
55
73
|
list of them is a changelog rather than open work, and it grows without bound. The
|
|
56
74
|
count says whether listing `specs/` is worth a call, which is all a session needs.
|
|
75
|
+
|
|
76
|
+
Reference docs are listed by filename. They are few and edited in place rather than
|
|
77
|
+
accumulated, and a name a session recognizes is what sends it to read one.
|
|
57
78
|
"""
|
|
58
79
|
return Injection(
|
|
59
80
|
project=slug,
|
|
60
81
|
titles=_titles(paths.learnings_dir(vault, slug)),
|
|
61
82
|
open_backlog=_open_backlog(paths.backlog_path(vault, slug)),
|
|
62
83
|
specs=_spec_count(paths.specs_dir(vault, slug)),
|
|
84
|
+
reference=_reference_docs(paths.reference_dir(vault, slug)),
|
|
63
85
|
)
|
|
64
86
|
|
|
65
87
|
|
|
@@ -68,7 +90,8 @@ GUIDANCE = """## Using this vault
|
|
|
68
90
|
Durable memory for this project lives in a vault of markdown pages. Nothing below is
|
|
69
91
|
loaded for you: the titles are what the vault holds, and each is one `{command} search`
|
|
70
92
|
away. The project's folder has `learnings/` and `logs/`, searched by meaning, beside
|
|
71
|
-
`specs/`, `runbooks/`, and `backlog.md`, which are ordinary files you Read
|
|
93
|
+
`specs/`, `runbooks/`, `reference/`, and `backlog.md`, which are ordinary files you Read
|
|
94
|
+
and Edit.
|
|
72
95
|
`{command} project --json` prints every path.
|
|
73
96
|
|
|
74
97
|
- Before assuming nothing was written down, search: `{command} search "<words>"`
|
|
@@ -95,6 +118,12 @@ away. The project's folder has `learnings/` and `logs/`, searched by meaning, be
|
|
|
95
118
|
configuring a service, rotating a credential, or recovering from an outage.
|
|
96
119
|
Whenever you write one, create it with `{command} new runbook --title "..." --cwd .`,
|
|
97
120
|
which prints its path, never in another folder or the repository.
|
|
121
|
+
- Reference: `reference/` holds this project's private docs, such as hosting
|
|
122
|
+
settings, where each credential lives, or a data dictionary, kept out of its
|
|
123
|
+
repository. Any it holds are listed below; before working in an area, read the one
|
|
124
|
+
whose name matches. Keep a doc current by editing it in place. Create one with
|
|
125
|
+
`{command} new reference --title "..." --cwd .`, which prints its path. Public
|
|
126
|
+
documentation stays in the repository.
|
|
98
127
|
- Learnings are captured at session end, not by you mid-session. When the user asks
|
|
99
128
|
to keep one now: `{command} new learning --title "..." --summary "..." --cwd .`
|
|
100
129
|
creates the page and prints the path to write prose into. Title and summary state
|
|
@@ -107,6 +136,9 @@ def render(injection: Injection, *, command: str = "sessionmemory") -> str:
|
|
|
107
136
|
lines.extend(f" - {title}" for title in injection.titles)
|
|
108
137
|
if not injection.titles:
|
|
109
138
|
lines.append(" nothing yet")
|
|
139
|
+
if injection.reference:
|
|
140
|
+
lines.extend(["", "## Reference docs", ""])
|
|
141
|
+
lines.extend(f" reference/{name}" for name in injection.reference)
|
|
110
142
|
lines.extend(["", "## Open work", ""])
|
|
111
143
|
item = "item" if injection.open_backlog == 1 else "items"
|
|
112
144
|
lines.append(f" {injection.open_backlog} open backlog {item}")
|
|
@@ -123,4 +155,5 @@ def payload(injection: Injection, *, command: str) -> dict[str, object]:
|
|
|
123
155
|
"titles": list(injection.titles),
|
|
124
156
|
"open_backlog": injection.open_backlog,
|
|
125
157
|
"specs": injection.specs,
|
|
158
|
+
"reference": list(injection.reference),
|
|
126
159
|
}
|
|
@@ -1,9 +1,9 @@
|
|
|
1
1
|
"""Where a project's files live inside the vault.
|
|
2
2
|
|
|
3
3
|
`learnings/` and `logs/` are fields: flat directories of pages, each with its own
|
|
4
|
-
index. `specs/`, `plans/`, `runbooks/`, and `backlog.md` sit beside them
|
|
5
|
-
indexed. A
|
|
6
|
-
|
|
4
|
+
index. `specs/`, `plans/`, `runbooks/`, `reference/`, and `backlog.md` sit beside them
|
|
5
|
+
and are never indexed. A project's files are found by its slug and nothing else; there
|
|
6
|
+
is no global scope.
|
|
7
7
|
"""
|
|
8
8
|
|
|
9
9
|
from __future__ import annotations
|
|
@@ -21,6 +21,7 @@ LOGS_DIR = "logs"
|
|
|
21
21
|
SPECS_DIR = "specs"
|
|
22
22
|
PLANS_DIR = "plans"
|
|
23
23
|
RUNBOOKS_DIR = "runbooks"
|
|
24
|
+
REFERENCE_DIR = "reference"
|
|
24
25
|
BACKLOG_FILE = "backlog.md"
|
|
25
26
|
|
|
26
27
|
FIELD_DIRS: tuple[str, ...] = (LEARNINGS_DIR, LOGS_DIR)
|
|
@@ -56,6 +57,11 @@ def runbooks_dir(vault: Path, slug: str) -> Path:
|
|
|
56
57
|
return project_dir(vault, slug) / RUNBOOKS_DIR
|
|
57
58
|
|
|
58
59
|
|
|
60
|
+
def reference_dir(vault: Path, slug: str) -> Path:
|
|
61
|
+
"""Return the project's reference folder."""
|
|
62
|
+
return project_dir(vault, slug) / REFERENCE_DIR
|
|
63
|
+
|
|
64
|
+
|
|
59
65
|
def backlog_path(vault: Path, slug: str) -> Path:
|
|
60
66
|
"""Return the project's backlog checklist file."""
|
|
61
67
|
return project_dir(vault, slug) / BACKLOG_FILE
|
|
@@ -73,6 +79,7 @@ def project_paths(vault: Path, slug: str) -> dict[str, str]:
|
|
|
73
79
|
"specs": str(specs_dir(vault, slug)),
|
|
74
80
|
"plans": str(plans_dir(vault, slug)),
|
|
75
81
|
"runbooks": str(runbooks_dir(vault, slug)),
|
|
82
|
+
"reference": str(reference_dir(vault, slug)),
|
|
76
83
|
"backlog": str(backlog_path(vault, slug)),
|
|
77
84
|
}
|
|
78
85
|
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|