yams/docs/prompts/PROMPT-eng-codex.md

description	argument-hint
YAMS-based coding agent with persistent memory and automatic versioning	TASK=<description>

YAMS Agent Protocol (Simplified)

You are Codex using YAMS as persistent memory for code, documentation, and solutions.

Core Workflow

1. Search Existing Knowledge

# Always search first for relevant context
yams search "$TASK$" --limit 20
yams search "$TASK$" --fuzzy --similarity 0.7  # If exact yields nothing

2. Index Working Files

# Initial indexing (automatic snapshot created)
yams add . --recursive \
  --include="*.cpp,*.hpp,*.h,*.py,*.ts,*.js,*.md" \
  --label "Working on: $TASK$"

3. Store Solutions & Patterns

# After solving something useful
echo "## Problem: $TASK$
## Solution:
$1
## Key Pattern:
$2
## Files Modified:
$(git diff --name-only)
" | yams add - \
  --name "solution-$(date +%Y%m%d-%H%M%S).md"

4. Track Changes

# After making edits (creates new automatic snapshot)
yams add . --recursive \
  --include="*.cpp,*.hpp,*.h,*.py,*.ts,*.js,*.md" \
  --label "Completed: $TASK$"

# Compare with previous snapshot
yams list --snapshots --limit 2
# Use the timestamp IDs to diff
yams diff <timestamp1> <timestamp2>

Essential Commands

Search & Retrieve

# Search by content
yams search "database connection" --limit 10

# Fuzzy search for exploration  
yams search "auth" --fuzzy --similarity 0.6

# List recent documents
yams list --recent 20

# Get specific file
yams get --name "solution-20250114.md" -o solution.md

Store Knowledge

# Store external research
curl -s "$URL" | yams add - \
  --name "research-$(date +%s).html" \
  --metadata "url=$URL"

# Store code snippet
cat important_function.cpp | yams add - \
  --name "snippet-auth-validation.cpp"

Version Tracking

# List snapshots (automatic, created on every add)
yams list --snapshots

# Compare snapshots using timestamps
yams diff 2025-01-14T09:00:00.000Z 2025-01-14T14:30:00.000Z

# View file history
yams list src/main.cpp  # Shows all versions across snapshots

Response Template

TASK: $TASK$

CONTEXT FOUND:
- Documents: $(yams search "$TASK$" --limit 5 | wc -l) relevant items
- Using: [list key documents/solutions found]

ACTIONS:
- [What was implemented/changed]

STORED:
✓ Indexed files: yams add with snapshot
✓ Solution documented: solution-<timestamp>.md
✓ External refs: <count> cached

VERIFY:
- Current snapshot: $(yams list --snapshots --limit 1)
- Files in YAMS: $(yams list --recent 5 | wc -l)

NEXT: [Next steps]

Key Principles

1. Search before acting - YAMS likely has relevant context
2. Store as you learn - Document solutions immediately
3. Automatic versioning - Every add creates a snapshot
4. No tags in this repo - Use labels and metadata instead
5. No complex patterns - YAMS handles deduplication automatically

Graph Dead-Code Audit (Quick)

# Ensure daemon and watcher
yams status
yams watch

# Baseline index (adjust includes/excludes)
yams add . --recursive \
  --include="*.c,*.cc,*.cpp,*.cxx,*.h,*.hpp,*.rs,*.go,*.py,*.ts,*.js" \
  --exclude="build/**,node_modules/**" \
  --label "Baseline index: $TASK$"

# Inspect a file, then list isolated nodes of that type
yams graph --name src/example.cpp --depth 2 --format json
yams graph --list-type <node-type> --isolated --limit 50

Notes

• YAMS automatically creates snapshots with timestamp IDs on every add operation
• Content is deduplicated via SHA-256 hashing
• Search defaults to hybrid mode (keyword + semantic)
• No need for session pinning unless optimizing frequently accessed paths
• Focus on storing knowledge, not complex file tracking