# 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.