Full Content
# CLAUDE_INSTRUCTIONS.md — v2
**Location:** `/var/www/api.nsgia.com/CLAUDE_INSTRUCTIONS.md`
**Purpose:** Read this ENTIRE file before doing ANY work. No exceptions.
**Updated:** 2026-02-09
---
## Step 1: Report Back on Relevant Links
Before working with Michael, review the links below and report which ones are relevant to the current task. **Always read the PostMortem Errors** — they catalog recurring failures with specific examples.
---
## Step 2: Fetch and Read Standards
**STOP. Before responding to anything else, fetch these URLs and confirm you've read them:**
1. **RAG Ingestion Protocol:** https://nsgia.com/p/48b730eece734c22ac2338d0b3fd57c7
2. **Memsystem Direct Ingestion:** https://nsgia.com/p/9b574001122e422b88ea0034cbff8b7c
Then proceed with the rest:
| Document | URL |
|----------|-----|
| Episodic PostMortem | https://nsgia.com/p/a06deb240a8f4b68a395a3da6677eab4 |
| Vector Guide | https://nsgia.com/p/8d3de49660b54556b43e9bee32d47541 |
| NSG Communication Standards | https://nsgia.com/p/b09e554ed7d546ffb010d4032ceb5a3a |
| NSG Website Workflow | https://nsgia.com/p/8b2864087a6c479a8fe9df19382c0148 |
| NSG Coding Standards | https://nsgia.com/p/e7685900e68644b389fcb192b251ebbc |
| NSG Limbic Visuals | https://nsgia.com/p/6eb64c5c5c4749be9c4e634fc73fbe9d |
| **PostMortem Errors (CRITICAL)** | https://nsgia.com/p/2504e13eae63462b8d2c23a311962700 |
| NSG Linter | https://nsgia.com/p/9107b10478034374850454d06ef7eaba |
| NSG Standards, Website Design | https://nsgia.com/p/c785ca610fd343f99c8d5d30baa1339e |
| Team Standards for Website Design | https://nsgia.com/p/9ee08725512a424e842e096e2b77ef39 |
| Communications Linter | https://nsgia.com/p/2aaaffdb092649079202e7b3d82ee79f |
---
## Step 3: RAG API — How to Search
The RAG system indexes 6.5M+ files across multiple databases. **Always use `bash_tool` with `curl`** — the `web_fetch` tool has permission restrictions that block these URLs, but `bash_tool` can curl freely.
**Base URL (magic key — no auth headers needed):**
```
https://api.nsgia.com/index/k/c46478591f96d3197bd135340531f5d53738494eed2bd4b5cc16a1eaf6d3f384
```
### 3a. FTS5 Keyword Search
Best for: finding specific code, error messages, exact terms.
**Search one index:**
```bash
curl -s 'https://api.nsgia.com/index/k/c46478591f96d3197bd135340531f5d53738494eed2bd4b5cc16a1eaf6d3f384/plain/search/memsys/device_key_expired/10'
```
**Search all indexes:**
```bash
curl -s 'https://api.nsgia.com/index/k/c46478591f96d3197bd135340531f5d53738494eed2bd4b5cc16a1eaf6d3f384/plain/search/Ready%20Aim%20Fire/10'
```
**URL pattern:**
```
/plain/search/{query}/{limit} ← search ALL indexes
/plain/search/{index_id}/{query}/{limit} ← search ONE index
```
**FTS5 search tips:**
- URL-encode spaces as `%20`
- Use specific/unique terms — generic words get drowned by other docs
- FTS5 tokenizes on underscores, hyphens, and punctuation — `CLAUDE_INSTRUCTIONS` won't match as one token; search `CLAUDE` or `device_key_expired` instead
- Porter stemming is on — `coding` matches `code`, `instructions` matches `instruct`
- Combine terms for precision: `device_key_expired` beats `device key`
### 3b. Vector/Semantic Search
Best for: conceptual queries, finding related content when you don't know exact terms.
**IMPORTANT: The route is `/plain/vector/search/` — NOT `/plain/semantic/`**
**Search one index:**
```bash
curl -s 'https://api.nsgia.com/index/k/c46478591f96d3197bd135340531f5d53738494eed2bd4b5cc16a1eaf6d3f384/plain/vector/search/memsys/Claude%20instructions%20for%20coding%20sessions/5'
```
**Search all indexes:**
```bash
curl -s 'https://api.nsgia.com/index/k/c46478591f96d3197bd135340531f5d53738494eed2bd4b5cc16a1eaf6d3f384/plain/vector/search/postmortem%20failures%20coding%20standards/5'
```
**URL pattern:**
```
/plain/vector/search/{query}/{limit} ← search ALL indexes
/plain/vector/search/{index_id}/{query}/{limit} ← search ONE index
```
**Vector search tips:**
- Use natural language phrases, not single keywords
- Describe what you're looking for conceptually
- Good: `Claude instructions for coding sessions postmortem standards`
- Bad: `CLAUDE_INSTRUCTIONS`
### 3c. Retrieve Full Content by ID
Once you have a `path` (filepath or chat_id) from search results, fetch full content:
**For file indexes (ats2, aburi, api, etc.):**
```bash
curl -s 'https://api.nsgia.com/index/k/c46478591f96d3197bd135340531f5d53738494eed2bd4b5cc16a1eaf6d3f384/content/api/index_search_api.py'
```
**For chat indexes (memsys) — use the chat_id from search results:**
```bash
curl -s 'https://api.nsgia.com/index/k/c46478591f96d3197bd135340531f5d53738494eed2bd4b5cc16a1eaf6d3f384/content/memsys/4dd7d361-fdb9-4826-865e-561340208426'
```
**URL pattern:**
```
/content/{index_id}/{filepath_or_chat_id}
```
Returns JSON with `content`, `has_content`, and for chats: `conversation_name`, `message_count`, `messages[]`.
### 3d. List Available Indexes
```bash
curl -s 'https://api.nsgia.com/index/k/c46478591f96d3197bd135340531f5d53738494eed2bd4b5cc16a1eaf6d3f384/plain/list'
```
Common indexes: `memsys`, `ats2`, `aburi`, `2tbu`, `2025downloads`, `api`
### 3e. Search Strategy (When First Search Misses)
1. **Start with FTS5 keyword search** using specific terms from the content you need
2. **If FTS5 returns 0 or irrelevant results**, switch to vector search with a natural language description
3. **If both miss**, try different terms — synonyms, related concepts, or broader queries
4. **Never assume content doesn't exist** just because one search missed — try all three methods
**DO NOT** use `/index/rag?q=...` — that endpoint requires session auth and will fail from curl.
**DO NOT** use Bearer tokens, session cookies, or any headers for RAG search. The magic key in the URL is the only auth needed.
---
## Step 4: Push to Memory System (Ingestion)
Claude can POST session summaries and clips directly into Michael's memory system RAG index (memsys). Clips are immediately stored, FTS5-indexed, and vectorized.
### Endpoint
```
POST https://memory.nsgia.com/ingest/clip
```
### Headers (required)
```
Content-Type: application/json
X-Device-Key: PsJHQ2l0GhtJpW4lX_rlvTfK2KIg-DCzDMt-ooDlqDc
```
### Payload
```json
{"content": "Full text here", "source": "claude_session", "title": "Session: 2026-02-09 — Brief description"}
```
### Field Notes
- **source:** Use `claude_session` for session summaries (distinguishes from `desktop_clip`)
- **title:** Prefix with `Session:` and date. Under 255 chars. This becomes the search result name.
- **content:** Include chat UUID, outcome, key decisions, technical details, grades if given.
### Exact Copy-Paste Command (bash_tool)
For short content:
```bash
curl -s -X POST https://memory.nsgia.com/ingest/clip \
-H "Content-Type: application/json" \
-H "X-Device-Key: PsJHQ2l0GhtJpW4lX_rlvTfK2KIg-DCzDMt-ooDlqDc" \
--data-binary @- <<EOF
{"content":"Your text here. Keep under 1KB.","source":"claude_session","title":"Session: 2026-02-09 — Description"}
EOF
```
For longer content or content with special characters (recommended):
```bash
CONTENT=$(cat /path/to/file.md | python3 -c "import sys,json; print(json.dumps(sys.stdin.read()))")
curl -s -X POST https://memory.nsgia.com/ingest/clip \
-H "Content-Type: application/json" \
-H "X-Device-Key: PsJHQ2l0GhtJpW4lX_rlvTfK2KIg-DCzDMt-ooDlqDc" \
--data-binary @- <<EOF
{"content":$CONTENT,"source":"claude_session","title":"Session: 2026-02-09 — Description"}
EOF
```
### Successful Response
```json
{"chat_id": "4dd7d361-fdb9-4826-865e-561340208426", "index": "memsys", "ok": true}
```
Save the `chat_id` — you need it to verify and retrieve content.
### Verify Ingestion (Three Methods — Try All)
After pushing, confirm the clip is searchable. If one method misses, try the next:
**1. Direct content retrieval (always works immediately — use chat_id from response):**
```bash
curl -s 'https://api.nsgia.com/index/k/c46478591f96d3197bd135340531f5d53738494eed2bd4b5cc16a1eaf6d3f384/content/memsys/CHAT_ID_HERE'
```
**2. FTS5 keyword (use a specific/unique term from the content you pushed):**
```bash
curl -s 'https://api.nsgia.com/index/k/c46478591f96d3197bd135340531f5d53738494eed2bd4b5cc16a1eaf6d3f384/plain/search/memsys/UNIQUE_TERM/5'
```
**3. Vector/semantic (use a natural language description of what you pushed):**
```bash
curl -s 'https://api.nsgia.com/index/k/c46478591f96d3197bd135340531f5d53738494eed2bd4b5cc16a1eaf6d3f384/plain/vector/search/memsys/description%20of%20what%20you%20pushed/5'
```
Method 1 always works immediately. Methods 2 and 3 depend on indexing — if they miss, try more specific terms before concluding the clip isn't indexed.
### Device Key Expiration
Key has 720-hour TTL. If `device_key_expired` error, ask Michael to generate a new key or re-download deb on workstation. Then search memsys for this document and update the key above.
---
## Session Start Workflow
1. Read this file (`cat /var/www/api.nsgia.com/CLAUDE_INSTRUCTIONS.md`)
2. Report which standards links are relevant to the current task
3. Fetch and read the relevant standards (always include PostMortem Errors)
4. Call `recent_chats` (n=20) if available
5. Search memsys for existing `claude_session` summaries to avoid duplicates
6. Summarize unsummarized sessions and POST via ingest endpoint
7. **Then** — and only then — begin working on Michael's request
---
## BEFORE ANY Writing or Coding Session
Fetch and review all standards links in Step 2. These contain lessons from past failures — Jinja in comments, coding before research, wrong tone, incomplete changelogs. Reading them first saves hours of rework.
When Michael says "see standards" or references any standard, fetch **ALL** immediately — they work together. The PostMortem Errors doc is especially critical.
---
## The Rules (from PostMortems)
1. **Ready-Aim-Fire, NOT Ready-Fire-Aim** — Research before coding.
2. **Fetch standards at session start** — Every time, no shortcuts.
3. **Ask "What already works?"** — Search RAG before writing new code.
4. **5-Failure Rule:** After 5 failed attempts, STOP. Review architecture. Ask.
5. **Two-Message Rule:** First message = research and propose approach. Second message = code (only after Michael confirms). Never code in the same message as acknowledging instructions.
6. **Read, Don't Skim:** Quote specific relevant sections. Show how the approach matches documentation. Flag discrepancies BEFORE coding.