Struct AgentsMd 

pub struct AgentsMd { /* private fields */ }

Discovers and loads AGENTS.md files by walking ancestor directories.

AgentsMd is the primary way to inject project-level instructions into an agent session. It walks upward from a given starting directory, collecting AGENTS.md files according to the configured AgentsMdMode. Explicit paths and extra search directories can be added for cases that fall outside simple ancestor discovery.

Loaded items carry metadata under the agentkit.context.* namespace:

Key	Value
agentkit.context.source	"agents_md"
agentkit.context.path	Filesystem path of the file

Example

use agentkit_context::AgentsMd;
use agentkit_context::ContextSource; // for `.load()`

// Find the nearest AGENTS.md starting from the current directory.
let items = AgentsMd::discover(".").load().await?;

// Or collect all ancestor AGENTS.md files, with an extra search dir.
let items = AgentsMd::discover_all(".")
    .with_search_dir("./.agent")
    .load()
    .await?;

Implementations

impl AgentsMd

pub fn discover(start_dir: impl Into<PathBuf>) -> Self

Create a new AgentsMd that searches for the nearest AGENTS.md starting from start_dir and walking upward.

This uses AgentsMdMode::Nearest by default. Call with_mode or use discover_all to collect every ancestor match instead.

pub fn discover_all(start_dir: impl Into<PathBuf>) -> Self

Shorthand for AgentsMd::discover(start_dir).with_mode(AgentsMdMode::All).

Collects every AGENTS.md from the filesystem root down to start_dir, ordered outermost-first so that more specific instructions appear last.

pub fn with_mode(self, mode: AgentsMdMode) -> Self

Set the discovery mode.

See AgentsMdMode for the available options.

pub fn with_file_name(self, file_name: impl Into<String>) -> Self

Override the file name to look for (default: AGENTS.md).

Useful when a project uses a different convention such as CLAUDE.md.

pub fn with_path(self, path: impl Into<PathBuf>) -> Self

Add an explicit file path to include.

The path is checked for existence at load time; if it does not exist it is silently skipped. Explicit paths are loaded before ancestor discovery results.

pub fn with_search_dir(self, dir: impl Into<PathBuf>) -> Self

Add a directory to search for the configured file name.

Unlike ancestor discovery, this checks only the given directory (not its ancestors). This is useful for well-known sidecar locations like .agent/ or .config/.

pub async fn resolve(&self) -> Result<Option<PathBuf>, ContextError>

Resolve the first matching path without reading its contents.

Returns None when no AGENTS.md file is found. This is a convenience wrapper around resolve_all.

Errors

Returns ContextError if a filesystem metadata check fails.

pub async fn resolve_all(&self) -> Result<Vec<PathBuf>, ContextError>

Resolve all matching paths without reading their contents.

The returned paths are deduplicated and ordered from outermost to innermost. When the mode is AgentsMdMode::Nearest, at most one path is returned.

Errors

Returns ContextError if a filesystem metadata check fails.

Trait Implementations

impl Clone for AgentsMd

fn clone(&self) -> AgentsMd

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl ContextSource for AgentsMd

fn load<'life0, 'async_trait>( &'life0 self, ) -> Pin<Box<dyn Future<Output = Result<Vec<Item>, ContextError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Load context items from this source.

impl Debug for AgentsMd

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.