@alekra1/llm-wiki 1.0.0 → 1.0.1

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 (5) hide show
  1. package/CLAUDE.md +4 -5
  2. package/README.md +74 -20
  3. package/bin/setup.js +11 -11
  4. package/package.json +3 -11
  5. package/wiki/HOWTO.md +2 -0
package/CLAUDE.md CHANGED
@@ -6,14 +6,13 @@ This project uses an LLM wiki at `./wiki/` as its living context layer.
6
6
  `wiki/_active/now.md` and recent entries from `wiki/log.md`. If unfamiliar with the
7
7
  wiki conventions, also read `wiki/HOWTO.md`. Drill into other pages only as needed.
8
8
 
9
- **While working:** update the wiki per `wiki/HOWTO.md`. Use supersession, not deletion,
10
- for contradictions. Add a `log.md` entry for each wiki change.
9
+ **While working:** update the wiki immediately when anything significant happens — do not batch updates for later. Triggers: a decision is made, a preference is stated, a pitfall is found, a task changes, a discovery occurs. Write the `wiki/log.md` entry at the moment it happens, not at session end. Use supersession, not deletion, for contradictions.
11
10
 
12
- **On session end:** rewrite `wiki/_snapshot.md` to reflect current state if anything changed this session. Run `/wiki-lint` only when the user asks for it.
11
+ **On session end:** rewrite `wiki/_snapshot.md` to reflect current state if anything changed. Run `/wiki-lint` only when the user asks for it.
13
12
 
14
13
  **Slash commands**: `/wiki-update` — write a wiki entry; `/wiki-lint` — run the lint
15
- checklist; `/wiki-snapshot` — refresh the snapshot mid-session. Hooks in
16
- `.claude/settings.json` automate the session-start reads and session-end prompt.
14
+ checklist; `/wiki-snapshot` — refresh the snapshot mid-session. The SessionStart hook
15
+ in `.claude/settings.json` auto-bootstraps context at the start of each session.
17
16
 
18
17
  **If you are a subagent** (spawned via API, orchestration tool, or CI — not an
19
18
  interactive CC session): hooks will not fire. Treat these instructions as your hooks.
package/README.md CHANGED
@@ -1,48 +1,102 @@
1
1
  # llm-wiki
2
2
 
3
- A markdown wiki template that gives LLM agents persistent, cross-session memory. Copy it into any project — agents read and write `wiki/` as a living brain that survives context resets and provider switches.
3
+ Gives LLM agents persistent, cross-session memory — a markdown wiki that agents read and write as a living brain. Survives context resets and provider switches. Zero tooling required.
4
4
 
5
5
  ## Install
6
6
 
7
+ **Step 1 — scaffold the wiki into your project:**
8
+
7
9
  ```bash
8
10
  npx @alekra1/llm-wiki
9
11
  ```
10
12
 
11
- This copies `wiki/` into your project, creates or appends to `CLAUDE.md`, and adds provider files (`AGENTS.md`, `GEMINI.md`, `.cursorrules`) if they don't exist.
13
+ This copies `wiki/` into your project, creates or appends to `CLAUDE.md`, and adds provider files (`AGENTS.md`, `GEMINI.md`, `.cursorrules`) if they don't already exist. Safe to run on existing projects — never overwrites.
14
+
15
+ **Step 2 — install the Claude Code plugin** (slash commands + session hooks):
12
16
 
13
- Then install the Claude Code plugin for slash commands:
14
17
  ```
15
18
  /plugin marketplace add Alekra1/llm-wiki
16
19
  /plugin install wiki@llm-wiki
17
20
  ```
18
21
 
19
- ## What's included
22
+ **Step 3 — fill in the snapshot:**
20
23
 
21
- | File/Dir | Purpose |
22
- |---|---|
23
- | `wiki/` | The wiki: snapshot, active tasks, decisions, preferences, pitfalls, workflows |
24
- | `CLAUDE.md` | Agent instructions for Claude Code |
25
- | `AGENTS.md` | Same for OpenAI Agents / Codex |
26
- | `GEMINI.md` | Same for Gemini |
27
- | `.cursorrules` | Same for Cursor |
28
- | `.claude/` | CC plugin: SessionStart hook + `/wiki-lint`, `/wiki-update`, `/wiki-snapshot` |
24
+ Open `wiki/_snapshot.md` and replace the placeholders with your project's current state. This is what the agent reads first every session.
25
+
26
+ That's it. Start a Claude Code session.
27
+
28
+ ---
29
29
 
