Imported from Pr0fe5s0r/StixDB (skills/CLI/SKILL.md). Install upstream with npx skills add Pr0fe5s0r/StixDB --skill CLI. Copyright stays with the author.

StixDB CLI Memory Skill

Every session: load context from StixDB at the start, save everything learned at the end. Your context window is temporary. StixDB is permanent.

Session Structure (mandatory, every time)

SESSION START  →  1. Resolve collection name
               →  2. Query StixDB for relevant context
               →  3. Read results — this is your ground truth
               →  4. Work using that context

SESSION END    →  5. Store everything learned, decided, or changed
               →  6. Write IN PROGRESS + SESSION SUMMARY entries

Skipping step 2 means you answer blind. Skipping step 5 means everything learned is lost.

Step 0 — Resolve Collection Name (always first, never skip)

proj_$(basename $(pwd)) is a guess. Collection names may use hyphens where directory names use underscores, or differ entirely. Always verify:

stixdb daemon start
stixdb collections list
# Read the output. Pick the name that matches this project.
COLL="proj_your-actual-name"   # paste the EXACT name shown — do not guess

Never proceed without setting $COLL from actual collections list output.

Windows PowerShell: use $COLL = "proj_your-actual-name" Windows CMD: use set COLL=proj_your-actual-name All stixdb commands themselves are identical across platforms — only shell variable syntax differs.

Step 1 — Load Context

If the user gave you a specific task ("add X", "fix Y", "refactor Z"):

Run only the task-specific query. Skip orientation.

stixdb ask "What context do I need to [exact task]? \
  What decisions apply, what bugs were previously fixed in this area, \
  what patterns must I follow, and what files are relevant?" \
  -c $COLL --top-k 20 --depth 3

If you still find yourself reading files to orient after this, the query was too generic — re-run with the actual task name filled in.

If the user asked for orientation ("recap", "what's the state", "pick up where we left off"):

# Structured orientation — ask four specific sub-questions, never just "what was I doing?"
stixdb ask "I am starting a new session on this project. \
  (1) What tasks are currently in progress with their exact next action? \
  (2) What decisions were made recently that I must not contradict? \
  (3) Any known bugs, blockers, or unresolved issues? \
  (4) What should I work on first, and why?" \
  -c $COLL --top-k 25 --depth 3 --thinking 2 --hops 4

# Targeted recall (hybrid mode by default — no extra flags needed)
stixdb search "in progress" -c $COLL --top-k 5
stixdb search "known issues blockers" -c $COLL --top-k 5
stixdb search "user preferences" -c $COLL --top-k 3

Before touching a specific area mid-session:

stixdb ask "I am about to modify [module/area]. \
  What decisions govern this area, what bugs were fixed here, \
  and what patterns must I follow?" \
  -c $COLL --top-k 20 --depth 3

Retrieval Modes

stixdb search supports three modes. The default is hybrid — no flag needed.

stixdb ask answer format: Answers are now Markdown with ## headers, bullet lists, inline citations [1] [2], and a Sources section. Use --stream to see tokens arrive progressively.

Query Rules

If ask returns empty: either top-k is too low, the collection is wrong, or the question is too generic. Check with stixdb collections stats $COLL, then rerun with --top-k 25 and a more specific question.

Ingesting Files

Use stixdb ingest to make source files semantically searchable. Use stixdb store for knowledge you synthesize (decisions, patterns, bug fixes). Never mix them.

How to discover what to ingest

# See what's in the project before ingesting
ls -la                          # top-level structure
find . -name "*.py" | head -30  # or *.ts, *.go, etc.
cat README.md 2>/dev/null       # project overview

# Then ingest selectively — full codebase for new projects,
# specific files after significant rewrites
stixdb ingest ./README.md -c $COLL --tags overview --importance 0.9
stixdb ingest ./ -c $COLL --tags source-code --chunk-size 600 --chunk-overlap 150

# Confirm what was ingested
stixdb collections stats $COLL

When to re-ingest

Re-ingest a file after significant changes so search returns current content, not stale chunks. Target specific files rather than the whole directory:

stixdb ingest src/auth/hashing.py -c $COLL --tags source-code,auth

ingest vs store — which to use

ingest creates searchable chunks of raw content. It does not store behavioral understanding, decisions, or experiential knowledge — you must write those with store.

What to Store vs What to Skip

✅ Store in StixDB

• File and module references (path + line range + purpose)
• Function/class behavioral contracts (what it does, not what it is)
• Decisions with rationale and rejected alternatives
• Bug root causes and exact fixes (file:line, symptom, fix)
• Discovered conventions and patterns
• In-progress state with exact next action
• API surface: inputs, outputs, side effects

