neo: Instructions file for Codex

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)
• Memory hygiene:
  • Per-scope valid-fact caps (SCOPE_LIMITS in store.py): global=200, org=100, project=500, session=50. Enforced per loaded scope set (project+org+global); invalidated facts persist as tombstones until purge_dead_facts runs.
  • Supersession at cosine ≥ 0.85 (SUPERSESSION_THRESHOLD); pre-write dedup is canonical-signature equality, not cosine (memory.generalize).
  • REVIEW → PATTERN synthesis was REMOVED. In four months of production it minted 114 facts and not one PATTERN (its PATTERN branch needed an outcome:accepted group that never existed), while re-consuming its own summaries as evidence and decaying the whole corpus on every run. A census also found zero ≥3-member clusters at cosine 0.85 across all 1152 valid REVIEWs, so it could not fire on real data. Durable learning now comes only from the git-verified episode ledger — do NOT reintroduce an unverified similarity-clustered route beside it.
  • Probation: new non-curated facts enter with a probation tag and a 3-day stale window (vs 7/14); promoted automatically on access_count ≥2 or success_count >0.
  • Independent-outcome facts capped at 5/session (MAX_INDEPENDENT_OUTCOMES in outcomes.py) and 50/project (MAX_INDEPENDENT_FACTS in store.py).
  • prune_stale_facts → demote_unhelpful_facts → purge_dead_facts → strip_tombstone_embeddings run on every cold start, each with save=False so the chain flushes one merge-on-save instead of four. _invalidate already strips a tombstone's embedding and bulk text at the transition, so the final step is a backfill for tombstones minted off that path. For on-demand compaction of tombstone bloat in a specific project's fact file, use neo memory prune [--all] [--dry-run] (subcommands.py:_compact_fact_file).
  • Diagnostics (read-only, flag-and-propose): neo memory issues [--since 14d] [--min-cluster 3] [--suggest-rules] [--json] surfaces recurring frictions mined from transcript history (Claude Code / Codex / CAR) as ranked, evidence-cited issues (missing-tool / absent-guardrail / vague-rule); --suggest-rules adds a bounded LM call per issue to draft a preventive rule. neo memory rules [--json] [--no-conflicts] flags drift between AGENTS.md / CLAUDE.md / GEMINI.md (gaps + LM-judged conflicts). neo memory audit [--json] [--no-conflicts] inspects an AI tool's memory files (Claude Code memory/*.md) for malformed entries, near-duplicates, conflicts, and MEMORY.md index drift. neo memory import [--dry-run] ingests a peer tool's memory files into neo's store as REVIEW facts on probation (trust-first; imported:claude-memory tag, content-hash watermark for idempotency). neo memory explain <fact-id-or-prefix> [--json] is a deterministic, read-only join across FactStore and the learning-episode ledger: provenance, supporting/conflicting outcomes, retrieval/context use, metric mutations, rollback, and supersession; it initializes neither embeddings nor an LM.
  • Evaluation: neo memory evaluate-learning [--json] [--workspace PATH] runs the versioned benchmarks/learning_loop_v1.json corpus against memory-disabled, legacy-immediate, and evidence-driven policies. All ten causal/safety scenarios, zero harmful/unsupported/repeat-error/leakage thresholds, a 500 ms local latency cap, zero model calls/tokens, and primary-quality improvement are hard gates. (neo/memory/issues.py, neo/memory/rulesync.py, neo/memory/memaudit.py, neo/memory/memimport.py)
• Domain tags (Fact.domain, memory.models.SUGGESTED_DOMAINS): optional free-form area tag orthogonal to FactKind — code-style, testing, git, debugging, workflow, security, file-patterns, architecture, performance are the suggested vocabulary, but any string is valid. retrieve_relevant(..., domain=...) filters by exact match; domain=None returns all facts including unset ones.
• Outcomes (memory.outcomes + store.detect_implicit_feedback): ACCEPTED/MODIFIED act on a linked legacy fact with confidence +0.2 / −0.2 (±arch_mod); ACCEPTED bumps success_count. New suggestions remain episode-local candidates until independently accepted twice; deterministic verification failure blocks promotion. MODIFIED also writes a REVIEW at confidence 0.4; ACCEPTED falls back to a REVIEW (suggestion_confidence + 0.1) only for legacy unattributed sessions. UNVERIFIED is recorded but never changes confidence or success. INDEPENDENT writes a REVIEW at confidence 0.2. REGRESSION is an explicitly attributed delayed failure; two distinct contradicting source episodes roll back their promoted fact without penalizing unrelated retrieved facts. Footgun: if you add a new OutcomeType, update both outcomes.py and store.detect_implicit_feedback.
• Retrieval: `rank_score = recall_decay(sim)·confidence + success_bonus·effectiveness_f
  • provenance_bonus. memory.models.rank_scoreis the single source of truth — if you change the formula, auditContextAssembler._score_factstoo. Cosine is batched viamath_utils.batched_cosine. Hybrid: 0.7·dense + 0.3·BM25; half the result slots ranked by rank_score, half by raw cosine. CONSTRAINT/ARCHITECTURE/DECISION and the seed/community/synthesizedtags bypass decay. Branching prompts (CHAIN/SPLIT) get per-branch retrieval viamemory.query_routing`; each surfaced EPISODE pulls up to 2 peer episodes from the same session.
