neo: Instructions file for Claude Code

Project: Neo - Semantic Reasoning Helper

Quick Context

• Purpose: Read-only reasoning helper for CLI tools using MapCoder/CodeSim-style multi-agent reasoning with semantic memory
• Tech Stack: Python 3.10+, fastembed (Jina Code v2, 768d), faiss-cpu (legacy pattern matching), Anthropic/OpenAI/Google LMs
• Installation: pip install -e ".[dev]" for development

Code Style

• Import convention: stdlib → third-party → local, specific imports
• Naming: PascalCase classes, snake_case functions, UPPER_SNAKE constants, _private methods
• Error handling: Try/except with specific exceptions, logger warnings, graceful fallbacks
• Testing: test_*.py pattern, pytest framework
• Type hints: Extensive with Optional, list[], dict[]
• Docstrings: Triple quotes, brief description first

Project Rules

• Keep implementations simple first, enhance iteratively
• Test all changes before committing
• Use 3-5 minute timeout when executing neo commands
• Semantic memory: Local embeddings (Jina 768-dim) preferred over OpenAI (1536-dim)
• When creating a pull request, always use the PR template included in the repo.
• Before changing a subsystem, read its notes in docs/engineering-notes/. They hold the reasons, measurements and footguns behind every rule below; most rules exist because the obvious alternative was shipped and broke. Add new long-form notes THERE, not here — this file stays short.

Subsystem rules (details: docs/engineering-notes/<file>)

Memory store — memory-store.md

• Per-scope valid-fact caps (SCOPE_LIMITS): global 200, org 100, project 500, session 50. Supersession at cosine ≥ 0.85 (SUPERSESSION_THRESHOLD); pre-write dedup is canonical-signature EQUALITY, not cosine.
• Promotion to a durable PATTERN needs ≥2 git-verified ACCEPTED episodes sharing a correlation signature AND spanning ≥2 distinct sittings/base revisions (applied_on_revision, FactStore._sitting_bases union-find). Fails closed on a blank revision. Never reintroduce a session-id fallback. Any new producer of ACCEPTED outcomes must set applied_on_revision or it never promotes.
• Correlation signature = candidate SUBJECT + structural fingerprint (_suggestion_fingerprint, name-normalized inside the skeleton extractor), never the LM body. Frozen into Fact.canonical_signature at mint; teardown uses the frozen value only. Don't conflate _episode_signature / _global_signature with _canonical_signature (dedup, includes body).
• Only pattern kind promotes (algorithm/bugfix task types). Task type comes from classify_task_type; ties fail safe to non-promotable kinds.
• suggestion_is_verifiable must resolve paths via normalize_suggestion_path; it deliberately over-admits (kind is frozen at mint). learning-stats classification is reporting-only and stricter; keep its check ordering.
• REVIEW→PATTERN similarity synthesis was REMOVED; do not reintroduce an unverified clustering route.
• _invalidate is the single invalidation choke point and strips embeddings + bulk text (keeps subject/tags/metadata). Cold start runs recall-lift → prune → demote → purge → strip with save=False and one save.
• project_id = hash of the normalized git remote URL (path hash fallback).
• Retrieval rank formula lives only in memory.models.rank_score; audit ContextAssembler._score_facts when changing it. Decay counts in DECAY_UNIT_DAYS; only carries_lesson facts enter the engine's valid layer and recall — slowing decay without that filter floods commit subjects. Four-layer context assembly must preserve the StateBench decision-accuracy contract.
• GitHubPRSource facts enter as REVIEW on probation and never promote by recurrence.
• Recall deliveries (ledger recall_delivered) lift probation for mined lessons but are NOT accesses; a recall-lifted fact lives only while recall keeps delivering it. Never feed deliveries into access_count.