30
30
  ## How it works
31
31
 
32
- On session start, the agent reads `wiki/_snapshot.md` (~300 tokens, ~30 seconds) and picks up exactly where the last session ended. No summaries to maintain — the wiki is the memory.
32
+ On session start, the SessionStart hook fires automatically and the agent reads `wiki/_snapshot.md` — one page, ~300 tokens, ~30 seconds. It picks up exactly where the last session ended.
33
+
34
+ As you work, the agent writes to the wiki: decisions in `wiki/decisions/`, preferences in `wiki/preferences/`, current task in `wiki/_active/`. Every change gets a line in `wiki/log.md`.
35
+
36
+ At session end, a Stop hook checks whether `wiki/log.md` was updated. If not, it prints a reminder in the terminal. The next SessionStart automatically catches any gaps from the previous session.
37
+
38
+ ---
39
+
40
+ ## Wiki structure
41
+
42
+ ```
43
+ wiki/
44
+ ├── _snapshot.md ← read first every session (~300 tokens)
45
+ ├── _active/
46
+ │ ├── now.md ← current task and blockers
47
+ │ └── open-questions.md ← unresolved questions
48
+ ├── decisions/ ← technical and design decisions
49
+ ├── preferences/ ← user preferences (style, tools, communication)
50
+ ├── workflows/ ← repeatable processes
51
+ ├── pitfalls/ ← known traps and how to avoid them
52
+ ├── architecture/ ← system overviews
53
+ ├── index.md ← catalog of all pages
54
+ ├── log.md ← append-only session log
55
+ ├── HOWTO.md ← full wiki conventions
56
+ └── EXAMPLES.md ← format examples for each page type
57
+ ```
33
58
 
34
- Agents write to the wiki as they work: decisions in `wiki/decisions/`, preferences in `wiki/preferences/`, active tasks in `wiki/_active/`. Every change gets a line in `wiki/log.md`.
59
+ ---
35
60
 
36
- Read `wiki/HOWTO.md` for conventions.
61
+ ## Slash commands (Claude Code)
37
62
 
38
- ## Slash commands (Claude Code plugin)
63
+ Installed by the CC plugin.
39
64
 
40
65
  | Command | What it does |
41
66
  |---|---|
42
- | `/wiki-update` | Write a new wiki entry |
43
- | `/wiki-lint` | Run the wiki health checklist |
44
- | `/wiki-snapshot` | Refresh the snapshot mid-session |
67
+ | `/wiki-update` | Write a structured wiki entry (routes to correct location automatically) |
68
+ | `/wiki-snapshot` | Rewrite `_snapshot.md` to reflect current state |
69
+ | `/wiki-lint` | Run the wiki health checklist — orphans, stale pages, contradictions, duplicates |
70
+
71
+ ---
45
72
 
46
73
  ## Provider support
47
74
 
