CLAUDE.md git:20260721.801cbc4A

Immutable. This exact content is served forever at /api/v1/blob/ddbcbd2de1e4d5c5.

# Memex - Personal Knowledge Base

Centralized knowledge base storing memos and transcripts from all Claude Code sessions.

## Quick Start

The `memex` CLI works from any directory. For Obsidian CLI and dreamer, `cd` to vault is still needed.

```bash
# Check vault status
memex status

# Search for something (RRF scoring is default)
memex search "authentication"

# Search recent docs only (7d, 2w, 3m)
memex search "plugin" --since=7d

# Rebuild index after changes
memex index rebuild --incremental
```

Semantic search requires Gemini API: `export GEMINI_API_KEY="your-key"`. Falls back to FTS-only without it.

## Your Role

You are the **memex curator**. Condense project knowledge into `_project.md` overviews, maintain `[[wikilinks]]`, and cultivate the vault's knowledge topology. Search the vault when you need context — don't rely on pre-loaded summaries.

## Folder Structure

```
memex/
├── projects/<name>/memos/       # Session memos per project
├── projects/<name>/auto-memory/ # Synced Claude Code auto-memory files
├── projects/<name>/transcripts/ # Full conversation logs
├── topics/                      # Cross-project concept notes + trails (type: trail)
├── src/memex/scripts/           # Core scripts (search, embeddings, etc.)
├── scripts/                     # Backward-compat shims → src/memex/scripts/
├── hooks/                       # Claude Code hooks (SessionStart, PreCompact, etc.)
├── commands/                    # Slash commands (/memex:*)
├── skills/                      # Intent-based skills
├── _meta/                       # Curator infrastructure (dashboard, log, tag taxonomy)
├── _views/                      # Obsidian Base views (.base)
├── _templates/                  # Note templates
├── _index.sqlite                # FTS5 + vector search + observation_topics index
└── .claude-plugin/              # Plugin manifest
```

## Knowledge Artifacts

The vault stores three kinds of knowledge, each with a different temperature:

| Artifact | Temperature | Maintenance | Purpose |
|----------|------------|-------------|---------|
| **Memos** | Cold (append-only) | None — write once | "What happened" — session records |
| **Topics** | Warm (periodically updated) | Rewrite during tending | "What is X" — encyclopedic reference |
| **Trails** (`type: trail`) | Warm (periodically extended) | Append during tending | "How X evolved" — narrative across projects |

Topics and trails both live in `topics/`. Trails are distinguished by `type: trail` in frontmatter. Topics are rewritten (synthesized); trails are extended (new chapters appended). Trails are for concepts with genuine cross-project temporal evolution.

## Plugin Commands

- `/memex:save [title]` - Save current context as memo
- `/memex:status` - Show index stats and pending memos
- `/memex:open` - Open vault in Finder/Obsidian

Retrieval is skill-based — Claude searches automatically when you ask about past work. Vault maintenance is handled by the garden-tending skill. Use `memex search` or `memex timeline` CLI for direct access.

## CLI Commands

Shell commands — work from any terminal, any agent:

```bash
memex search <query>        # Hybrid search (FTS + vector)
memex ask <question>        # Deep retrieval with observations
memex timeline <date>       # Browse by date (yesterday, 7d, last week)
memex read <path>           # Read vault document to stdout
memex path                  # Print resolved vault path
memex check                 # Vault health — crystallization readiness
memex check --folders       # Detect project-folder drift (cwd-fragment names, duplicate/split folders)
memex check --validate      # Lint frontmatter (merged keys, missing title, dangling delimiter, no-frontmatter)
memex status                # Document count, chunks, last rebuild
memex context               # Project detection and pending memo status
memex similarity            # Detect near-duplicate topics (--threshold, --json)
memex scrub <path>          # Detect API keys / secrets (--apply redacts in place)
memex mark-saved            # Mark memo saved (prevents duplicate generation)
memex sync                  # Sync auto-memory into vault
memex graph <subcmd>        # Backlinks, orphans, tags, stats
memex topic resolve <slug>  # Resolve redirect_to chain (exit 0=ok, 1=skip/error)
memex index rebuild         # Rebuild search index (--full for embeddings)
memex index status          # Index health JSON (doc/chunk counts, embedding gaps)
memex index embed-missing   # Embed chunks/obs missing from vec tables (retry after API failures)
memex index migrate-vec     # Truncate vec tables to index_dimensions + add metadata cols (no re-embed)
memex index vacuum          # VACUUM the index to reclaim free pages (e.g. after migrate-vec)
memex session discover      # Find unprocessed sessions
memex session import        # Import discovered sessions (--apply to execute)
memex session reconcile-orphans  # Clear stale pending-memo signals whose session was already saved (--apply)
memex obs topic <slug>      # All observations for a topic (cluster lookup)
memex obs stats             # Observation counts per topic
memex obs retag <old> <new> # Retag observations (for topic merges)
memex obs reassign --from-prefix X --to-prefix Y  # Rewrite obs+chunks doc_path (folder rename SOP)
memex obs untagged          # Observations with no topics (new-topic signals)
memex obs orphans           # Mirror rows whose parent observation is gone (--apply to prune)
memex backfill obs          # Extract observations from memos
memex backfill tokens       # Backfill token counts on transcripts
memex backfill memos        # Backfill has_memo on transcripts
memex backfill topic-tags   # Propagate memo topics to observations
```

