Skip to content

CLAUDE.md

Latest commit

 

History

History
63 lines (46 loc) · 3.83 KB

CLAUDE.md

File metadata and controls

63 lines (46 loc) · 3.83 KB

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.

Definition Of Done

  • uv run pytest green (full suite)
  • uv run ruff check src tests clean
  • New CLI subcommand: smoke test in tests/test_cli_smoke.py
  • New backend: registered via entry-point, covered by unit + integration test
  • Release: uv build && uvx twine check dist/* clean before tagging

Critical Config

  • Config discovery order: .supamem/config.toml → ~/.config/supamem/config.toml → share/default.toml
  • Cache dir: platformdirs.user_cache_dir("supamem") — never ~/.cache/supamem directly
  • CI env: smoke tests pin NO_COLOR=1, TERM=dumb, COLUMNS=200, pop FORCE_COLOR

When Blocked

  • Test fails on CI but passes locally: check Rich color escape pollution (see test_cli_smoke env override)
  • Import error: confirm uv sync --extra dev ran; check entry-points in pyproject.toml
  • Qdrant connection failure: docker compose up qdrant or use mock fixture
  • 2+ verification failures: stop and report blocker with command output