chore: clean up project root

CLAUDE.md

@@ -3,6 +3,118 @@
 Shared memory layer for AI-powered engineering teams. Built on
 [QMD](https://github.com/tobi/qmd).
 
+## Memory
+
+You have Smriti. USE IT.
+
+### Start of Every Session
+
+Before writing a single line of code, run:
+
+```bash
+smriti recall "[what we're about to work on]"
+```
+
+Use what comes back. If there's prior context on this topic, it changes how
+you approach the work. Don't ignore it.
+
+### Recognize These Moments — Then Act Immediately
+
+No permission needed. No asking "should I save this?" Just do it.
+
+- Someone says "this works" or "let's go with this"
+- An approach is chosen after comparing options
+- A bug is fixed and the root cause is understood
+- A constraint is discovered that will affect future work
+- An architectural decision is made
+
+**WRONG**: Continue the conversation without saving.
+**RIGHT**: Write the decision record, ingest it, tag it — then respond.
+
+### How to Save a Decision
+
+**Step 1 — Write the record:**
+
+```bash
+cat > /tmp/smriti-note.md << 'EOF'
+# [Title]
+
+## Decision
+[One sentence — the actual choice made.]
+
+## Why
+[The reasoning. What was considered. What was ruled out and why.]
+
+## Context
+[What problem this solves. What breaks if someone reverses this later.]
+EOF
+```
+
+**Step 2 — Ingest:**
+
+```bash
+smriti ingest file /tmp/smriti-note.md \
+  --title "[Title]" \
+  --project smriti
+```
+
+**Step 3 — Tag:**
+
+```bash
+smriti tag [session-id] [category]
+```
+
+### Categories
+
+| What happened | Tag |
+|---------------|-----|
+| Architecture choice, approach finalized | `decision/technical` |
+| Library or tool selected | `decision/tooling` |
+| Bug fixed, root cause identified | `bug/fix` |
+| Structural design settled | `architecture/design` |
+| Feature approach finalized | `feature/implementation` |
+| Config or setup figured out | `project/config` |
+
+### Concrete Example
+
+User says: *"Okay let's use post-filtering for vector search with filters"*
+
+**WRONG**:
+> "Got it, I'll use post-filtering."
+
+**RIGHT**:
+
+```bash
+cat > /tmp/smriti-note.md << 'EOF'
+# Vector search with filters: post-filter approach
+
+## Decision
+Use post-filter strategy for applying metadata filters to vector search
+results, rather than combining sqlite-vec queries with EXISTS subqueries.
+
+## Why
+sqlite-vec's two-step query pattern hangs when combined with Smriti's
+EXISTS subqueries on metadata tables. Post-filtering runs vector search
+unfiltered (3x overfetch), then filters results against session metadata
+in a separate batch lookup — no sqlite-vec changes needed.
+
+## Context
+Affects smriti recall when --project, --category, or --agent flags are
+used. Without this, filtered recall loses semantic search entirely and
+falls back to BM25 only.
+EOF
+
+smriti ingest file /tmp/smriti-note.md \
+  --title "Vector search with filters: post-filter approach" \
+  --project smriti
+
+smriti tag [session-id] decision/technical
+```
+
+Then respond to the user.
+
+---
+
 ## Quick Reference
 
 ```bash
@@ -104,7 +216,7 @@ get a clean name like `openfga`.
 4. Store message/meta/sidecars/costs (store gateway)
 5. Aggregate results and continue on per-session errors (orchestrator)
 
-See `INGEST_ARCHITECTURE.md` for details.
+See `docs/internal/ingest-architecture.md` for details.
 
 ### Search
 

README.md

@@ -299,7 +299,7 @@ works cross-project by default, scoped with `--project <id>`.
 git-native today. Issue tracker integrations are on the roadmap.
 
 **Further reading:** See [docs/cli.md](./docs/cli.md) for the full command
-reference, [INGEST_ARCHITECTURE.md](./INGEST_ARCHITECTURE.md) for the ingestion
+reference, [docs/internal/ingest-architecture.md](./docs/internal/ingest-architecture.md) for the ingestion
 pipeline, and [CLAUDE.md](./CLAUDE.md) for the database schema and
 architecture.