smriti: Instructions file for Claude Code

Smriti

Shared memory layer for AI-powered engineering teams. Built on QMD.

Memory

You have Smriti. USE IT.

Start of Every Session

Before writing a single line of code, run:

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:

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:

smriti ingest file /tmp/smriti-note.md \
  --title "[Title]" \
  --project smriti

Step 3 — Tag:

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:

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