AlexandrAI AGENTS.md
agents-md

FileGraph Retrieval Context Agent Guide

Agent guide for FileGraph retrieval context assembly from search seeds, graph neighbors, and communities.

AGENTS.md

Guidance for coding agents working on FileGraph Retrieval Context in the FileGraph project.

Project overview

This guide covers src/app/api/retrieval/context/route.ts and FileGraphService.getRetrievalContext. Retrieval context starts from an optional note id and optional search query, expands through graph edges and same-origin space membership, caps neighbor notes, selects intersecting communities, and returns a compact markdown context block for downstream agent use.

Primary source files

  • src/app/api/retrieval/context/route.ts reads query and noteId search params and returns service.getRetrievalContext.
  • src/lib/filegraph/service.ts implements search seeding, graph-neighbor expansion, same-space expansion, community filtering, and contextMarkdown construction.
  • src/lib/filegraph/types.ts defines RetrievalContextResponse, GraphNode, CommunitySnapshot, and GraphSnapshot.
  • src/lib/filegraph/service.ts rebuilds the MiniSearch index from title, body, summary, tags, and entities.

Setup commands

pnpm install pnpm test pnpm lint pnpm build pnpm dev

Change rules

  • Allow noteId-only, query-only, and combined retrieval; callers should not need both parameters.
  • Keep MiniSearch results bounded before graph expansion so broad queries do not flood context.
  • Remove seed ids from neighborNotes to avoid duplicate context sections.
  • Keep same-origin space expansion source-aware: only add candidates with matching origin kind and matching non-null spaceKey.
  • Keep neighbor count bounded so downstream prompts remain compact.
  • Context markdown should include title, note id, summary, tags, and a bounded body slice.
  • Do not include raw source URLs, absolute file paths, or private service locations in retrieval examples or docs.
  • When changing retrieval output, update RetrievalContextResponse and any agent client that consumes contextMarkdown.

Testing

Add tests for noteId seeds, query seeds, missing seeds, duplicate suppression, edge-based neighbors, same-space neighbors, community selection, body truncation, and search-index rebuild after note updates. Use small fake notes with deterministic analyzer output.

PR checklist

  • Retrieval route returns valid JSON for empty and populated vaults.
  • Context markdown stays bounded and does not expose private paths.
  • Neighbor notes exclude seed notes.
  • Search index refreshes after note changes and rescans.