d8fabc5a50
Replace project self-references throughout README, SETUP, and the example CLAUDE.md files. External artifact titles are preserved as-is since they refer to the actual title of the Claude design artifact. Also add a "Why 'memex'?" aside to the README that roots the project in Vannevar Bush's 1945 "As We May Think" essay, where the term originates. The compounding knowledge wiki is the LLM-era realization of Bush's memex concept: the "associative trails" he imagined are the related: frontmatter fields and wikilinks the agent maintains. Kept lowercase where referring to the generic pattern (e.g. "an LLM wiki persists its mistakes") since that refers to the class of system, not this specific project.
162 lines
6.0 KiB
Markdown
162 lines
6.0 KiB
Markdown
# Global Claude Code Instructions — memex Section
|
|
|
|
**What this is**: Content to add to your global `~/.claude/CLAUDE.md`
|
|
(the user-level instructions Claude Code reads at the start of every
|
|
session, regardless of which project you're in). These instructions tell
|
|
Claude how to consult memex from outside the wiki directory.
|
|
|
|
**Where to paste it**: Append these sections to `~/.claude/CLAUDE.md`.
|
|
Don't overwrite the whole file — this is additive.
|
|
|
|
---
|
|
|
|
Copy everything below this line into your global `~/.claude/CLAUDE.md`:
|
|
|
|
---
|
|
|
|
## Wake-Up Context
|
|
|
|
At the start of each session, read `~/projects/wiki/context/wake-up.md`
|
|
for a briefing on active projects, recent decisions, and current
|
|
concerns. This provides conversation continuity across sessions.
|
|
|
|
## memex — When to Consult It
|
|
|
|
**Before creating API endpoints, Docker configs, CI pipelines, or making
|
|
architectural decisions**, check the wiki at `~/projects/wiki/` for
|
|
established patterns and decisions.
|
|
|
|
The wiki captures the **why** behind patterns — not just what to do, but
|
|
the reasoning, constraints, alternatives rejected, and environment-
|
|
specific differences. It compounds over time as projects discover new
|
|
knowledge.
|
|
|
|
**When to read from the wiki** (query mode):
|
|
- Creating any operational endpoint (/health, /version, /status)
|
|
- Setting up secrets management in a new service
|
|
- Writing Dockerfiles or docker-compose configurations
|
|
- Configuring CI/CD pipelines
|
|
- Adding database users or migrations
|
|
- Making architectural decisions that should be consistent across projects
|
|
|
|
**When to write back to the wiki** (ingest mode):
|
|
- When you discover something new that should apply across projects
|
|
- When a project reveals an exception or edge case to an existing pattern
|
|
- When a decision is made that future projects should follow
|
|
- When the human explicitly says "add this to the wiki"
|
|
|
|
Human-initiated wiki writes go directly to the live wiki with
|
|
`origin: manual`. Script-initiated writes go through `staging/` first.
|
|
See the wiki's own `CLAUDE.md` for the full ingest protocol.
|
|
|
|
## memex — How to Search It
|
|
|
|
Use the `qmd` CLI for fast, structured search. DO NOT read `index.md`
|
|
for large queries — it's only for full-catalog browsing. DO NOT grep the
|
|
wiki manually when `qmd` is available.
|
|
|
|
The wiki has **three qmd collections**. Pick the right one for the
|
|
question:
|
|
|
|
### Default collection: `wiki` (live content)
|
|
|
|
For "what's our current pattern for X?" type questions. This is the
|
|
default — no `-c` flag needed.
|
|
|
|
```bash
|
|
# Keyword search (fast, BM25)
|
|
qmd search "health endpoint version" --json -n 5
|
|
|
|
# Semantic search (finds conceptually related pages)
|
|
qmd vsearch "how should API endpoints be structured" --json -n 5
|
|
|
|
# Best quality — hybrid BM25 + vector + LLM re-ranking
|
|
qmd query "health endpoint" --json -n 5
|
|
|
|
# Then read the matched page
|
|
cat ~/projects/wiki/patterns/health-endpoints.md
|
|
```
|
|
|
|
### Archive collection: `wiki-archive` (stale / superseded)
|
|
|
|
For "what was our OLD pattern before we changed it?" questions. This is
|
|
excluded from default searches; query explicitly with `-c wiki-archive`.
|
|
|
|
```bash
|
|
# "Did we used to use Alpine? Why did we stop?"
|
|
qmd search "alpine" -c wiki-archive --json -n 5
|
|
|
|
# Semantic search across archive
|
|
qmd vsearch "container base image considerations" -c wiki-archive --json -n 5
|
|
```
|
|
|
|
When you cite content from an archived page, tell the user it's
|
|
archived and may be outdated.
|
|
|
|
### Conversations collection: `wiki-conversations` (mined session transcripts)
|
|
|
|
For "when did we discuss this, and what did we decide?" questions. This
|
|
is the mined history of your actual Claude Code sessions — decisions,
|
|
debugging breakthroughs, design discussions. Excluded from default
|
|
searches because transcripts would flood results.
|
|
|
|
```bash
|
|
# "When did we decide to use staging?"
|
|
qmd search "staging review workflow" -c wiki-conversations --json -n 5
|
|
|
|
# "What debugging did we do around Docker networking?"
|
|
qmd vsearch "docker network conflicts" -c wiki-conversations --json -n 5
|
|
```
|
|
|
|
Useful for:
|
|
- Tracing the reasoning behind a decision back to the session where it
|
|
was made
|
|
- Finding a solution to a problem you remember solving but didn't write
|
|
up
|
|
- Context-gathering when returning to a project after time away
|
|
|
|
### Searching across all collections
|
|
|
|
Rarely needed, but for "find everything on this topic across time":
|
|
|
|
```bash
|
|
qmd search "topic" -c wiki -c wiki-archive -c wiki-conversations --json -n 10
|
|
```
|
|
|
|
## memex — Rules When Citing
|
|
|
|
1. **Always use `--json`** for structured qmd output. Never try to parse
|
|
prose.
|
|
2. **Flag `confidence: low` pages** to the user when citing. The content
|
|
may be aging out.
|
|
3. **Flag `status: pending` pages** (in `staging/`) as unverified when
|
|
citing: "Note: this is from a pending wiki page that has not been
|
|
human-reviewed yet."
|
|
4. **Flag archived pages** as "archived and may be outdated" when citing.
|
|
5. **Use `index.md` for browsing only**, not for targeted lookups. `qmd`
|
|
is faster and more accurate.
|
|
6. **Prefer semantic search for conceptual queries**, keyword search for
|
|
specific names/terms.
|
|
|
|
## memex — Quick Reference
|
|
|
|
- `~/projects/wiki/CLAUDE.md` — Full wiki schema and operations (read this when working IN the wiki)
|
|
- `~/projects/wiki/index.md` — Content catalog (browse the full wiki)
|
|
- `~/projects/wiki/patterns/` — How things should be built
|
|
- `~/projects/wiki/decisions/` — Why we chose this approach
|
|
- `~/projects/wiki/environments/` — Where environments differ
|
|
- `~/projects/wiki/concepts/` — Foundational ideas
|
|
- `~/projects/wiki/raw/` — Immutable source material (never modify)
|
|
- `~/projects/wiki/staging/` — Pending automated content (flag when citing)
|
|
- `~/projects/wiki/archive/` — Stale content (flag when citing)
|
|
- `~/projects/wiki/conversations/` — Session history (search via `-c wiki-conversations`)
|
|
|
|
---
|
|
|
|
**End of additions for `~/.claude/CLAUDE.md`.**
|
|
|
|
See also the wiki's own `CLAUDE.md` at the wiki root — that file tells
|
|
the agent how to *maintain* the wiki when working inside it. This file
|
|
(the global one) tells the agent how to *consult* the wiki from anywhere
|
|
else.
|