• Local storage: per-scope JSON files in ~/.neo/facts/ with inline embeddings. Fine while any single scope file stays under ~10k facts; revisit the backend past that. project_id is SHA256[:16] of the normalized git remote URL (scope._compute_project_id) so the same repo on different clones / worktrees / machines hashes to the same ID. Falls back to a path hash for repos without a remote. Legacy path-hashed fact and watermark files are renamed in place on FactStore init (store._migrate_legacy_project_id_files).
• Context assembly four-layer model is from Beyond Conversation: A State-Based Context Architecture for Enterprise AI Agents (Liotta, 2025); the ContextAssembler token-budget enforcement is ported from Memgine: A Deterministic Memory Engine for Stateful AI Agents (Liotta, 2026). Both PDFs: state-based-context-architecture and memgine-deterministic-memory-engine. Both are evaluated by StateBench. Changes to layer ordering, the 2/3 constraint cap, or the inline (changed from: X) annotation should preserve the validated 95.8% decision-accuracy contract (GPT-5.2 on the v1.0 development split). See docs/solutions/token-budget-enforcement.md.
• A2UI memory inspector (neo.a2ui): a per-project A2UI v0.9 surface (neo-<project_id8>) registered with the running car-server daemon so any conformant renderer (CarHost.app, future webviews) can inspect neo's state live. Two tabs: Observer (status badge, pid, last cycle, recent cycles list, Kick/Stop buttons) and Memory (valid fact count, by kind, by scope, probation count). Updates pushed by the observer process at the end of each synthesis cycle — the same FactStore load powers both tabs, so the inspector adds zero hot-path cost. Kick/Stop buttons emit a2ui.action notifications which the observer dispatches to kick_observer / stop_observer — closes the loop with CAR's supervisor. Footgun: Python's car_runtime.a2ui_* helpers are in-process only; reaching the daemon's shared store (which renderers subscribe to) requires speaking JSON-RPC over its WebSocket. neo.a2ui.DaemonClient is that bridge. Activation: auto when 127.0.0.1:9100 is reachable; silent no-op otherwise. Adds websockets>=12.0 to the [car] extra.
• Async transcript-mining observer (memory.observer): a single global background process (CAR agent neo-observer, --daemon --all) that sweeps every discovered project each cycle, round-robin and watermark-gated. The earlier per-project model (neo-observer-<id12>) is migrated away on bootstrap. Container roots (/, $HOME, ~/git) are excluded from discovery. It ran synthesize_reviews until that subsystem was removed. Hard dep: car-runtime ≥ 0.17.0 and a running car-server daemon — CAR's supervisor owns the spawn / restart-on-failure / log redirection / clean SIGTERM shutdown. Spec persisted to ~/.car/agents.json (auto_start: true so it comes back on daemon boot); logs land at ~/.car/logs/neo-observer-<id8>.{stdout,stderr}.log. Lifecycle: neo memory observer {start|stop|status|kick} — kick maps to agents_restart since CAR has no signal-passthrough primitive. Status surfaces CAR's raw state verbatim (running | stopped | starting | backoff | errored) so restart-loops are diagnosable. Tunables: NEO_OBSERVER_INTERVAL_SECONDS (default 300), NEO_OBSERVER_COOLDOWN (default 60, per-process). Footgun: the interpreter path (sys.executable) must not live under a world-writable directory (/tmp, /private/tmp, /var/tmp, /dev/shm) — the CAR daemon rejects such commands as a security measure. Use a venv under $HOME or a system install.
• Observability: retrieve / add_fact / lm_call / overseer_tick events land in ~/.neo/metrics.jsonl. Gated by NEO_PROFILE: off (no emit), minimal (lm_call only), standard (default, all events), strict (reserved for future verbose events; currently == standard). NEO_METRICS=off is a legacy hard kill-switch that overrides NEO_PROFILE. Sessions and watermarks live in ~/.neo/sessions/.
• Debugging: neo --dry-run "your query" assembles the full context (file selection, fact retrieval, constraints, four-layer assembly) and prints what would be sent to the LM, then exits without making the LLM call. Faster iteration on context-gatherer and retrieval changes than waiting for an inference round trip.
• CarAdapter defaults intent_hint={"task":"code"} so CAR's router picks a code-capable model rather than the chat default. This is the local workaround for Parslee-ai/car-releases#52 (route_model is cost-biased for "simple" prompts and ranks gpt-5.3-codex/o3 behind gpt-4.1-mini). If that upstream lands, revisit the default.
• Operating modes (neo.operating_mode): standalone defaults to learn for backward compatibility (repository read-only, evidence learning enabled). advise and patch retrieve memory but never detect outcomes/create candidates; verify requires caller-provided changes and makes zero LM calls; agent requires explicit workspace-relative write globs plus a host ExecutionAdapter. Neo never executes generated command strings, and standalone/CAR-without-executor fail closed.
• Goal-aware execution envelope (neo.execution_context): JSON/CAR callers may supply goal, intent, constraints, success criteria, attempt, outcome, progress, trajectory, caller role, and requested output. Missing goal/intent values are deterministic, confidence-scored provisional context; never promote an inferred goal or intent as durable truth. Retrieval is conditioned on the resolved envelope. Loop stop/change decisions must use observed progress/outcome evidence, never model confidence alone. Proof-aware callers should declare validation_gates and link each validation_observation by gate_id; aggregate success never satisfies missing gates, and stale/skipped/unavailable evidence fails closed. hypotheses are episode-local falsifiable claims with explicit evidence transitions, never durable truth by generation. execution_identity preserves goal/task/parent/session and cross-repository provenance. Run neo memory evaluate-execution --json for the deterministic zero-model safety gate.
• When creating a pull request, always use the PR template included in the repo.