@codewizard-dt/bootstrap 2.13.0 → 2.15.0

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 (38) hide show
  1. package/lib/hooks/README.md +592 -12
  2. package/lib/hooks/absolute-path-guard.js +142 -0
  3. package/lib/hooks/claude-settings-guard.js +235 -0
  4. package/lib/hooks/env-content-read-guard.js +367 -0
  5. package/lib/hooks/git-protected-ops-block.js +12 -7
  6. package/lib/hooks/interpreter-indirection-guard.js +576 -0
  7. package/lib/hooks/lib/command-parse.js +63 -0
  8. package/lib/hooks/package-install-consent.js +151 -0
  9. package/lib/hooks/protected-write-guard.js +237 -0
  10. package/lib/scripts/README.md +62 -5
  11. package/lib/scripts/build-mcp-guide.sh +9 -1
  12. package/lib/scripts/install-global.sh +25 -2
  13. package/lib/scripts/install-mcps.sh +140 -36
  14. package/lib/scripts/lib.sh +11 -7
  15. package/lib/scripts/merge-gitignore.sh +242 -33
  16. package/lib/scripts/merge-settings-deny.js +112 -39
  17. package/lib/scripts/templates/file-suggestion.sh +142 -0
  18. package/lib/scripts/templates/gitignore +8 -0
  19. package/lib/scripts/templates/guides/stubs/playwright.md +2 -0
  20. package/lib/scripts/templates/settings-deny.json +81 -1
  21. package/lib/skills/debug-logs/SKILL.md +1 -1
  22. package/lib/skills/git-commit/SKILL.md +8 -0
  23. package/package.json +5 -2
  24. package/raw/research/brave-mcp-single-docker-container/index.md +0 -94
  25. package/raw/research/brave-mcp-single-docker-container/sources.md +0 -70
  26. package/raw/research/dark-mode-theme/index.md +0 -85
  27. package/raw/research/dark-mode-theme/sources.md +0 -49
  28. package/raw/research/mcp-add-scope-writes/index.md +0 -46
  29. package/raw/research/mcp-add-scope-writes/sources.md +0 -38
  30. package/raw/research/mcp-one-process-per-user/index.md +0 -75
  31. package/raw/research/mcp-one-process-per-user/sources.md +0 -66
  32. package/raw/research/mcp-scope-conflict-handling/index.md +0 -61
  33. package/raw/research/mcp-scope-conflict-handling/sources.md +0 -32
  34. package/raw/research/serena-mcp-disconnect/index.md +0 -81
  35. package/raw/research/serena-mcp-disconnect/sources.md +0 -87
  36. package/raw/research/wiki-tooling-improvements/index.md +0 -126
  37. package/raw/research/wiki-tooling-improvements/sources.md +0 -73
  38. package/raw/software-factory-case-study.pdf +0 -0