❌ Never store

• Raw source code (use ingest instead, or store only the behavioral description + file:line reference)
• Full conversation transcripts (distill into SESSION SUMMARY or DECISION entries)
• Transient debug output (store only if it reveals a root cause)
• Things directly readable from the filesystem (reference file:line instead)
• Vague summaries like "fixed bug in worker.py" (forces re-investigation — the exact failure mode StixDB prevents)

The test: Can the next agent read only this entry and continue work immediately, without opening a single file? If no — add more detail.

The SUPERSEDES Rule

Every time a fact changes, you MUST explicitly supersede the old entry. If you only add a new entry, both exist. The next agent retrieves both, cannot tell which is current, and picks arbitrarily. This is context contamination — it compounds silently and kills long-running projects.

Before storing any new entry, check:

stixdb search "[topic of what you're about to store]" -c $COLL --top-k 5

If an existing entry covers the same topic, write a SUPERSEDES entry — not a duplicate:

stixdb store "DECISION: [new decision]. \
SUPERSEDES: [previous decision on this topic — state the old topic clearly]. \
CONTEXT: [what changed and why]. \
..." -c $COLL --tags decisions,AREA --importance 0.95

Supersede when: a decision is reversed, a file moves, a bug reappears, a convention changes, an API contract changes, or in-progress work is completed.

Storage Templates

Fill every field. Abbreviated entries force re-investigation and defeat the purpose of StixDB.

Bug Fix

stixdb store "BUG FIXED: [what was observed in logs/output/behavior]. \
ROOT CAUSE: [exact technical explanation — what was wrong and why]. \
LOCATION: [file:line_number — function/class name]. \
FIX: [exactly what changed — behavioral change, not raw code]. \
VERIFIED: [how you confirmed the fix worked]. \
RELATED: [other files/functions involved or worth checking]." \
  -c $COLL --tags bugfix,AREA --importance 0.9

Decision

stixdb store "DECISION: [what was decided — one specific, unambiguous statement]. \
SUPERSEDES: [previous decision on this topic, or 'none']. \
CONTEXT: [what problem this solved]. \
RATIONALE: [why this option over the alternatives]. \
ALTERNATIVES REJECTED: [what else was considered and exactly why ruled out]. \
CONSEQUENCES: [constraints this creates — what you must/must not do now]. \
DATE: [YYYY-MM-DD]." \
  -c $COLL --tags decisions,AREA --importance 0.95

Pattern Discovered

stixdb store "PATTERN: [name or one-line description]. \
WHERE IT APPLIES: [which modules, layers, or situations this governs]. \
THE RULE: [exactly what must be done — specific enough to follow without examples]. \
EXAMPLE LOCATION: [file:line where canonically implemented]. \
GOTCHAS: [what breaks if violated — and how it breaks (silently vs loudly)]. \
EXCEPTIONS: [any legitimate exceptions and where they are]. \
DISCOVERED: [date and context]." \
  -c $COLL --tags pattern,AREA --importance 0.9

Module Map

stixdb store "MODULE MAP: [module or file name]. \
LOCATION: [file path, key line numbers]. \
PURPOSE: [what this module does and why it exists]. \
STRUCTURE: [key classes and functions with line numbers and one-line descriptions]. \
DEPENDENCIES: [what it imports from, what imports it — call direction matters]. \
HOW IT CONNECTS: [data flow in and out of this module]. \
GOTCHAS: [non-obvious things — naming confusion, hidden side effects, init order]." \
  -c $COLL --tags file-map,architecture --importance 0.85

API Surface

stixdb store "API SURFACE: [ClassName.method() or function_name()] at [file:line]. \
SIGNATURE: [full signature with types]. \
INPUT: [each parameter — type, valid values, gotchas]. \
OUTPUT: [return type and what it represents]. \
SIDE EFFECTS: [what this changes in the world — DB writes, cache invalidation, events]. \
INVARIANTS: [contracts the caller must uphold]. \
CALLERS: [key call sites — file:line for each]. \
NOTE: [error cases, thread safety, performance profile]." \
  -c $COLL --tags api-surface,AREA --importance 0.85

Refactor

stixdb store "REFACTOR [YYYY-MM-DD]: [one-line description of what moved]. \
SUPERSEDES: [MODULE MAP or file-map entries that are now stale]. \
WHAT MOVED: [old path → new path for every affected file/class/function]. \
WHAT STAYED: [files that look related but did NOT change]. \
NEW ENTRY POINTS: [new canonical locations]. \
HOW TO REACH IT NOW: [how callers need to update — import path, config, etc.]. \
GOTCHAS: [things that break if someone uses old paths]. \
MOTIVATION: [why the refactor happened]." \
  -c $COLL --tags refactor,file-map --importance 0.9

