# Pr0fe5s0r Stixdb Stixdb

> StixDB CLI Memory Skill

- Skill: `tomevault-io/pr0fe5s0r-stixdb-stixdb` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add tomevault-io/pr0fe5s0r-stixdb-stixdb`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/pr0fe5s0r-stixdb-stixdb/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: tomevault-io (https://skillmd.com/u/tomevault-io)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tomevault-io/pr0fe5s0r-stixdb-stixdb

---


# 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:

```bash
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.

```bash
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"):

```bash
# 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:

```bash
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.

| Mode | Flag | How it works | When to use |
|---|---|---|---|
| **hybrid** (default) | `--mode hybrid` | Keyword scoring + vector similarity merged (`0.7×semantic + 0.3×keyword`). | Best general recall — use for all normal queries |
| **keyword** | `--mode keyword` | Tag overlap (2× weight) + content term match. No API call. ~5ms. | Exact-tag lookups when you know the exact term |
| **semantic** | `--mode semantic` | Vector embedding via API + cosine similarity. ~1–3s. | Paraphrase or conceptual queries that fail in keyword mode |

**`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

| Rule | Detail |
|---|---|
| Always inject task context | "I am about to do X" gives retrieval a concrete anchor. "What was I doing?" matches nothing usefully. |
| Minimum `--top-k` for `ask` | Never below 10. Use 20–25 for orientation, 15–20 for area-specific, 10 for quick fact. |
| Use `search` for known facts | Faster, no LLM cost. Use `ask` only when synthesis across multiple nodes is needed. |
| Check before storing | Always run `stixdb search "[topic]" --top-k 5` before storing — if a match exists, supersede it, don't duplicate. |

**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

```bash
# 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:

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

### `ingest` vs `store` — which to use

| Use `ingest` for | Use `store` for |
|---|---|
| Source code files and directories | Decisions and their rationale |
| README, docs, API specs | Bug root causes and fixes |
| Any file whose content should be searchable | Coding patterns and conventions |
| — | In-progress state and session summaries |
| — | Architecture understanding you derived |

`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:**

```bash
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:

```bash
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

```bash
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

```bash
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

```bash
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

```bash
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

```bash
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

```bash
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

```bash
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

```bash
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)

```bash
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

```bash
# 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

```bash
# 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

| Score | Use for |
|---|---|
| `0.95` | IN PROGRESS, user preferences, critical decisions |
| `0.9` | Bug fixes, discovered patterns, active architecture rules |
| `0.85` | Module maps, API surfaces, session summaries, refactors |
| `0.7` | Normal facts, file locations |
| `0.5` | Background context |

---

## Tags Reference

| Tag | Meaning |
|---|---|
| `in-progress` | Work started but not finished |
| `session-summary` | Full session narrative |
| `decisions` | Architecture or design decisions |
| `bugfix` | Bug found and fixed |
| `known-issues` | Problems not yet fixed |
| `user-preferences` | How the user wants things done |
| `file-map` | Where things live in the codebase |
| `architecture` | Structural or design facts |
| `api-surface` | Function/class contracts |
| `pattern` | Discovered coding conventions |
| `refactor` | Code that moved or was restructured |
| `YYYY-MM-DD` | Date stamp — always add to in-progress and session-summary |

---

## Troubleshooting

| Symptom | Fix |
|---|---|
| Cannot reach server | `stixdb daemon start` |
| No config found | `stixdb init` |
| `stixdb` not found (Mac/Linux) | `pip install stixdb-engine` — ensure pip's bin dir is in PATH |
| `stixdb` not recognized (Windows) | Restart terminal after install; or try `python -m stixdb`; or add `%APPDATA%\Python\PythonXX\Scripts` to PATH |
| Search returns nothing | Lower `--threshold 0.1`; verify collection with `stixdb collections list` |
| Wrong project context | Wrong collection — always run `stixdb collections list` and use the exact name |
| Two conflicting entries on same topic | The one with `SUPERSEDES:` is current |
| Retrieval returns stale file paths | Run `stixdb search "[module name]" --top-k 10` and look for REFACTOR entries; re-ingest changed files |
| `ask` returns empty | `top-k` too low, wrong collection, or question too generic — see Query Rules above |

---
> Source: [Pr0fe5s0r/StixDB](https://github.com/Pr0fe5s0r/StixDB) — distributed by [TomeVault](https://tomevault.io).
<!-- tomevault:4.0:skill_md:2026-06-24 -->