vector-mcp: Instructions file for Codex

AGENTS.md

Agent contract

Tool-neutral rules for any AI agent or human working in this repository. This block is maintained by the fleet standard; edit outside the markers.

• Owner boundary: this repository owns one external system's calls, mappings and MCP tools (spec prefix CONN-VECTOR-MCP-); it depends on the connector SDK only. Feature routing across repositories: ecosystem boundaries.
• Setup: run uv sync --locked, then uvx pre-commit install --hook-type pre-commit --hook-type pre-push.
• Gates: uvx pre-commit run --all-files must pass before you push. Do not bypass hooks to get green.
• Commits: one logical change per commit with a Spec: <ID> trailer (or Spec: none (<reason>)), plus a Co-Authored-By: trailer naming the assisting agent. Stage explicit paths only; never git add -A or git add .. Use your own configured Git identity, never a tool or bot name.
• Org rules: organization AGENTS.md.

Scope

This repository provides the action-routed vector-mcp server, optional vector provider adapters, an agent entry point, packaged skills/prompts, a vector ontology, and a read-only collection-inventory connector preset.

• Language/Version: Python 3.11+
• Core Libraries: scion-sdk, fastmcp, medulla (client)
• Key principles: Functional patterns, Pydantic for data validation, asynchronous tool execution.

Current architecture

MCP client
  -> vector_collection_management / vector_search
  -> validation, privacy, and backend policy
  -> verified GraphSession boundary
  -> configured provider

Epistemic-graph is the native default. Optional providers are isolated behind extras and imported only when selected.

Non-negotiable design rules

• Do not add legacy paths, fallback implementations, deprecated aliases, compatibility shims, or backward-compatibility branches. Migrate the current contract directly.
• Do not accept credentials or local database paths as MCP tool arguments.
• Do not persist endpoints, credentials, personal identity, raw content, hostnames, or local filesystem paths in source, skills, docs, traces, reports, fixtures, or generated evidence.
• Resolve runtime values through AgentConfig, environment variables, and supported secret references.
• Resolve TLS through the shared transport profile. Do not add certificate-verification bypasses.
• Keep document ingestion confined to the configured root and relative caller-selected paths.
• Keep optional dependencies lazy; importing vector_mcp must not start services or require every provider SDK.
• Never fabricate connector signatures, live test evidence, trace evidence, or safe dependency versions.