## Available Skills

| Skill | Purpose | When to Invoke |
|-------|---------|---------------|
| `recall` | Retrieve session memory — temporal browsing, keyword search, deep cross-session synthesis, or direct file loading | "what did I do yesterday?", "why did we...", "what patterns across...", "load the X topic" |
| `garden-tending` | Full vault lifecycle: diagnose, condense, connect, grow, maintain | "tend the garden", "update project overview", "check vault health", "find broken links" |
| `curator-practice` | Autonomous curator operating philosophy: attention, judgment, initiative | Autonomous tending, "what should I work on next?", scheduled/cron agents |
| `memo-writing` | Format and quality guidelines | `/memex:save`, "remember this", or when [memex] nudge appears |
| `project-consolidation` | Safely merge drifted/duplicate project folders (preserves obs via `obs reassign`) | "consolidate project folders", "merge duplicate projects", "fix detection drift", or after `memex check --folders` reports drift |

Skills are intent-based: Claude decides when to invoke based on user questions. This is more flexible than hooks which run on events.

## Gotchas

Domain-specific gotchas are in `.claude/rules/` and load automatically when working on relevant files. These are universal:

- **`memex` CLI resolves vault path automatically** — No `cd` needed for `memex search`, `memex timeline`, etc. For Obsidian CLI (`uv run scripts/obsidian_cli.py`) and dreamer (`uv run python -m memex.dreamer`), `cd` to vault is still required
- **Observation topic slugs are not validated on insert** — `store_observation_topics` accepts any string. Use only slugs matching `topics/*.md` filenames. Invalid slugs create orphan rows in `observation_topics`. Use `memex obs untagged` during garden-tending to spot gaps
- **Never delete from `observations` directly — route through `delete_observation_ids`** — three tables mirror it by observation id (`fts_observations`.rowid, `vec_observations`.rowid, `observation_topics`.observation_id). A bare `DELETE FROM observations` leaves mirror rows that every JOIN-ing read path silently discards, so the damage never surfaces in search — it shows up only as counters claiming observations the vault cannot return, and as orphan rows consuming vector-search KNN slots. `_OBS_MIRROR_TABLES` in `observations.py` is the single registry; a new mirror table must be added there or `test_mirror_registry_covers_every_table_referencing_observations` fails. Check any index with `memex obs orphans` (read-only; `--apply` prunes)
- **`memex backfill obs` REPLACES a doc's observations, it does not append** — `store_observations` calls `delete_observations_for_doc(conn, memo_path)` first, so a second call for the same `--doc-path` silently destroys everything the first call stored. The output reports only `{"stored": N, "total": N}` and says nothing about what it deleted, so the loss is invisible: extracting 12 obs, then later extracting 5 more for the same memo, leaves you with **5**, not 17. **Always send the complete set for a doc in ONE call.** If you extend a memo mid-session, re-send the original observations together with the new ones. Verify with `memex obs stats` before and after — the total is the invariant (observed live 2026-07-21: 15694 → 15687 after a 5-obs "addition"; recovered by re-sending all 18)

## Where to Go Next

Domain-specific details load automatically via `.claude/rules/` when you work on relevant files:

| Rules File | Covers | Loaded When Editing |
|------------|--------|-------------------|
| `architecture.md` | Memo generation layers, session lifecycle, search pipeline, frontmatter schema | `scripts/`, `hooks/`, `commands/`, `skills/` |
| `maintenance.md` | Periodic tasks, dev commands (rebuild, backfill, discover, sync) | `scripts/`, `_views/`, `topics/` |
| `configuration.md` | Config paths, path resolution, linking conventions, security | `scripts/`, `hooks/`, `.claude-plugin/` |
| `search-and-embeddings.md` | Embedding providers (Gemini primary, LM Studio fallback), chunking, search gotchas | `scripts/{search,hybrid_search,embeddings,index_rebuild}.py` |
| `obsidian-cli.md` | Obsidian CLI 1.12.5 commands, SQLite fallback, graph navigation | `scripts/obsidian_cli.py`, `graph_queries.py`, `crystallization_check.py` |
| `transcripts.md` | Transcript processing, JSONL format, system tag cleaning | transcript-related scripts |
| `hooks.md` | Hook implementation details, timing constraints | `hooks/` |
| `plugin-authoring.md` | Error patterns for commands, skills, hooks, scripts, plugin cache | `commands/`, `skills/`, `hooks/`, `scripts/`, `.claude-plugin/` |
| `python-patterns.md` | Python patterns used across the codebase | `scripts/` |