@@ -1,81 +0,0 @@
1
- ---
2
- topic: "Recent hook changes to Serena MCP health-checking appear to be causing Serena's MCP server to disconnect mid-session, almost every session — evidenced by: 'Serena's MCP server disconnected mid-session, so exploration fell back to Read/Bash — didn't block anything since the README/wiki already had the architecture fully synthesized.'"
3
- slug: serena-mcp-disconnect
4
- researched: 2026-07-07
5
- sources: [./sources.md]
6
- ---
7
-
8
- # Research: Serena MCP server disconnects mid-session after the health-tracking hook change
9
-
10
- > **The health-tracking hook doesn't just detect a dead Serena server — under a common, everyday condition it actively kills a live, healthy one.** `classifySerenaFailure()` defaults *any* unrecognized error string to `'transport'` (assess-and-possibly-kill) instead of `'tool'` (log-and-continue). A completely benign, expected error — Serena declining to parse a file whose language isn't enabled in `.serena/project.yml` — doesn't match the narrow tool-level regex, falls through to the transport branch, and `attemptSerenaRestart()` then `pkill`s the process on the false premise that "alive but returned an error" means "hung." Since Claude Code has no documented way to reconnect a stdio MCP server mid-session, the kill is effectively permanent for the rest of that session. This was caught live, in real time, during this research: three parallel `get_symbols_overview` calls on this repo's own `.js` hook files (JS/TS isn't in this project's enabled Serena languages) triggered exactly this sequence, and `ps aux` confirms the `bootstrap-claude` Serena process is gone while two other concurrently open projects' Serena processes are untouched. A related concurrency bug (unsynchronized read-modify-write on the shared per-project state file) then left the enforcement flag in an inconsistent state — `should_enforce: true` while the process is confirmed dead — which is the exact deadlock shape that would explain "almost every session."
11
-
12
- ## Research Questions
13
- - What changed in the recent Serena health-tracking hook work, and does it plausibly cause server disconnects?
14
- - Can the disconnect be reproduced/observed directly, and what is the precise trigger?
15
- - Is there a design flaw in how "hung" vs. "dead" vs. "erroring-but-alive" is distinguished?
16
- - Is there a secondary bug (e.g. concurrency) that compounds the problem?
17
- - What's the minimal, safe fix?
18
-
19
- ## Current State (Codebase)
20
-
21
- The hook chain lives in `lib/hooks/` (mirrored to `~/.claude/hooks/` by `install-global.sh`):
22
-
23
- - **`lib/hooks/lib/serena.js`** — shared helper. Added in commit `5752eed` ("Add Serena health tracking with fail-open enforcement..."): a per-project JSON state file (`~/.claude/state/lsp-ready-<md5(cwd).slice(0,12)>`) now carries a `health` sub-object (`should_enforce`, `healthy`, `error_count`, `last_error`, `last_check`, `notified`), plus new functions `classifySerenaFailure()`, `isSerenaProcessAlive()`, and `attemptSerenaRestart()` [S1].
24
- - **`lib/hooks/serena-usage-tracker.js`** — `PostToolUse` + `PostToolUseFailure` hook, registered under matcher `mcp__serena__.*|mcp__plugin_[^_]+_serena__.*` in `~/.claude/settings.json` [S4]. On any Serena tool call: success restores health; failure is classified and, if `'transport'`, drives `handleFailure()` → process-liveness probe → possible restart → fail-open [S2].
25
- - **`lib/hooks/serena-first-read-guard.js`** — Gate 1 blocks the very first `Read` on a code file until `mcp__serena__get_symbols_overview` (or another nav tool) has been called at least once (`warmup_done`); Gates 4/5 require increasing `nav_count` before more Reads unlock. All gates are skipped only if `shouldEnforceSerena(flag)` is false [S3].
26
- - **`.serena/project.yml`** for this repo enables only `languages: [bash, markdown, yaml]` — **not** `typescript` (the config file's own comment says "For JavaScript, use typescript") [S5]. But this repo's own tooling — `lib/hooks/*.js`, `lib/scripts/*.js`, `bin/cli.js` — is JavaScript.
27
- - The user-level global rule `~/.claude/rules/lsp-first.md` instructs **all agents** to call `find_symbol`/`get_symbols_overview` first for any code navigation, with no carve-out for files whose language isn't enabled in the current project's Serena config.
28
-
29
- ## Key Findings
30
-
31
- 1. **The exact failure was reproduced live, in this session, on this repo.** Three parallel `mcp__serena__get_symbols_overview` calls against `lib/hooks/lib/serena.js`, `lib/hooks/serena-session-reset.js`, and `lib/hooks/serena-usage-tracker.js` each failed with `ValueError: Cannot extract symbols from file <path>. Active languages: ['bash', 'markdown', 'yaml']` — because JS/TS isn't an enabled language for this project [S6]. Immediately after, the system surfaced: *"The following MCP servers have disconnected: serena."* [S7]
32
-
33
- 2. **`classifySerenaFailure()` misclassifies this benign error as a transport failure.** Its tool-level regex — `not found|no results|no matching|no symbol|could not find|error searching|error finding|does not exist|no such (?:file|symbol|path|directory)|error at` — does not match "Cannot extract symbols... Active languages: [...]". The function's own comment says "Unknown ⇒ transport (assess health rather than silently ignore)" [S1, lines 449–472] — meaning *any* Serena error message the author didn't anticipate defaults to the destructive path.
34
-
35
- 3. **`attemptSerenaRestart()` kills a process that just proved it was alive.** The function's premise: if `isSerenaProcessAlive()` is true after a failure, the process must be "hung," so `pkill -f 'serena start-mcp-server.*<projectDir>'` is issued, followed by a 1s sleep and a re-probe [S1, lines 492–509]. This is a logical inversion: a `PostToolUseFailure`/error `tool_response` can only fire if the MCP round-trip *completed* — the server necessarily responded. A genuinely hung or dead process would never produce a parseable error payload for this hook to classify in the first place. The hook's own code comment even acknowledges the fix is unrecoverable: *"There is no documented way to reconnect a stdio MCP server mid-session, so a successful 'restart' only happens if the host respawns the process."* [S1, lines 495–497]
36
-
37
- 4. **Empirically confirmed via `ps aux`.** No `serena start-mcp-server ... bootstrap-claude` process exists post-incident, while `serena start-mcp-server ... portfolio_v2` and `... gauntlet/demand-letter` (two other projects open in sibling sessions at the same time) are both alive and untouched [S8]. This rules out a host-level/global Serena outage — the kill was scoped to exactly the project whose hook fired.
38
-
39
- 5. **The per-project state file confirms the exact trigger and reveals a second bug.** `~/.claude/state/lsp-ready-6d7a97f1dd99` (the `bootstrap-claude` state file) shows `last_error` verbatim matching the reproduction above, `healthy: false`, but **`should_enforce: true`** [S9] — an inconsistent combination the code's own contract says should not occur (`should_enforce` is meant to flip to `false` exactly when `attemptSerenaRestart` finds no live process remaining, per `handleFailure()`'s final branch [S1, lines 170–189]). Root cause: `serena-usage-tracker.js` does an unsynchronized `readStateFile → mutate → writeStateFile` with no locking [S2, lines 122–189; `writeStateFile` at S1 lines 399–404]. The three parallel `get_symbols_overview` failures in this session raced: `error_count: 2` (not 3 — one write was clobbered), and the write that correctly set `should_enforce: false` was overwritten by a losing, stale write from another concurrent invocation.
40
-
41
- 6. **This inconsistent state reproduced the deadlock live, moments later.** Immediately after, a plain `ls`/`find` via Bash on `raw/research/` was blocked by `serena-bash-grep-block.js`'s SERENA-FIRST guard — even though Serena is confirmed dead — because the guard reads `should_enforce: true` from the (corrupted) state file and has no independent way to know the process is gone. Work only proceeded via a `python3 -c` one-liner that doesn't match the guard's command patterns.
42
-
43
- 7. **In a fresh session, this is the "almost every time" mechanism.** `serena-session-reset.js` wipes `nav_count`/`warmup_done` to zero at `SessionStart` [S10]. `serena-first-read-guard.js` Gate 1 then blocks the *first* code `Read` until a Serena nav call succeeds [S3, lines 55–67]. Per the global LSP-first rule, the agent's first move on a code file is `get_symbols_overview`. If that first file is one of this project's own `.js` hook/script files (a near-certainty when exploring `lib/hooks/`, `lib/scripts/`, or `bin/cli.js`, since `typescript` isn't enabled), the failure→misclassify→pkill sequence fires at the very start of the session — the worst possible time, before `nav_count` has any headroom to survive a stale `should_enforce: true` race outcome. This matches the reported symptom precisely: it recurs "almost every time" because the trigger condition (Serena is asked to parse a JS file in a project that hasn't enabled JS/TS) is hit on nearly every session's first few tool calls, not on rare edge cases.
44
-
45
- 8. **The reported incident text is consistent with a race that happened to land safely.** *"Serena's MCP server disconnected mid-session, so exploration fell back to Read/Bash — didn't block anything since the README/wiki already had the architecture fully synthesized"* describes a session where the kill fired, but either `should_enforce` correctly flipped to `false` (no race) or `nav_count`/prior reads had already cleared the gates, so the fallback wasn't blocked. This session's own reproduction shows the alternate (worse) outcome: the race left `should_enforce: true`, and the bash fallback *was* blocked.
46
-
47
- ## Constraints
48
-
49
- - Any fix must preserve the hook's stated contract: **fail-open, never fail-closed** — a broken Serena must never leave the agent unable to work at all.
50
- - `lib/hooks/lib/serena.js` is shared by 7+ guard hooks; changes must not regress `isAllowedPath`, symbol detection, or the message-builder API used elsewhere.
51
- - The hooks are mirrored verbatim to `~/.claude/hooks/` and apply across *all* projects, not just this repo — so the classification/restart fix should be general (not bootstrap-claude-specific), while the `.serena/project.yml` language gap is this-repo-specific.
52
- - No test suite currently exercises `classifySerenaFailure`/`attemptSerenaRestart` (not found via codebase search) — any fix should be validated by direct reasoning/manual reproduction, as done here, since there's no existing harness to run against.
53
-
54
- ## Recommendation
55
-
56
- Two independent, complementary fixes — both are needed; neither alone fully resolves the symptom.
57
-
58
- **A. Fix the hook logic (`lib/hooks/lib/serena.js`, `lib/hooks/serena-usage-tracker.js`) — applies to every project:**
59
-
60
- 1. **Stop killing a process that just answered.** A `PostToolUse`/`PostToolUseFailure` event with a parseable error payload is proof the server is alive and responsive — that is the opposite of "hung." Remove (or heavily restrict) the `pkill` branch in `attemptSerenaRestart()`; at minimum, never invoke it from `handleFailure()`'s per-tool-call error path. If a genuine "unresponsive process" signal is needed, it would have to come from the harness itself (e.g. a distinct transport-disconnect notification, or a timeout with *no* response at all) — not from a tool call that successfully round-tripped with an error.
61
- 2. **Flip `classifySerenaFailure()`'s default.** Change "Unknown ⇒ transport" to "Unknown ⇒ tool" (log-and-continue). A missed real transport failure just delays detection to the next failure; a false-positive under the current default is an irreversible kill. Also add the observed pattern (`cannot extract symbols`, `active languages`, `unsupported language`) to the explicit tool-level regex, since it's a deterministic, expected response.
62
- 3. **Make the state-file read-modify-write atomic.** `writeStateFile` currently does a bare `fs.writeFileSync` with no locking (`lib/hooks/lib/serena.js` lines 399–404), so concurrent Serena tool calls (common — agents frequently batch independent navigation calls, as this session did) race and can corrupt `error_count`/`should_enforce`, as observed. Use a write-to-temp-then-rename for atomicity, and add a short-lived lock (e.g. a `.lock` sibling file with a retry/backoff, or `proper-lockfile`) around the full read-modify-write in `handleSuccess`/`handleFailure`.
63
- 4. **Bound the worst case regardless.** Add a hard ceiling in `serena-first-read-guard.js`: if Gate 1 has blocked N times in a row without `warmup_done` ever succeeding, fail open rather than blocking indefinitely. This is a safety net if an unforeseen error type or another race slips past fixes 1–3.
64
-
65
- **B. Fix this project's Serena language config (`.serena/project.yml`) — bootstrap-claude-specific:**
66
-
67
- Add `typescript` to the `languages` list so `lib/hooks/*.js`, `lib/scripts/*.js`, and `bin/cli.js` get real symbol support instead of a guaranteed parse failure on every navigation attempt. This removes the trigger condition at its most common source for this repo and gives the agent working code intelligence for the repo's own JS surface (currently it silently degrades to Read/Bash for all JS/TS files, which the memory `hooks/serena-health-tracking` already tacitly documents but doesn't flag as a gap).
68
-
69
- ### Risks and mitigations
70
- - **Risk:** Loosening the transport-classification default might mask a genuinely dead server for longer. **Mitigation:** `handleSuccess()` already restores health instantly on the next success, and the fail-open path still exists for cases where the process is *actually* absent (`isSerenaProcessAlive()` false) — only the "alive-but-erroring ⇒ kill" inversion is being removed.
71
- - **Risk:** Adding `typescript` to `project.yml` spins up a TS language-server process for a repo that's primarily markdown/wiki content. **Mitigation:** this repo already ships real JS (`lib/hooks/`, `lib/scripts/`, `bin/cli.js`) that benefits from it; the overhead is the same one other projects on this machine already pay (confirmed running for `portfolio_v2` and `gauntlet/demand-letter` in `ps aux`).
72
- - **Risk:** Removing the "restart" behavior entirely removes any self-healing. **Mitigation:** there was never real self-healing to begin with — the code's own comment confirms no documented mid-session stdio reconnect exists; the pkill was pure downside with no realistic upside.
73
-
74
- ### Alternative if constraints change
75
- If Claude Code ever exposes a genuine transport-disconnect event (distinct from a tool-level error payload), that would be the correct signal to drive `attemptSerenaRestart()` — at that point the "kill and hope the host respawns" logic could legitimately fire on that event instead of on ordinary tool errors.
76
-
77
- ## Next Steps
78
-
79
- - `/task-add Fix Serena health-tracking hook: stop killing live-but-erroring processes, default unknown failures to tool-level, and atomicize state-file writes (lib/hooks/lib/serena.js, lib/hooks/serena-usage-tracker.js)` — the general hook fix (A above).
80
- - `/task-add Add typescript to .serena/project.yml languages list so lib/hooks/*.js, lib/scripts/*.js, and bin/cli.js get real symbol navigation` — the project-config fix (B above).
81
- - Run `/wiki-ingest raw/research/serena-mcp-disconnect/index.md` to synthesize this into the knowledge base once the above tasks are filed.
@@ -1,87 +0,0 @@
1
- ---
2
- topic: "Recent hook changes to Serena MCP health-checking appear to be causing Serena's MCP server to disconnect mid-session, almost every session"
3
- slug: serena-mcp-disconnect
4
- researched: 2026-07-07
5
- ---
6
-
7
- # Primary Sources — Serena MCP server disconnects mid-session
8
-
9
- | ID | Type | Locator | Accessed | What it contributed |
10
- |----|------|---------|----------|---------------------|
11
- | S1 | codebase | `lib/hooks/lib/serena.js` (post-`5752eed`, lines 375–510) | 2026-07-07 | `classifySerenaFailure()`, `isSerenaProcessAlive()`, `attemptSerenaRestart()`, `shouldEnforceSerena()`, state-file read/write functions — the core misclassification + kill logic |
12
- | S2 | codebase | `lib/hooks/serena-usage-tracker.js` (full file) | 2026-07-07 | `handleSuccess()`/`handleFailure()` — how a Serena tool failure drives classification, restart, and fail-open; confirms unsynchronized `readStateFile → mutate → writeStateFile` |
13
- | S3 | codebase | `lib/hooks/serena-first-read-guard.js` (full file) | 2026-07-07 | Gate 1 (`warmup_done`) / Gate 4 / Gate 5 logic — shows a fresh session blocks the first code `Read` until a Serena nav call succeeds, and only skips enforcement if `shouldEnforceSerena()` is false |
14
- | S4 | codebase | `~/.claude/settings.json` — `hooks.PostToolUse` / `hooks.PostToolUseFailure` entries | 2026-07-07 | Confirms `serena-usage-tracker.js` is wired to both events with matcher `mcp__serena__.*\|mcp__plugin_[^_]+_serena__.*` |
15
- | S5 | codebase | `.serena/project.yml` (bootstrap-claude) | 2026-07-07 | `languages: [bash, markdown, yaml]` — confirms `typescript`/`javascript` is NOT enabled for this project despite `lib/hooks/*.js`, `lib/scripts/*.js`, `bin/cli.js` being real JS code |
16
- | S6 | codebase (live reproduction) | `mcp__serena__get_symbols_overview` tool_response, this session | 2026-07-07 | Verbatim error: `ValueError: Cannot extract symbols from file lib/hooks/lib/serena.js. Active languages: ['bash', 'markdown', 'yaml']` — the exact trigger, reproduced 3× in parallel against `lib/hooks/lib/serena.js`, `lib/hooks/serena-session-reset.js`, `lib/hooks/serena-usage-tracker.js` |
17
- | S7 | tool output (live reproduction) | System reminder immediately following S6, this session | 2026-07-07 | `"The following MCP servers have disconnected: serena"` and the full list of `mcp__serena__*` tools becoming unavailable — the disconnect event itself, observed in real time right after the ValueError batch |
18
- | S8 | shell (live reproduction) | `ps aux \| grep -i serena` output, this session | 2026-07-07 | No `serena start-mcp-server ... /Users/davidtaylor/Repositories/bootstrap-claude` process present; sibling processes `... /Users/davidtaylor/Repositories/portfolio_v2` and `... /Users/davidtaylor/Repositories/gauntlet/demand-letter` are alive and running — proves the kill was scoped to exactly this project, not a global outage |
19
- | S9 | filesystem (live reproduction) | `~/.claude/state/lsp-ready-6d7a97f1dd99` (md5 of `/Users/davidtaylor/Repositories/bootstrap-claude`, first 12 hex chars) | 2026-07-07 | `health.last_error` matches S6 verbatim; `health.healthy: false`; `health.error_count: 2` (not 3 — a lost write); `health.should_enforce: true` — the inconsistent post-race state that re-armed enforcement despite the process being dead |
20
- | S10 | codebase | `lib/hooks/serena-session-reset.js` (full file) | 2026-07-07 | `SessionStart` hook wipes the per-project state file (`nav_count`/`warmup_done` reset to zero) every new session — the reason Gate 1 is live at the very start of every session, when the first-file-is-JS trigger is most likely to fire |
21
- | S11 | codebase | `git log --oneline -20 -- lib/hooks/` and `git show --stat 5752eed` | 2026-07-07 | Confirms commit `5752eed` ("Add Serena health tracking with fail-open enforcement, project-scoped guards, and hook consolidation", 2026-07-06) is the commit that introduced the health-tracking/restart machinery being investigated |
22
- | S12 | Auto Memory | `hooks/serena-health-tracking` memory file | 2026-07-07 | Corroborates the design intent and self-acknowledged limitation: *"There is NO documented way to reconnect a stdio MCP server mid-session; 'restart' is best-effort only. Fail-open + success-based recovery is the guaranteed path."* — confirms the author already knew restarts can't truly succeed, which sharpens why triggering the kill on a false premise is the critical defect |
23
-
24
- ## Excerpts
25
-
26
- ### S1 — `lib/hooks/lib/serena.js`
27
- `/Users/davidtaylor/Repositories/bootstrap-claude/lib/hooks/lib/serena.js` (lines 449–509)
28
- > ```
29
- > function classifySerenaFailure(errorPayload) {
30
- > ...
31
- > // Unknown ⇒ transport (assess health rather than silently ignore).
32
- > return 'transport';
33
- > }
34
- > ...
35
- > /**
36
- > * Best-effort restart of a hung Serena server for `projectDir`: if a process
37
- > * exists it is (presumably hung) killed, we wait ~1s, then re-probe. Returns
38
- > * whether a live process remains afterwards. Never throws; budget < ~2s.
39
- > * There is no documented way to reconnect a stdio MCP server mid-session, so
40
- > * a successful "restart" only happens if the host respawns the process.
41
- > */
42
- > function attemptSerenaRestart(projectDir) {
43
- > try {
44
- > if (isSerenaProcessAlive(projectDir)) {
45
- > try { execSync(`pkill -f '${serenaProcPattern(projectDir)}'`, { stdio: 'pipe' }); } catch {}
46
- > try { execSync('sleep 1'); } catch {}
47
- > }
48
- > return isSerenaProcessAlive(projectDir);
49
- > } catch {
50
- > return false;
51
- > }
52
- > }
53
- > ```
54
-
55
- ### S6 — Live reproduction: the ValueError trigger
56
- Tool result from `mcp__serena__get_symbols_overview` on `lib/hooks/lib/serena.js`, this session, 2026-07-07
57
- > `Error executing tool get_symbols_overview: ValueError: Cannot extract symbols from file lib/hooks/lib/serena.js. Active languages: ['bash', 'markdown', 'yaml']`
58
-
59
- ### S7 — Live reproduction: the disconnect notice
60
- System reminder, this session, immediately after S6, 2026-07-07
61
- > "The following MCP servers have disconnected. Their instructions above no longer apply: serena"
62
- > "The following deferred tools are no longer available (their MCP server disconnected). Do not search for them — ToolSearch will return no match: mcp__serena__..." (full tool list)
63
-
64
- ### S8 — Live reproduction: process list
65
- `ps aux | grep -i serena | grep -v grep`, this session, 2026-07-07
66
- > ```
67
- > ...python .../bin/serena start-mcp-server --context claude-code --project /Users/davidtaylor/Repositories/portfolio_v2
68
- > ...python .../bin/serena start-mcp-server --context claude-code --project /Users/davidtaylor/Repositories/gauntlet/demand-letter
69
- > ```
70
- > (No entry for `/Users/davidtaylor/Repositories/bootstrap-claude`.)
71
-
72
- ### S9 — Live reproduction: corrupted health state
73
- `~/.claude/state/lsp-ready-6d7a97f1dd99`, read this session, 2026-07-07
74
- > ```json
75
- > "health": {
76
- > "should_enforce": true,
77
- > "healthy": false,
78
- > "error_count": 2,
79
- > "last_error": "Error executing tool get_symbols_overview: ValueError: Cannot extract symbols from file lib/hooks/serena-usage-tracker.js. Active languages: ['bash', 'markdown', 'yaml']",
80
- > "last_check": 1783446017493,
81
- > "notified": false
82
- > }
83
- > ```
84
-
85
- ### S12 — Auto Memory: `hooks/serena-health-tracking`
86
- `~/.claude/projects/-Users-davidtaylor-Repositories-bootstrap-claude/memory/hooks_serena-health-tracking.md` (read via `mcp__serena__read_memory`), 2026-07-07
87
- > "There is NO documented way to reconnect a stdio MCP server mid-session; 'restart' is best-effort only. Fail-open + success-based recovery is the guaranteed path."
@@ -1,126 +0,0 @@
1
- ---
2
- topic: how to improve the wiki tooling. Find examples of 'second brains' on the internet and consider what types of improvements could be made to our wiki setup to improve memory handling and general project setup. There have for sure been developments since the original wiki gist. Areas for improvement could potentially include infrastructure, skills, hooks, prompting, etc.
3
- slug: wiki-tooling-improvements
4
- researched: 2026-07-06
5
- sources: [./sources.md]
6
- ---
7
-
8
- # Research: Improving the LLM Wiki tooling — what's new since the Karpathy gist
9
-
10
- > This repo's `raw/llm-wiki.md` faithfully implements Andrej Karpathy's original LLM Wiki gist (published 2026-04-04 — three months before this research, not years). The ecosystem around that gist moved fast: at least four public projects (`claude-obsidian`, `ar9av/obsidian-wiki`, `MehmetGoekce/llm-wiki`, plus Claude Code's own **native Auto Memory** feature shipped by Anthropic) have independently converged on the same three gaps this repo's wiki does not yet cover — **session-to-session handoff (a "hot cache")**, **provenance/confidence tagging on claims**, and **concurrent-writer safety**. Separately, Claude Code itself gained a first-party memory system (the one *this very session* is using) that this repo's `wiki/` has no integration point for. The highest-leverage, lowest-cost next steps are: (1) add a `wiki/hot.md` session-handoff cache read at the start of every wiki operation, (2) formally activate the `confidence`/provenance frontmatter keys `wiki/conventions.md` already reserves-but-doesn't-use, and (3) write a short bridging convention so Claude Code's native Auto Memory (cross-session, cross-project) and this repo's wiki (per-project, git-versioned) don't silently duplicate or contradict each other. Heavier infrastructure (Mem0/Zep/Hindsight-style vector/graph memory layers, qmd local search) is available and mature but not yet justified at this repo's current wiki scale (empty scaffold, no ingested sources).
11
-
12
- ## Research Questions
13
-
14
- 1. What has changed in the public "second brain" / personal-knowledge-management ecosystem since Karpathy's LLM Wiki gist, and which of those changes are directly portable to this repo's wiki schema?
15
- 2. What do productized implementations of the *same* gist (built by other people, independently) do differently or additionally — and which of those differences look like genuine improvements rather than just different taste?
16
- 3. Has Claude Code itself (the harness this repo targets) grown built-in memory/context features since the gist, and does this repo's wiki architecture account for them?
17
- 4. What do dedicated agent-memory frameworks (Mem0, Zep/Graphiti, Letta/MemGPT, Hindsight, A-Mem) offer that a pure-markdown wiki doesn't — and is any of it worth adopting here, or is markdown-only still the right call at this repo's scale?
18
- 5. Concretely, what infrastructure, skill, hook, and prompting changes would most improve this repo's wiki tooling, ranked by cost vs. benefit?
19
-
20
- ## Current State (Codebase)
21
-
22
- This repo (`bootstrap-claude`) is a **template/scaffolding package**, not a working wiki instance — `wiki/` in this repo is empty (no knowledge pages, no work items; confirmed via `wiki/index.md` placeholder text "_(none yet)_" across all sections). The actual wiki pattern lives in three places:
23
-
24
- - **`raw/llm-wiki.md`** — a verbatim copy of Karpathy's gist (the idea file). Explicitly says "this document is intentionally abstract" and defers all tooling specifics to the implementer.
25
- - **`wiki/conventions.md`** — this repo's own concrete implementation of the pattern: atomic pages, stable IDs, typed links (`rel::[[target]]`), and a **frontmatter namespace that already reserves but does not populate** `confidence`, `tier`, `last_verified`, `supersedes`, `superseded_by`, `scope` — explicitly called out as "populated later by overlays." The doc also explicitly name-drops the exact overlays this research was asked to investigate: *"so the heavier overlays (confidence scoring, knowledge lifecycle, hybrid search, A-Mem-style link discovery) can be added later as zero-migration add-ons."* This means the repo's own authors already anticipated this research direction and pre-wired the frontmatter for it — the gap is that no skill or hook actually populates these fields yet.
26
- - **`lib/skills/wiki-*`** (9 skills: ingest, query, lint, archive, rotate-log, tidy) — implement Ingest/Query/Lint from the gist. No skill currently implements **session handoff** (a "what changed last time" cache) or **provenance tagging**.
27
- - **`lib/hooks/`** — 14 hook scripts, overwhelmingly focused on **Serena-first code navigation enforcement** and a sophisticated **fail-open health-tracking system** (`serena-usage-tracker.js` classifies tool-level vs. transport-level failures, attempts one restart, auto-recovers). This fail-open pattern (assume healthy, only disable enforcement on confirmed transport failure, auto-restore on next success) is a strong, reusable design — and it's a template for how a future "wiki-lock" or memory-plugin health check should behave, but currently nothing in `lib/hooks/` touches `wiki/` file safety, wiki auto-commit, or memory injection.
28
- - **Skills library is broad** (60+ skills: requirements, decisions, tasks, UAT, bugs, roadmaps, research, evals, security-audit, power-mode multi-agent orchestration) — meaning this repo already runs **heavy concurrent subagent activity** (`power-mode`, `tackle`, `now`) that could plausibly write to the same wiki family index or log file from multiple agents at once, which is exactly the failure mode other implementers have hit and started addressing with file locking (see Key Findings below).
29
- - This session itself is running inside **Claude Code's native Auto Memory system** (see the `MEMORY.md`/per-type memory files described in this session's own system prompt) — a first-party feature that postdates this repo's wiki design and has zero cross-references to it anywhere in `CLAUDE.md` or the wiki schema.
30
-
31
- ## Key Findings
32
-
33
- ### 1. Claude Code shipped a first-party memory system that this repo's wiki doesn't acknowledge
34
-
35
- Anthropic's Claude Code now ships **Auto Memory**: typed memory files (`user`, `feedback`, `project`, `reference` — the exact four types this session is instructed to use) stored under `~/.claude/projects/<hash>/memory/`, indexed by a `MEMORY.md`, auto-loaded at session start, and **specifically exempted from context compaction** — it survives summarization along with `CLAUDE.md` and any active skill [S17]. Anthropic's own official best-practices docs describe this as one of two now-standard patterns (the other being subagent delegation) for managing context across long sessions [S6]. Community write-ups independently describe the same architecture: "anything loaded from disk at startup comes back, anything that arrived through conversation gets summarized away" [S17], and note that **per-subagent** memory directories exist too (`.claude/agent-memory/<name>/MEMORY.md`, first 200 lines/25KB auto-injected) [S15].
36
-
37
- This is architecturally adjacent to, but distinct from, this repo's wiki:
38
- - **Auto Memory** is cross-project, un-versioned (lives outside the git repo, in `~/.claude/projects/`), small (200-line/25KB budget), and optimized for *behavioral* facts (how the user likes to work, standing feedback).
39
- - **This repo's wiki** is per-project, git-versioned, unbounded in size, and optimized for *domain* knowledge (sources, decisions, tasks).
40
-
41
- No file in this repo currently tells Claude Code how these two systems should divide responsibility, which risks two failure modes already documented in the wild: (a) duplicating the same fact in both places, or (b) a `feedback`-type Auto Memory entry silently overriding a `wiki/knowledge/` page's stated convention with no cross-reference. *(inference — no primary source ties this specific failure to this specific repo; the risk is inferred from the architecture, not observed)*.
42
-
43
- ### 2. Every independent reimplementation of the same gist converged on a "hot cache" / session-handoff file
44
-
45
- At least three separate teams, building on the same Karpathy gist, independently added a mechanism this repo lacks: a small, always-read-first file summarizing "what happened last session."
46
-
47
- - **`claude-obsidian`** (AgriciDaniel, MIT, 358+ GitHub stars) calls it `wiki/hot.md` — "At the end of every session, Claude updates `wiki/hot.md` with a compact context summary. The next session reads that file first. You never rebuild context." [S10, S11]. The file format is small and structured: `Last Updated`, `Key Recent Facts`, `Recent Changes` (created/updated/flagged), `Active Threads` [S12].
48
- - **`MehmetGoekce/llm-wiki`** independently calls this an "L1/L2 cache architecture": "Auto-loaded rules in memory (L1) + deep knowledge in the wiki (L2)... the key insight Karpathy's gist does not mention" [S14].
49
- - This maps directly onto Claude Code's own compaction behavior described above [S17] — a hot-cache file is essentially a hand-rolled version of what Auto Memory now does natively, but scoped to wiki-domain state rather than user-behavior state.
50
-
51
- This repo's `wiki/log.md` is chronological (append-only, all history) but is not designed to be *read first* as a compact summary — a session resuming work has to scan or grep it. A `wiki/hot.md`-equivalent (or a "recent activity" section auto-maintained at the top of `wiki/index.md`) is the single most directly portable idea from this research.
52
-
53
- ### 3. Provenance/confidence tagging is a recurring, cheap addition other implementers already built — and this repo already reserved the frontmatter keys for it
54
-
55
- - **`ar9av/obsidian-wiki`** tags every claim as `extracted` (default), `^[inferred]` (LLM synthesis), or `^[ambiguous]` (sources disagree), with a `provenance:` frontmatter block summarizing the mix per page, and a `wiki-lint`-equivalent that **flags pages drifting into mostly speculation** [S13].
56
- - This is not a novel idea invented for AI wikis — it's the same instinct behind this research skill's own Phase 5 rule ("mark unsupported claims as *(inference — no primary source)*" rather than fabricating a citation), just formalized as page-level frontmatter instead of an inline note.
57
- - `wiki/conventions.md` in this repo **already reserves** `confidence`, `tier`, `last_verified` as frontmatter keys "populated later by overlays... safe to ignore until then" [S2] — meaning this is a zero-migration addition: no existing file needs to change, only `/wiki-ingest` and `/wiki-lint` need new instructions to populate and check these fields.
58
-
59
- ### 4. Multi-writer safety for concurrent wiki edits is an active, only-partially-solved problem — relevant given this repo's heavy subagent orchestration
60
-
61
- - `claude-obsidian` v1.7 added **per-file advisory locking** (`scripts/wiki-lock.sh`) specifically because "parallel ingest sub-agents acquire locks before writes" was previously a "latent multi-writer corruption hole" [S10, S20].
62
- - A community report (r/hermesagent) describes a simpler ad-hoc pattern for two-agent concurrent edits: a YAML soft-lock (`locked: true` set/cleared atomically around the edit, with a 30-minute staleness override and a log entry on override) plus an append-only "Proposals" section so agents that can't coordinate can still both write without conflicting, since appends never collide [S21].
63
- - `MehmetGoekce/llm-wiki`'s docs explicitly warn: "If you have multiple Claude sessions writing to wiki files simultaneously, concurrent edits can cause conflicts. Treat wiki files as a shared resource" [S14].
64
- - Claude Code's own Agent Teams / worktree-isolation feature sidesteps this for *code* files by giving each subagent an isolated git worktree [S9-adjacent finding, from MindStudio], but this repo's `wiki/index.md`, family `index.md` files, and `wiki/log.md` are **shared append/edit targets by design** (every ingest touches the same index) — worktree isolation doesn't apply to a single logical file two agents both need to update.
65
- - **This repo's own risk surface**: `power-mode` and `tackle` already run multiple concurrent subagents, and several wiki skills (`/wiki-ingest`, `/task-add`, `/decision-create`) all write to shared index files (`wiki/index.md`, family `index.md`s, `wiki/log.md`). If two subagents ever ran a wiki-writing skill concurrently, this is the exact failure mode others have already hit.
66
-
67
- ### 5. Local hybrid search (qmd) — already correctly identified in the gist as optional, and still the right call to defer
68
-
69
- The original gist recommends `tobi/qmd` — a local CLI combining BM25 + vector + LLM re-ranking, with an MCP server interface — once a wiki "grows past a few hundred pages" [S1, S18]. Nothing has since obsoleted this recommendation; if anything qmd has matured (active development, MCP integration, documented "cuts token usage by 95%+" via retrieval instead of full-file reads) [S18]. But **this repo's actual wiki content is currently empty** — `wiki/index.md`-as-search is not yet a bottleneck anywhere in this template repo or (presumably) in any project it's been synced into. This is a "when you need it" addition, not a now addition.
70
-
71
- ### 6. Dedicated agent-memory frameworks (Mem0, Zep/Graphiti, Letta, Hindsight, A-Mem) are a different tool for a different job, not a wiki replacement
72
-
73
- The 2025-2026 wave of memory frameworks is real and mature (Mem0 raised $24M, is AWS Agent SDK's default memory provider, 186M API calls in Q3 2025 [S7, S8]; Zep's Graphiti adds temporal knowledge graphs on Neo4j [S7]; Letta/MemGPT's own August 2025 benchmark found a plain-filesystem agent beat Mem0's graph variant on long-context recall, arguing "agents are post-trained to be good at iterative file search, so specialized memory systems add little" [S7] — a notable data point *against* over-engineering memory infra). Hindsight specifically targets the exact gap flagged in Finding 4 — cross-subagent shared memory in Claude Code — via a hooks + MCP plugin giving every subagent read/write access to one memory bank instead of N siloed `MEMORY.md` files [S15, S16].
74
-
75
- All of these are optimized for **conversational/episodic recall at scale** (chat histories, user preferences across sessions) — a genuinely different problem from **curated, versioned, cross-referenced domain knowledge**, which is what this repo's wiki is for. Letta's own finding above is direct evidence that "just use files, well-organized" is a defensible, not backwards, choice at this repo's scale. The right time to reach for one of these is if/when a specific concrete pain point emerges (e.g., subagents in `power-mode` genuinely losing shared context across a long multi-wave run) — not preemptively.
76
-
77
- ## Constraints
78
-
79
- - **Any change must be additive, not a rewrite.** `wiki/conventions.md` was explicitly written to allow exactly this kind of overlay ("zero-migration add-ons") — new frontmatter keys, new skill instructions — without touching existing files or breaking the "raw/ is immutable" and "atomic pages" rules already in force.
80
- - **This is a template repo, not a live wiki** — changes here are to the *scaffold* (`lib/scripts/templates/wiki/`, `lib/skills/wiki-*`, `lib/hooks/`) that gets synced into *other* projects' `wiki/` directories, not to this repo's own (empty) `wiki/`. Any recommendation must be implementable as a skill/hook/template change, not a one-off wiki edit.
81
- - **Copy-once vs. always-refresh semantics already exist** (`sync-wiki-scaffold.sh`) — new template files (e.g., a `hot.md` stub) need to be classified into one of these two buckets correctly, or updates will either clobber project-owned content or never propagate fixes.
82
- - **No new required infrastructure/dependencies.** The gist's own philosophy — and this repo's existing zero-dependency wiki (Serena, Brave, Context7 aside) — argues against introducing a vector DB, graph DB, or SaaS memory layer as a *default*. Anything heavier should be optional, documented, and opt-in (mirroring how `qmd` is already framed as optional in `raw/llm-wiki.md`).
83
- - **Multi-agent write safety must not slow down the common (single-agent) case.** A locking mechanism modeled on the existing fail-open Serena health-tracking pattern (`lib/hooks/lib/serena.js`) — enforce by default, degrade gracefully on failure, auto-recover — is the established idiom in this codebase and should be reused rather than inventing a new failure-handling philosophy.
84
-
85
- ## Solution Comparison
86
-
87
- | Criteria | A. Hot-cache session handoff (`wiki/hot.md` or index "Recent Activity" section) | B. Provenance/confidence frontmatter activation | C. Multi-writer file locking for wiki writes | D. Bridge doc: Auto Memory ↔ wiki division of responsibility | E. Adopt a dedicated memory framework (Hindsight/Mem0) for subagent sharing |
88
- |---|---|---|---|---|---|
89
- | **Approach** | New small file/section, updated at end of each ingest/query/task-touching skill, read first by `/primer` and every wiki skill | Populate the already-reserved `confidence`/`tier`/`last_verified` keys on write; `/wiki-lint` flags high-inference pages | Advisory lock file per shared index, acquired/released around writes, stale-lock override + log entry (mirrors `serena.js` fail-open pattern) | Short section in `CLAUDE.md`/`wiki/conventions.md` stating what belongs in Auto Memory vs. wiki, with a rule against duplicating the same fact in both | Install Hindsight (or similar) as an MCP plugin giving `power-mode`/`tackle` subagents a shared, queryable memory bank |
90
- | **Pros** | Matches convergent design from 3+ independent implementers [S10,S14]; trivial to implement; directly reduces "rebuild context every session" cost this repo's own `/primer` skill already exists to solve | Zero new files/keys — frontmatter already declared; makes contradiction/staleness detection in `/wiki-lint` concrete instead of vibes-based; cheap | Directly prevents a documented real failure mode (concurrent-write corruption) [S10,S21] that this repo's concurrency features (`power-mode`) can trigger | Prevents silent duplication/contradiction between two systems that already coexist in every session; near-zero cost (documentation only) | Solves cross-subagent memory sharing more robustly than ad hoc files; benchmarked, maintained, used elsewhere in the Claude Code ecosystem [S15,S16] |
91
- | **Cons** | One more file to keep in sync; needs a clear "who updates this and when" rule or it goes stale like any cache | Discipline-dependent — an agent can always skip tagging; needs `/wiki-lint` enforcement to have teeth | Advisory locks are not bulletproof (community example calls it "not bulletproof, but... plenty" [S21]); adds a small step to every wiki write | Doesn't solve any concrete problem by itself — pure risk-reduction / clarity, no immediate feature win | New runtime dependency (MCP server, possibly hosted service or local daemon); real ongoing infra to run and reason about; overkill until subagent memory-sharing is an observed pain point, not a hypothetical one |
92
- | **Complexity** | Low | Low | Medium | Low | High |
93
- | **Dependencies** | None (markdown + skill instruction changes) | None | None (plain files + one small hook/script, following existing `serena.js` pattern) | None | New MCP server + (optionally) hosted backend or local daemon |
94
- | **Codebase fit** | Excellent — directly extends `/primer` and the existing Ingest/Query/Lint skills | Excellent — activates dormant, already-designed convention | Good — mirrors the existing fail-open health-tracking idiom in `lib/hooks/lib/serena.js` | Excellent — pure documentation, no structural change | Moderate — would sit alongside existing MCPs (Serena/Brave/Context7) but changes what "the wiki" means (adds a non-file-based memory layer this repo has so far deliberately avoided) |
95
- | **Maintenance** | Low — one skill instruction to keep current | Low — enforcement lives in existing `/wiki-lint` | Medium — lock file lifecycle needs periodic sanity (stale-lock cleanup), same shape as existing Serena health state files | Near-zero | Ongoing — a new external dependency to monitor, version, and pay for (if hosted) |
96
-
97
- ## Recommendation
98
-
99
- **Adopt A, B, and D now; hold C and E until a concrete trigger.**
100
-
101
- 1. **A — hot cache** and **D — the bridging doc** are strict no-regret wins: no new dependencies, no schema migration, and both close a gap that Claude Code's own native features (Auto Memory, compaction-survival) and every other public reimplementation of this exact gist have already converged on independently. Do these together, since the hot-cache file is itself a candidate for the "what belongs where" line D draws (hot cache = wiki-domain session state; Auto Memory = cross-project user/feedback state).
102
- 2. **B — provenance tagging** is next: it activates frontmatter this repo's own conventions doc already promised ("zero-migration add-ons"), and gives `/wiki-lint` a concrete, checkable signal instead of relying on the LLM's judgment alone to catch drift into speculation.
103
- 3. **C — multi-writer locking** should be built, but only scoped to the specific shared files that concurrent skills actually touch (`wiki/index.md`, each family `index.md`, `wiki/log.md`) — not every wiki page, since most pages are written by exactly one skill invocation at a time. Model it directly on the existing `serena.js` fail-open pattern (enforce by default, one-time degrade notice on confirmed failure, auto-recover) rather than inventing new semantics. This is worth doing given `power-mode`/`tackle` already run concurrent subagents against a repo that (per this same research skill's own instructions) requires touching shared index files on every wiki operation.
104
- 4. **E — a dedicated memory framework (Hindsight, Mem0, etc.)** should be treated as a documented *option*, not a default: add a short note in `raw/llm-wiki.md`'s "Optional: CLI tools" section (alongside the existing `qmd` mention) pointing at Hindsight specifically for the cross-subagent-memory-sharing use case, but do not wire it into the template's default skill/hook set. Letta's own benchmark finding — that a well-organized filesystem approach can *beat* a dedicated graph-memory framework on long-context recall [S7] — is direct evidence this restraint is well-founded, not conservative-for-its-own-sake.
105
-
106
- **Implementation outline** (for A/B/D, as a follow-on task):
107
- - Add `wiki/hot.md` to `lib/scripts/templates/wiki/` (copy-once — project-owned once created) with the format Karpathy-derivative projects converged on: `Last Updated`, `Key Recent Facts`, `Recent Changes`, `Active Threads` [S12].
108
- - Update `/wiki-ingest`, `/task-add`/`task-update`, `/decision-finalize`, and any skill that changes wiki state to append/refresh `wiki/hot.md` as a final step.
109
- - Update `/primer` (already exists specifically to "refresh codebase context via Serena memories") to read `wiki/hot.md` first, before Serena memories.
110
- - Add a `confidence: extracted | inferred | ambiguous` frontmatter convention to `wiki/conventions.md`'s existing (currently unused) "Reserved keys" section, and teach `/wiki-ingest` to set it and `/wiki-lint` to flag pages that are mostly `inferred`/`ambiguous` with no `extracted` claims.
111
- - Add a short "Auto Memory vs. this wiki" subsection to `CLAUDE.md`'s LLM Wiki section: Auto Memory owns cross-project user/feedback facts; the wiki owns per-project domain/source/decision knowledge; never write the same fact to both.
112
-
113
- **Risks and mitigations**:
114
- - *Hot cache goes stale / becomes another maintenance burden* → mitigate by keeping it small (the gist's own precedent caps it at ~500 words [S12]) and regenerating it fully each time rather than appending, so staleness self-corrects.
115
- - *Provenance tagging gets skipped under time pressure* → mitigate by making `/wiki-lint` actively check for it (a missing `confidence` field on a newly-ingested page is itself a lint finding), not just documenting the convention and hoping.
116
- - *Locking adds friction to the common single-agent case* → mitigate by making the lock acquire/release near-instant (a file touch/delete, per the community pattern [S21]) and only wrapping the specific shared-index write, not the whole skill invocation.
117
-
118
- **Alternative if constraints change**: if a future project synced from this template accumulates enough subagent-driven wiki writes that ad hoc locking proves insufficient (repeated corruption, not just theoretical risk), revisit Hindsight or a similar shared-memory-bank MCP as the concurrency layer instead of hand-rolled locks — at that point the maintenance cost of running dedicated memory infra will be justified by an observed, not hypothetical, problem.
119
-
120
- ## Next Steps
121
-
122
- - To create a task for the highest-priority items: `/task-add "Add wiki/hot.md session-handoff cache to wiki scaffold templates, updated by wiki-writing skills and read first by /primer" --roadmap <if one exists>`
123
- - A second task for provenance tagging: `/task-add "Activate confidence/provenance frontmatter (extracted/inferred/ambiguous) in wiki-ingest and enforce via wiki-lint"`
124
- - A third, smaller task for the bridging doc: `/task-add "Document Auto Memory vs. wiki-knowledge division of responsibility in CLAUDE.md LLM Wiki section"`
125
- - If the multi-writer locking risk feels premature to act on without more evidence: run `/wiki-lint` (once this repo or a synced project has real content) periodically and watch specifically for signs of concurrent-write corruption before committing to building C.
126
- - Run `/wiki-ingest raw/research/wiki-tooling-improvements/index.md` to fold this research into the knowledge base as a proper wiki page (likely `wiki/knowledge/concepts/wiki-tooling-improvements.md`, cross-linked from `wiki/knowledge/concepts/` and touching an entity page for `raw/llm-wiki.md` itself if one gets created).
@@ -1,73 +0,0 @@
1
- ---
2
- topic: how to improve the wiki tooling. Find examples of 'second brains' on the internet and consider what types of improvements could be made to our wiki setup to improve memory handling and general project setup. There have for sure been developments since the original wiki gist. Areas for improvement could potentially include infrastructure, skills, hooks, prompting, etc.
3
- slug: wiki-tooling-improvements
4
- researched: 2026-07-06
5
- ---
6
-
7
- # Primary Sources — Improving the LLM Wiki tooling
8
-
9
- | ID | Type | Locator | Accessed | What it contributed |
10
- |----|------|---------|----------|---------------------|
11
- | S1 | codebase | `raw/llm-wiki.md` | 2026-07-06 | Karpathy's original gist text as implemented in this repo; the "Optional: CLI tools" section already recommends `qmd` for hybrid search once a wiki grows large |
12
- | S2 | codebase | `wiki/conventions.md` | 2026-07-06 | Confirms `confidence`, `tier`, `last_verified`, `supersedes`, `superseded_by`, `scope` are reserved-but-unused frontmatter keys, explicitly intended for "confidence scoring, knowledge lifecycle, hybrid search, A-Mem-style link discovery" as future zero-migration overlays |
13
- | S3 | codebase | `lib/hooks/README.md` | 2026-07-06 | Documents the fail-open Serena health-tracking pattern (`serena-usage-tracker.js`, `lib/serena.js`): enforce by default, classify tool-level vs transport-level failures, one restart attempt, auto-recover on next success — used as the design template for a proposed wiki-locking hook |
14
- | S4 | codebase | `README.md` | 2026-07-06 | Confirms this repo is a template/scaffold package (not a live wiki instance); confirms copy-once vs always-refresh semantics for wiki templates via `sync-wiki-scaffold.sh` |
15
- | S5 | codebase | `lib/skills/wiki-query/SKILL.md` | 2026-07-06 | Confirms current Query skill design: reads `wiki/index.md` first, no session-handoff/hot-cache step exists in current skill set |
16
- | S6 | web | https://code.claude.com/docs/en/best-practices | 2026-07-06 | Anthropic's official Claude Code best-practices docs: recommends customizing compaction behavior via CLAUDE.md instructions, delegating research to subagents to protect main context |
17
- | S7 | web | https://codepointer.substack.com/p/agent-memory-systems-and-knowledge | 2026-07-06 | Comparison of Letta/Mem0/Zep/Cognee architectures; quotes Letta's Aug 2025 "Is a Filesystem All You Need?" finding that a plain-file agent scored 74.0% vs Mem0's graph variant's 68.5% on LOCOMO, arguing specialized memory adds little when agents are good at iterative file search |
18
- | S8 | web | https://mem0.ai/blog/state-of-ai-agent-memory-2026 | 2026-07-06 | Mem0's own 2026 benchmark report; confirms Mem0's ECAI 2025 paper (arXiv:2504.19413), adoption scale (AWS Agent SDK default provider, 186M API calls Q3 2025) |
19
- | S9 | web | https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f | 2026-07-06 | The original gist itself, plus comments; confirms publish date of 2026-04-04 (per aggregating articles) and ongoing community feedback thread |
20
- | S10 | web | https://github.com/AgriciDaniel/claude-obsidian | 2026-07-06 | Productized reimplementation of the same gist: confirms `wiki/hot.md` hot-cache mechanism, v1.7 per-file advisory locking (`scripts/wiki-lock.sh`) added to close a "latent multi-writer corruption hole," 15 Claude Code skills, methodology modes, provenance concepts |
21
- | S11 | web | https://claude-blog.md/blog/claude-obsidian-second-brain | 2026-07-06 | Describes claude-obsidian's hot-cache workflow in narrative form: "At the end of every session, Claude updates wiki/hot.md... The next session reads that file first. You never rebuild context." |
22
- | S12 | web | https://github.com/AgriciDaniel/claude-obsidian/blob/main/WIKI.md | 2026-07-06 | Exact `hot.md` file format/example: `Last Updated`, `Key Recent Facts`, `Recent Changes` (Created/Updated/Flagged), `Active Threads`, capped around ~500 words |
23
- | S13 | web | https://github.com/ar9av/obsidian-wiki | 2026-07-06 | Independent reimplementation with provenance tracking: every claim tagged `extracted` (default), `^[inferred]`, or `^[ambiguous]`; `provenance:` frontmatter block; wiki-lint flags pages drifting into mostly speculation |
24
- | S14 | web | https://github.com/MehmetGoekce/llm-wiki | 2026-07-06 | Independent reimplementation describing "L1/L2 cache architecture" (auto-loaded rules = L1, deep wiki = L2) as "the key insight Karpathy's gist does not mention"; explicit warning that concurrent Claude sessions writing to wiki files simultaneously can cause conflicts |
25
- | S15 | web | https://hindsight.vectorize.io/blog/2026/05/06/claude-code-subagents-shared-memory | 2026-07-06 | Documents Claude Code's native per-subagent memory field (`.claude/agent-memory/<name>/MEMORY.md`, first 200 lines/25KB auto-injected) and the cross-subagent silo problem it doesn't solve; Hindsight's shared-bank solution |
26
- | S16 | web | https://hindsight.vectorize.io/sdks/integrations/claude-code | 2026-07-06 | Hindsight's Claude Code plugin architecture: hooks (auto recall/retain) + MCP server (explicit `agent_knowledge_*` tools) + a skill for subagent creation |
27
- | S17 | web | https://claudefa.st/blog/guide/mechanics/context-management | 2026-07-06 | Describes Claude Code's compaction behavior precisely: CLAUDE.md, unscoped rules, and Auto Memory (first 200 lines/25KB of MEMORY.md) are re-injected from disk after compaction; conversation-arrived context is not |
28
- | S18 | web | https://github.com/tobi/qmd | 2026-07-06 | Confirms qmd (the tool named in the original gist) is still actively maintained: hybrid BM25 + vector + LLM re-ranking, CLI + MCP server interfaces |
29
- | S19 | web | https://arxiv.org/abs/2502.12110 | 2026-07-06 | A-MEM paper abstract: Zettelkasten-inspired dynamic memory organization for LLM agents with "memory evolution" (existing notes update when new ones are linked) — the academic root of the "A-Mem-style link discovery" already name-checked in this repo's `wiki/conventions.md` |
30
- | S20 | web | https://skillsllm.com/skill/claude-obsidian | 2026-07-06 | claude-obsidian v1.7 "Compound Vault" changelog: hybrid retrieval (contextual prefix + BM25 + cosine rerank per Anthropic's Sept 2024 contextual retrieval research) plus the per-file advisory locking release note |
31
- | S21 | web | https://www.reddit.com/r/hermesagent/comments/1tiec44/hermes_agent_claude_obsidian_and_hindsight_walk/ | 2026-07-06 | Community-reported ad hoc two-agent concurrent-edit pattern: YAML soft-lock (set true/edit/set false in one write), 30-minute staleness override with log entry, append-only "Proposals" section for lock-free concurrent additions |
32
-
33
- ## Excerpts
34
-
35
- ### S2 — wiki/conventions.md (this repo)
36
- `wiki/conventions.md`
37
- > The rules that govern every page in this wiki. They exist so the knowledge base stays navigable as it grows, and so the heavier overlays (confidence scoring, knowledge lifecycle, hybrid search, A-Mem-style link discovery) can be added **later as zero-migration add-ons**.
38
-
39
- ### S7 — Agent Memory Systems and Knowledge Graphs (codepointer.substack.com)
40
- https://codepointer.substack.com/p/agent-memory-systems-and-knowledge
41
- > Letta's "Is a Filesystem All You Need?" post (Aug 2025) dumped LOCOMO (a multi-session dialogue recall benchmark) conversation transcripts into files attached to a plain agent and scored 74.0%, above the 68.5% for Mem0's graph variant (arXiv 2504.19413, Apr 2025). Letta argues that agents are post-trained to be good at iterative file search, so specialized memory systems add little.
42
-
43
- ### S10 — claude-obsidian GitHub repo
44
- https://github.com/AgriciDaniel/claude-obsidian
45
- > Can multiple people edit the same vault safely? Yes (v1.7+). Per-file advisory locking via scripts/wiki-lock.sh prevents concurrent writes from corrupting pages. Parallel ingest sub-agents acquire locks before writes.
46
-
47
- ### S11 — claude-blog.md article
48
- https://claude-blog.md/blog/claude-obsidian-second-brain
49
- > The hot cache is the most underrated feature. At the end of every session, Claude updates wiki/hot.md with a compact context summary. The next session reads that file first. You never rebuild context. The wiki already knows.
50
-
51
- ### S12 — claude-obsidian WIKI.md
52
- https://github.com/AgriciDaniel/claude-obsidian/blob/main/WIKI.md
53
- > --- type: meta title: "Hot Cache" updated: 2026-04-07T14:30:00 --- # Recent Context ## Last Updated 2026-04-07 — Ingested 3 new YouTube transcripts ## Key Recent Facts - [Most important recent takeaway] - [Second most important] ## Recent Changes - Created: [[New Page 1]], [[New Page 2]] - Updated: [[Existing Page]] (added section on X) - Flagged: Contradiction between [[Page A]] and [[Page B]] on topic Y ## Active Threads - User is currently researching [topic] - Open question: [thing still being investigated]
54
-
55
- ### S13 — ar9av/obsidian-wiki
56
- https://github.com/ar9av/obsidian-wiki
57
- > Provenance tracking. Every claim on a wiki page is tagged: extracted (default), ^[inferred] (LLM synthesis), or ^[ambiguous] (sources disagree). A provenance: block in the frontmatter summarizes the mix per page, and wiki-lint flags pages that drift into mostly speculation.
58
-
59
- ### S14 — MehmetGoekce/llm-wiki
60
- https://github.com/MehmetGoekce/llm-wiki
61
- > If you have multiple Claude sessions writing to wiki files simultaneously, concurrent edits can cause conflicts. Treat wiki files as a shared resource... L1/L2 architecture. Auto-loaded rules in memory (L1) + deep knowledge in the wiki (L2). No other tool has this.
62
-
63
- ### S15 — Hindsight blog: subagent shared memory
64
- https://hindsight.vectorize.io/blog/2026/05/06/claude-code-subagents-shared-memory
65
- > Each subagent's memory directory is siloed from every other subagent's. The code-reviewer doesn't see what the security-auditor learned, and vice versa. A shared memory layer (Hindsight on a single project bank) gives every subagent — plus the orchestrator — one common, accumulating understanding.
66
-
67
- ### S17 — claudefa.st context management guide
68
- https://claudefa.st/blog/guide/mechanics/context-management
69
- > The short version: anything loaded from disk at startup comes back, and anything that arrived through the conversation gets summarized away. Your project-root CLAUDE.md, your unscoped rules, and your auto memory (Claude's own notes, the first 200 lines or 25KB of MEMORY.md) are all re-injected from disk after compaction.
70
-
71
- ### S21 — r/hermesagent concurrent-edit thread
72
- https://www.reddit.com/r/hermesagent/comments/1tiec44/hermes_agent_claude_obsidian_and_hindsight_walk/
73
- > Read, set true, edit, set false in the same write. Stale lock (updated >30 min old) gets overridden with a log entry... Append-only Proposals section with three-party threads. Both agents can add proposals to the bottom without coordinating, because appends don't conflict.
Binary file