In-Progress

stixdb store "IN PROGRESS [YYYY-MM-DD]: [feature or task name]. \
COMPLETED SO FAR: [specific things done, with file:line references]. \
CURRENT STATE: [exact state now — what works, what doesn't, what is broken]. \
REMAINING (in order): \
  1. [first step — specific enough to execute without re-investigation] \
  2. [second step] \
  3. [third step] \
NEXT ACTION: [exact first thing to do when resuming — file to open, line to jump to, command to run]. \
BLOCKERS: [anything unresolved that must be addressed first, or 'none']." \
  -c $COLL --tags in-progress --importance 0.95

Session Summary

stixdb store "SESSION SUMMARY [YYYY-MM-DD]: [one-line description of focus]. \
ACCOMPLISHED: \
  - [completed item 1 — with file:line reference] \
  - [completed item 2] \
DECISIONS MADE: \
  - [decision — or 'see DECISION entry: [topic]'] \
BUGS FIXED: \
  - [bug — with file:line — or 'see BUG FIXED entry: [topic]'] \
PATTERNS DISCOVERED: \
  - [pattern — or 'see PATTERN entry: [topic]'] \
CURRENT STATE: [where the project stands now — what works end-to-end]. \
LEFT OFF AT: [exact stopping point — file, function, or task]. \
NEXT SESSION SHOULD START WITH: [specific first action — not a category, an action]." \
  -c $COLL --tags session-summary --importance 0.85

Session End (run every time, after your last tool call)

DATE=$(date +%Y-%m-%d)   # PowerShell: $DATE = Get-Date -Format "yyyy-MM-dd"

# 1. Check: did anything change that supersedes an existing entry?
#    If yes — store SUPERSEDES entries before the summary.

# 2. Store in-progress state
stixdb store "IN PROGRESS [$DATE]: [IN PROGRESS template — full detail]" \
  -c $COLL --tags in-progress,$DATE --importance 0.95

# 3. Store session summary
stixdb store "SESSION SUMMARY [$DATE]: [SESSION SUMMARY template]" \
  -c $COLL --tags session-summary,$DATE --importance 0.85

New Project Setup

# Set collection name (create it if it doesn't exist)
COLL="proj_$(basename $(pwd))"   # then verify with: stixdb collections list

# Ingest and orient
stixdb ingest ./README.md -c $COLL --tags overview --importance 0.9
stixdb ingest ./ -c $COLL --tags source-code --chunk-size 600 --chunk-overlap 150

stixdb ask "I have just ingested this codebase for the first time. \
  What is this project, what problem does it solve, what are the main modules, \
  and what is the entry point I should read first to understand how it works?" \
  -c $COLL --top-k 20 --depth 3

# Store initial structural understanding
stixdb store "MODULE MAP: [entry point module — full MODULE MAP template]" \
  -c $COLL --tags file-map,architecture --importance 0.9

One Collection Per Project (strict)

Every coding project gets its own collection. Never mix projects.

Naming: proj_<repo-name> — e.g. proj_stixdb, proj_payments-api, proj_auth-service

Mixing projects causes context contamination: stixdb ask reasons across two codebases simultaneously, decisions bleed across projects, and file:line references become ambiguous across repos.

Core Commands

# Store synthesized knowledge (agent-written)
stixdb store "TEXT" -c COLLECTION --tags TAGS --importance 0.85

# Ingest files (automated chunking)
stixdb ingest PATH -c COLLECTION --tags TAGS --chunk-size 600 --chunk-overlap 150

# Search — hybrid by default (keyword + semantic merged)
stixdb search "QUERY" -c COLLECTION --top-k 10 --depth 1 --threshold 0.1
# keyword mode — no embedding API call, ~5ms
stixdb search "QUERY" -c COLLECTION --mode keyword --top-k 10
# semantic mode — pure vector similarity
stixdb search "QUERY" -c COLLECTION --mode semantic --top-k 10

# Ask — LLM reasoning, Markdown answer with inline citations
stixdb ask "QUESTION" -c COLLECTION --top-k 20 --depth 3 --thinking 2
# Stream tokens as they are generated
stixdb ask "QUESTION" -c COLLECTION --stream

# Manage
stixdb collections list
stixdb collections stats COLLECTION
stixdb daemon start | stop | restart | status | logs

Importance Guide

Tags Reference

Troubleshooting