AlexandrAI AGENTS.md
agents-md

FileGraph Vault Service Agent Guide

Agent guide for FileGraphService, the local markdown vault and graph artifact coordinator.

AGENTS.md

Guidance for coding agents working on FileGraph Vault Service in the FileGraph project.

Project overview

This guide covers src/lib/filegraph/service.ts. FileGraphService owns the local vault lifecycle, note persistence, source identity index, async analysis queue, graph snapshot, MiniSearch index, taxonomy artifacts, and watcher-triggered rescans. Treat it as the system boundary between API routes, the editor UI, analyzer implementations, and the on-disk vault.

Primary source files

  • src/lib/filegraph/service.ts defines FileGraphService and all artifact rebuild logic.
  • src/lib/filegraph/types.ts defines StoredNote, NoteFrontmatter, GraphSnapshot, relations, origins, and ingest payloads.
  • src/lib/filegraph/metadata.ts serializes and parses comment-wrapped metadata headers.
  • src/lib/filegraph/analyzer.ts supplies the default Claude CLI analyzer with heuristic fallback.
  • src/lib/filegraph/service.test.ts covers source upsert, graph relation projection, and metadata artifact generation.

Setup commands

pnpm install pnpm test pnpm lint pnpm build pnpm dev

Change rules

  • Call init before reading service state; public methods already do this and also create vault/notes and vault/.filegraph.
  • Keep notes in vault/notes and derived files in vault/.filegraph; do not mix source markdown and generated artifacts.
  • Preserve sourceIndex semantics: makeSourceKey is origin kind plus external id, and ingestNote must upsert by that identity.
  • Keep persistNote idempotent for unchanged title and body so repeated sync jobs return unchanged and avoid extra analysis work.
  • Use writeAtomically for note and artifact writes so partial files are not left behind during graph rebuilds.
  • Do not bypass rebuildArtifacts after note changes; graph.json, sources.json, communities.json, search-index.json, catalog.json, taxonomy.json, and master.md must move together.
  • Leave watcher debounce and ignoreWatcherEventsUntil intact when changing persistence, or service writes may trigger recursive rescans.
  • Resolve relation proposals only to known note ids before writing metadata and graph edges.

Testing

Cover create, update, unchanged, source-index persistence, hierarchy edge projection, ready and error analysis states, catalog generation, taxonomy defaults, master.md generation, watcher-off test setup, and waitForIdle. service.test.ts already uses a fake analyzer; extend that pattern before reaching for real CLI analysis.

PR checklist

  • pnpm test passes for service and route tests.
  • Generated artifacts still rebuild after manual and ingest writes.
  • Unchanged source sync keeps the same note id and does not enqueue analysis.
  • No public guide or fixture contains machine-local paths, private hosts, or source URLs.