Skip to content

Commit ab1b0b5

Browse files
awrshiftclaude
andcommitted
fix(v2 audit): remove topic/ leftovers, add CONTRIBUTING.md
Systematic audit of v2 port found leftover v1 references and one broken link: 1. .claude/memory/MEMORY.md template — rewritten to remove "Topic Files" section and pointers to .claude/memory/topics/ (replaced by knowledge/ in v2). New "Knowledge Wiki" section documents the 6 subdirs and growth pattern. Architecture header changed: "Index + topic files" → "Hot cache + knowledge wiki". 2. CLAUDE.md line 205 (Context Save Protocol) — "create topic file" → "write a knowledge article in .claude/memory/knowledge/concepts/{slug}.md" 3. CLAUDE.md line 405 (Memory Entry Quality) — "needs more? → topic file" → "needs more? → knowledge article in knowledge/concepts/{slug}.md" 4. CONTRIBUTING.md — created. README linked to CONTRIBUTING.md which did not exist (broken link on first click). New file has minimal welcome + ground rules (zero deps, pure Markdown, Obsidian optional). Known remaining warning (acceptable): - lint.py flags 2 stale_experiments warnings on fresh clone for demo experiments 001 and 002. These are deleted during first-run setup per CLAUDE.md Step 5, so warnings disappear after setup. Verified via grep that zero "topic file" / "topics/" strings remain outside example content. README metrics unchanged: 7/7 P0 still passing. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
1 parent 6da1f19 commit ab1b0b5

3 files changed

Lines changed: 48 additions & 17 deletions

File tree

.claude/memory/MEMORY.md

Lines changed: 18 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
# Project Memory
22
Last updated: [DATE] (Session: #1)
3-
Architecture: Index (< 200 lines, auto-loaded) + topic files (on-demand)
3+
Architecture: Hot cache (< 200 lines, auto-loaded) + knowledge wiki (on-demand)
44

55
---
66

@@ -30,20 +30,23 @@ Architecture: Index (< 200 lines, auto-loaded) + topic files (on-demand)
3030
|----------|-----------|--------|
3131
| [Example: "Used raw SQL"] | [SQL injection in user input] | [Always use parameterized queries] |
3232

33-
## Topic Files (read on-demand)
33+
## Knowledge Wiki (read on-demand)
3434

35-
> As your project grows, move detailed knowledge into topic files.
36-
> MEMORY.md stays under 200 lines. Topics have no size limit.
37-
> Claude reads topic files when working on that area — not every session.
35+
> Deep knowledge lives in `.claude/memory/knowledge/`, not here.
36+
> MEMORY.md stays under 200 lines (Anthropic auto-load cap).
37+
> The wiki is read on-demand through `knowledge/index.md` — Claude reads individual articles only when relevant, not every session.
3838
39-
| Topic | File | When to read |
40-
|-------|------|-------------|
41-
| [Example: API patterns] | `.claude/memory/topics/api.md` | Working on API endpoints |
42-
| [Example: Database] | `.claude/memory/topics/database.md` | Schema changes, queries |
43-
| [Example: Deployment] | `.claude/memory/topics/deployment.md` | CI/CD, hosting, env config |
39+
**Wiki entry point:** `.claude/memory/knowledge/index.md`
4440

45-
> **How to create a topic file:**
46-
> 1. When a section above grows beyond 5-10 entries on the same theme
47-
> 2. Create `.claude/memory/topics/{topic-name}.md`
48-
> 3. Move detailed entries there, keep one-line summary here
49-
> 4. Add to the table above
41+
**Subdirectories:**
42+
- `concepts/` — single-topic deep dives
43+
- `connections/` — cross-concept relationships
44+
- `meetings/` — structured meeting index articles
45+
- `qa/` — filed query answers (compounding loop via `query.py --file-back`)
46+
- `projects/` — per-project wiki articles
47+
- `experiments/` — gravestone articles (stay after raw files archived)
48+
49+
> **How to grow the wiki:**
50+
> 1. When a theme in MEMORY.md grows beyond 5-10 entries on the same topic, move details to `.claude/memory/knowledge/concepts/{slug}.md`
51+
> 2. Keep a one-line summary here with a pointer: `- **Theme name** [YYYY-MM] — see `knowledge/concepts/{slug}`
52+
> 3. Or let the session-end hook + `compile.py` do it automatically from `daily/` logs

CLAUDE.md

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -202,7 +202,7 @@ Triggers: user says "save context" / "update context", session is ending, or hoo
202202

203203
Execute ALL 3 steps in order:
204204

205-
1. **MEMORY.md** — add new verified patterns (with `[YYYY-MM]` date). Keep < 200 lines. If a theme grows > 5 entries → create topic file.
205+
1. **MEMORY.md** — add new verified patterns (with `[YYYY-MM]` date). Keep < 200 lines. If a theme grows > 5 entries → write a knowledge article in `.claude/memory/knowledge/concepts/{slug}.md`.
206206
2. **next-session-prompt.md** — update ONLY your `<!-- PROJECT:name -->` section: what was done, key decisions, `### IMMEDIATE NEXT` (exact first steps for next session).
207207
3. **JOURNAL.md** — update task statuses if any active tasks.
208208

@@ -402,7 +402,7 @@ Before writing to MEMORY.md, self-check every entry:
402402
2. **Specific** — "always use parameterized queries" > "be careful with SQL"
403403
3. **Actionable** — changes your future behavior, not just states a fact
404404
4. **Not duplicate** — scan existing entries, update if exists
405-
5. **One line** — needs more? → topic file
405+
5. **One line** — needs more? → knowledge article in `knowledge/concepts/{slug}.md`
406406

407407
### MEMORY.md — What does NOT go here
408408

CONTRIBUTING.md

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
# Contributing to Claude Memory Kit
2+
3+
Thank you for your interest in contributing. This project is an OSS starter kit for Claude Code, focused on persistent memory and structured context management.
4+
5+
## Ways to contribute
6+
7+
- **Report a bug** — open an issue with steps to reproduce
8+
- **Propose a feature** — open an issue describing the use case before writing code
9+
- **Improve docs** — PRs for README, CLAUDE.md, or the `/tour` skill are welcome
10+
- **Share a pattern** — open a discussion if you've found a memory or rules pattern that works well
11+
12+
## Pull requests
13+
14+
- Keep PRs focused. One feature or fix per PR.
15+
- Match the existing style (pure Markdown, zero dependencies, stdlib-only Python).
16+
- Test scripts locally before pushing: `python3 .claude/memory/scripts/lint.py` on your changes.
17+
- If you change behavior, update `CHANGELOG.md` and mention the change in the PR description.
18+
19+
## Ground rules
20+
21+
- **Zero dependencies.** Scripts use Python stdlib only. No `pip install`. No external services beyond `claude -p` subprocess.
22+
- **Pure Markdown for content.** Keep the wiki and memory plain `.md` so any editor works.
23+
- **Obsidian remains optional.** Don't add features that require Obsidian to be installed.
24+
- **Be kind in issues and PRs.** Assume good intent.
25+
26+
## License
27+
28+
By contributing, you agree that your contributions will be licensed under the MIT License (see [LICENSE](LICENSE)).

0 commit comments

Comments
 (0)