INSTALL.md

docs/INSTALL.md

1. # Installing better-memory
3. One script (plus an optional second one) and one launchd job on a Mac, then a
4. scheduled Cowork task for the distiller. Replace `CHANGEME` with the macOS username.
6. ## The shape
8. vaults -> gate.py (20:00, launchd) -> ~/cowork-staging/staging -> distiller (20:30, Cowork) -> Notion better-memory
10. ## 1. Decide the walls first
12. Open `gate.py` and read `_BASE_DENY_PREFIXES` and `DENY_COMPONENTS`. Every folder that
13. must stay out of a database your phone reads has to be named there (prefixes are
14. relative to a vault root and match case-insensitively; components match a folder name
15. at any depth). Add any that are missing, and add a matching probe to the startup
16. self-check in `main()` so the gate refuses to run if that wall ever stops blocking.
17. This is the one review that matters. `EXTRA_DENY` (comma-separated prefixes) adds
18. walls without editing the file.
20. ## 2. Install the scripts
22. mkdir -p ~/.local/bin/better-memory ~/cowork-staging
23. cp gate.py content_gate.py scheduling/run-nightly.sh ~/.local/bin/better-memory/
24. chmod +x ~/.local/bin/better-memory/*
26. ## 3. Run it by hand against the live vaults
28. VAULT_ROOTS="$HOME/Documents/vaults/workbench:$HOME/Documents/vaults/identity" \
29. STAGING_DIR="$HOME/cowork-staging" \
30. python3 ~/.local/bin/better-memory/gate.py
32. You want one line: `gate: staged=N skipped=N framing-only=N scaffold-skipped=N total-staged=N -> <staging dir>`.
33. Then check the walls held, naming your own walled folders:
35. ls ~/cowork-staging/staging | grep -iE '_private|finance|journal' \
36. && echo "WALL LEAK, STOP" || echo "walls holding"
38. If the gate prints `DENYLIST FAILED to block ...`, that is it refusing to run because a
39. wall is not blocking. Fix the denylist; do not force it. Run it a second time: it should
40. stage 0.
42. Point `VAULT_ROOTS` at the live vaults, never at a copy or a mirror that may be missing
43. the very folders the walls exist for.
45. ## 4. Schedule it
47. Edit `scheduling/com.example.better-memory.plist` (replace every `CHANGEME`; confirm the
48. `python3` path in `run-nightly.sh` matches `which python3`), and set `VAULT_ROOTS` in
49. `run-nightly.sh`. Then:
51. cp scheduling/com.example.better-memory.plist ~/Library/LaunchAgents/
52. launchctl load ~/Library/LaunchAgents/com.example.better-memory.plist
53. launchctl start com.example.better-memory
54. cat ~/cowork-staging/better-memory.log
56. It now runs nightly at 20:00. To stop it: `launchctl unload` the same plist.
58. ## 5. The distiller
60. 1. In Notion, create a database named `better-memory` with the properties in
61. [`distiller/notion-schema.md`](../distiller/notion-schema.md), and seed the Tags
62. vocabulary.
63. 2. Authorize the Notion connector in Claude against that workspace. Click-through
64. authorization; no token touches a vault or a script.
65. 3. Install [`distiller/better-memory-nightly-distill`](../distiller/better-memory-nightly-distill/SKILL.md)
66. as a skill, with the database's URL and data source ID filled in.
67. 4. Create a Cowork scheduled task for 20:30 that runs the skill, bound to
68. `~/cowork-staging/staging` only.
69. 5. Keep the database read-only from every interactive session.
71. ## The optional content gate
73. `run-nightly.sh` runs `content_gate.py` after the path gate. It removes (or, with
74. `BM_GATE_MODE=redact`, redacts) any staged file with `private: true`, `gate: block` or
75. `visibility: private` in its frontmatter, and any line carrying `%% bm:private %%` or
76. matching its patterns. It writes `gate-report.json` into staging listing every decision.
77. It is a backstop for filing mistakes, not semantic privacy: a private thought in
78. ordinary words, with no flag and no pattern, passes. Delete its lines from the wrapper
79. to run the path gate alone.