48
- Works with any LLM that can read files. Entry-point files (`CLAUDE.md`, `AGENTS.md`, `GEMINI.md`, `.cursorrules`) contain identical instructions in each provider's expected format.
75
+ `npx @alekra1/llm-wiki` installs entry-point files for every major provider:
76
+
77
+ | File | Provider |
78
+ |---|---|
79
+ | `CLAUDE.md` | Claude Code |
80
+ | `AGENTS.md` | OpenAI Agents, Codex |
81
+ | `GEMINI.md` | Gemini |
82
+ | `.cursorrules` | Cursor |
83
+
84
+ Each file contains identical wiki instructions in the format that provider expects. The CC plugin (slash commands + hooks) is Claude Code only — other providers use the wiki via file reads without the plugin.
85
+
86
+ ---
87
+
88
+ ## Existing projects
89
+
90
+ `npx @alekra1/llm-wiki` is conflict-safe:
91
+
92
+ - `wiki/` — skipped if it already exists
93
+ - `CLAUDE.md` — wiki block appended if not already present, never overwritten
94
+ - `AGENTS.md`, `GEMINI.md`, `.cursorrules` — created only if absent
95
+
96
+ The CC plugin installs alongside your existing `.claude/settings.json` without touching it.
97
+
98
+ ---
99
+
100
+ ## Conventions
101
+
102
+ Read `wiki/HOWTO.md` for the full conventions: page format, supersession rules, log format, index discipline, snapshot discipline, and lint checklist.
package/bin/setup.js CHANGED
@@ -35,21 +35,21 @@ const WIKI_BLOCK = `
35
35
  This project uses an LLM wiki at \`./wiki/\` as its living context layer.
36
36
 
37
37
  **On session start:** read \`wiki/_snapshot.md\` first (fast bootstrap), then
38
- \`wiki/_active/now.md\` and recent entries from \`wiki/log.md\`. If unfamiliar
39
- with the wiki conventions, also read \`wiki/HOWTO.md\`. Drill into other pages
40
- only as needed.
38
+ \`wiki/_active/now.md\` and recent entries from \`wiki/log.md\`. If unfamiliar with the
39
+ wiki conventions, also read \`wiki/HOWTO.md\`. Drill into other pages only as needed.
41
40
 
42
- **While working:** update the wiki per \`wiki/HOWTO.md\`. Use supersession, not
43
- deletion, for contradictions. Add a \`log.md\` entry for each wiki change.
41
+ **While working:** update the wiki immediately when anything significant happens — do not batch updates for later. Triggers: a decision is made, a preference is stated, a pitfall is found, a task changes, a discovery occurs. Write the \`wiki/log.md\` entry at the moment it happens, not at session end. Use supersession, not deletion, for contradictions.
44
42
 
45
- **On session end:** rewrite \`wiki/_snapshot.md\` to reflect current state if
46
- anything changed this session.
43
+ **On session end:** rewrite \`wiki/_snapshot.md\` to reflect current state if anything changed. Run \`/wiki-lint\` only when the user asks for it.
44
+
45
+ **Slash commands**: \`/wiki-update\` — write a wiki entry; \`/wiki-lint\` — run the lint
46
+ checklist; \`/wiki-snapshot\` — refresh the snapshot mid-session. The SessionStart hook
47
+ in \`.claude/settings.json\` auto-bootstraps context at the start of each session.
47
48
 
48
49
  **If you are a subagent** (spawned via API, orchestration tool, or CI — not an
49
- interactive CC session): hooks will not fire. Treat these instructions as your
50
- hooks. Read \`wiki/_snapshot.md\` at the start of your first response. Write
51
- updates to the wiki before your final response. Append a \`log.md\` entry for
52
- any wiki change made.
50
+ interactive CC session): hooks will not fire. Treat these instructions as your hooks.
51
+ Read \`wiki/_snapshot.md\` at the start of your first response. Write updates to the wiki
52
+ before your final response. Append a \`log.md\` entry for any wiki change made.
53
53
  `;
54
54
 
55
55
  const claudePath = path.join(DEST, 'CLAUDE.md');
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@alekra1/llm-wiki",
3
- "version": "1.0.0",
3
+ "version": "1.0.1",
4
4
  "description": "Markdown wiki template for LLM agent persistent memory. Gives agents cross-session, cross-provider memory.",
5
5
  "bin": {
6
6
  "llm-wiki": "bin/setup.js"
@@ -13,19 +13,11 @@
13
13
  "GEMINI.md",
14
14
  ".cursorrules"
15
15
  ],
16
- "keywords": [
17
- "llm",
18
- "claude",
19
- "agents",
20
- "wiki",
21
- "memory",
22
- "context",
23
- "claude-code"
24
- ],
16
+ "keywords": ["llm", "claude", "agents", "wiki", "memory", "context", "claude-code"],
25
17
  "license": "MIT",
26
18
  "repository": {
27
19
  "type": "git",
28
- "url": "git+https://github.com/Alekra1/llm-wiki.git"
20
+ "url": "https://github.com/Alekra1/llm-wiki"
29
21
  },
30
22
  "engines": {
31
23
  "node": ">=14"
package/wiki/HOWTO.md CHANGED
@@ -104,6 +104,8 @@ Format: `- [Page Title](relative/path.md) — one-line summary`
104
104
  `log.md` is append-only. Never edit or delete existing entries.
105
105
  Every wiki write gets a log entry.
106
106
 
107
+ **Write immediately, not at session end.** The moment a decision is made, a preference stated, a pitfall found, or a task changes — write the log entry then. Do not accumulate updates and batch them later. Batching leads to missed entries when context runs out or sessions end unexpectedly.
108
+
107
109
  **Format:**
108
110
 
109
111
  ```