Skip to content

AGENTS.md

Latest commit

 

History

History
154 lines (106 loc) · 4.28 KB

AGENTS.md

File metadata and controls

154 lines (106 loc) · 4.28 KB
Raw

AGENTS.md

Project memory for future Codex runs on codesmart.

1) What This Repo Is (Current Reality)

CodeSmart is a local-first, deterministic codebase intelligence system with:

  • SQLite-backed snapshots/checkpoints
  • Symbol graph + semantic labels
  • Deterministic literal index (strings/comments/docstrings)
  • Optional asynchronous GLiNER2-style enrichment (ml_entities)
  • CLI + MCP interfaces

Important product position:

  • Deterministic baseline is primary and immediately usable.
  • Enrichment is secondary, non-blocking, and improves recall on semantic/prose-heavy fan-out cases.
  • No LLM calls in indexing/query path.

2) High-Value Architecture Decisions

  • Index first, enrich later: start->usable latency is optimized.
  • Content-addressed dedup is in place (parse artifacts keyed by path/hash strategy).
  • Snapshot diff is a core gatekeeping feature.
  • MCP transport support is intentionally dual:
    • stdio
    • Streamable HTTP (single endpoint)

HTTP MCP details already implemented:

  • origin validation
  • localhost-safe defaults (127.0.0.1)
  • MCP-Protocol-Version handling (2025-11-25, fallback path for 2025-03-26)

3) CLI Surface You Should Assume

Top-level commands include:

  • index, stats, find-symbol, symbol, file, label, find-text, ml-entities
  • callers, callees
  • diff, call-diff, snapshot (list/show/delete)
  • serve-mcp, serve-mcp-http
  • doctor, hooks, enrich

Notable behavior:

  • index supports --enqueue-enrich and optional background worker startup.
  • Snapshot creation is implicit via index (no snapshot create command).

4) MCP Surface You Should Assume

Methods implemented:

  • initialize
  • tools/list, tools/call
  • resources/list, resources/read, resources/templates/list
  • roots/list

Current tool set includes:

  • index_repo
  • get_stats (includes enrichment readiness fields)
  • find_symbols
  • find_by_label
  • find_text
  • find_ml_entities
  • get_callers
  • get_callees
  • list_snapshots
  • diff_snapshots
  • diff_call_graph

Important: get_stats now includes:

  • ml_entities
  • enrichment_ready
  • enrichment_status

5) Agent Retrieval Strategy (Expected Best Practice)

Default sequence for agents:

  1. find_symbols for typed/API retrieval.
  2. find_text for fan-out phrase/warning consistency retrieval.
  3. find_ml_entities only when deterministic recall is insufficient.
  4. Use snapshots + diff_snapshots for completeness validation.

This ordering is critical to keep answers deterministic, explainable, and token-efficient.

6) Evaluation Assets and Truth Sources

Evaluation scripts are in scripts/eval/.

Canonical flow:

  • clone_and_index_eval_repos.py
  • run_graph_eval.py
  • run_enrich_eval.py
  • run_callgraph_parity_eval.py
  • run_baseline_literal_eval.py
  • case-study scripts for VS Code and Turbopack

Benchmark/case-study facts are documented in:

  • README.md
  • docs/CASE_STUDY_VSCODE.md
  • docs/CASE_STUDY_TURBOPACK.md
  • docs/index.html

If behavior changes, re-run evals before editing claims.

7) Quality Gates (Now Enforced)

Lint is configured with Ruff in pyproject.toml.

Current lint profile:

  • select = ["E", "W", "F", "I", "UP"]
  • ignore = ["E402", "E501"]
  • excludes: eval-repos, draft

Run before commits:

uv run lint
uv run test

Why E402 ignored: eval scripts intentionally modify sys.path before imports. Why E501 ignored: avoid huge non-functional line-wrap churn.

8) Docs and Messaging Constraints

  • docs/index.html is the polished landing page; keep it externally focused.
  • Emphasize deterministic baseline + no LLM in runtime/index/query.
  • Mention enrichment as additive recall, not foundational requirement.
  • Snapshot diff gatekeeping is a key selling point.

9) Session-Specific Repo Hygiene Notes

There are intentionally untracked docs that may stay uncommitted unless explicitly requested:

  • docs/GLi_PLAN.md
  • docs/ref/pearls-user-guide.md

Do not stage random workspace noise. Keep commits focused and split by concern.

10) Practical Working Norms for This Repo

  • Prefer small, focused commits.
  • Verify with tests/evals after meaningful behavior changes.
  • Avoid docs drift from actual CLI/MCP behavior; confirm via -h and source.
  • For MCP changes, always add/adjust unit tests in tests/unit/test_mcp_server.py.