supamem: Instructions file for Claude Code

CLAUDE.md — supamem

Claude Code instructions for the supamem repository.

@AGENTS.md

Workflow

• Use /brainstorm before ambiguous feature work
• Use /write-plan before multi-step implementation
• Use /systematic-debug before proposing bug fixes
• Verify with uv run pytest (project root) and uv run ruff check src tests before claiming done

Dual-Memory Tool Use (HARD — eat your own dog food)

This repo SHIPS supamem. If you don't call its MCP tools yourself, end users won't either. Before any of the following, your FIRST action MUST be a mcp__supamem__dual_memory_search (or mcp__supamem__qdrant_find for semantic-only):

• ANY edit under src/supamem/ — search first, edit second. No exceptions.
• Touching retrieval / embedder / chunker / indexer / hooks / installer code
• Investigating a non-obvious bug, test failure, or surprising behavior
• Architecture decisions, ADR-shaped questions ("should I rename X?", "where does Y belong?")
• Before proposing CONTEXT.md decisions during /gsd-discuss-phase

Anti-patterns:

• Searching AFTER editing (the point is to load context BEFORE choosing an approach)
• Skipping because "I already know" — that mindset is exactly what wastes end-user tokens
• Calling only the structural side when the question is "why" — semantic memory has the rationale

If the search returns nothing relevant, say so explicitly ("supamem search empty — proceeding from code") so the gap is visible. Drift between this rule and actual behavior is the bug we're trying to fix in v0.2.0.

Hard Constraints

• NEVER use bare print() — import from src/supamem/console.py
• NEVER print to stdout from mcp_server.py — JSON-RPC purity (use err_console)
• NEVER hardcode collection names — read config.collection
• NEVER skip the PEP 639 license check on release — license = "MIT" SPDX, no License :: classifier
• NEVER force-move a published git tag — PyPI rejects re-uploads of the same version
• NEVER suppress errors in indexing/retrieval paths — surface via err_console
• Update-check is the ONLY code path where blanket except Exception: pass is acceptable
• NEVER edit README.md without also updating the 4 translations (README.zh-CN.md, README.es.md, README.ja.md, README.ru.md) AND bumping the synced-with SHA marker on line 2 of each. See AGENTS.md → "README Translations" for the one-liner.
• ALWAYS update llms.txt when CLI subcommands, MCP tools, env vars, version, or major doc structure changes. Drift between code and llms.txt is a documentation bug — see AGENTS.md → "llms.txt is MANDATORY".
• NEVER commit GSD planning artifacts (.planning/, .gsd/, .continue-here.md, HANDOFF-*.md) to the supamem repo — they are gitignored and meant to stay local. supamem ships as a clean Python package, not a planning workspace. Use docs/adr/, CHANGELOG.md, or commit messages for durable public design records.