AgenticStore Documentation

Analyzes local git commit history — authors, frequency, recent changes, and commit patterns. No API key required; reads directly from the local git repository. Use when: user asks about who committed what, recent changes, commit history, activity patterns, or wants to understand how a local repo has evolved. Scope: local git repository only — no network access. Run git commands via subprocess. Not for: remote GitHub repo metadata (use get_repo_info), fetching remote files (use get_file), or searching code patterns (use search_code).

Find local Python and TypeScript/JavaScript symbol imports, definitions, and references with line-level excerpts.

Finds named symbols in a local codebase: Python classes/functions and JavaScript or TypeScript functions, classes, interfaces, types, and variables. Use when an agent needs code structure before reading files or searching references. Scope: local filesystem only and read-only; skips dependency/build directories and scans at most 2,000 files. Not for call graphs or remote repositories.

Compare a Git ref to local dependency manifest changes and estimate affected Python or JavaScript/TypeScript imports.

Read local package manifests and import references to prepare a bounded dependency-upgrade plan without changing packages.

Fetches the content of a specific file from a GitHub repository. Token optional for public repos; required for private repos. Use when: user wants to read a known file from a GitHub repo by its path — e.g. 'show me the README', 'get the handler.py from owner/repo'. Scope: remote GitHub file fetch only. Requires knowing the exact file path. Not for: searching for files by pattern (use search_code), local file reading (use standard file tools), or repo structure overview (use get_repo_info).

Return staged and unstaged files, diff statistics, changed symbols, generated-file detection, and a bounded local Git diff summary.

Static analysis for Python files — detects unused imports, likely bugs, style violations, and high-complexity functions. No code is executed. Use when: user asks to lint, review, check quality, or find bugs in Python code. Scope: Python files only (.py). Local files — no network access. Not for: other languages, package vulnerabilities (use dependency_audit), or secrets in files (use repo_scanner).

Create a read-only release report for Git cleanliness, version metadata, README, changelog, and ignore configuration, with required follow-up checks.

Searches for code patterns across files in a local directory or a remote GitHub repository. Local mode requires no token; GitHub mode uses the GitHub connector (optional for public repos). Use when: user wants to find where a function, class, variable, or pattern is used across a codebase — locally or on GitHub. Scope: local directory walk (no token) OR GitHub code search API (token optional for public repos). Not for: fetching a specific known file (use get_file), analyzing commit history (use analyze_commits), or finding security issues (use repo_scanner).

Run an allowlisted local test, lint, build, or typecheck command with a bounded timeout. Requires confirm_execute=true because it executes project scripts.

Opens a pull request in a GitHub repository. Always returns a preview first — call with confirmed=false (default) to review, then confirmed=true to execute. Requires GitHub connector token with 'repo' scope. Use when: user wants to open a pull request to merge a branch into a target branch. Scope: remote GitHub API — write operation, requires token. Not for: creating issues (use manage_issue), pushing commits (use local git), or reviewing existing PRs (use get_repo_info).

Fetches metadata and structure of a GitHub repository — description, language, stars, forks, branches, topics, and top contributors. Token optional for public repos. Use when: user asks for an overview of a GitHub repo, wants to understand its structure, or needs branch/contributor information. Scope: remote GitHub API. Token optional for public repos, required for private repos. Not for: fetching file contents (use get_file), searching code (use search_code), or analyzing local git history (use analyze_commits).

Creates, updates, closes, or triages issues in a GitHub repository. Always returns a preview first — call with confirmed=false (default) to review, then confirmed=true to execute. Requires GitHub connector token with 'repo' scope. Use when: user wants to create a bug report, update an issue title/body, add labels, assign someone, or close an issue on GitHub. Scope: remote GitHub API — write operation, requires token. Not for: creating pull requests (use create_pr), reading issue lists (use get_repo_info), or local git operations.

Retrieves GitHub code scanning alerts (SARIF findings) for a repository — results from tools like CodeQL, Semgrep, or other SAST tools integrated via GitHub Actions. Requires GitHub connector token with 'security_events' or 'repo' scope. Use when: user asks about code scanning results, CodeQL findings, SARIF alerts, or GitHub Actions security scan results on a remote repo. Scope: remote GitHub API only — requires GITHUB_TOKEN. Not for: local secret scanning (use repo_scanner), Dependabot package vulnerabilities (use dependabot_alerts), or local dependency auditing (use dependency_audit).

Retrieves Dependabot vulnerability alerts for a GitHub repository. Shows CVE IDs, severity, affected package, and available fix versions. Requires GitHub connector with a token that has 'security_events' or 'repo' scope. Use when: user asks about Dependabot alerts, GitHub security tab findings, vulnerable dependencies in a remote GitHub repo. Scope: remote GitHub API only — requires GITHUB_TOKEN. Not for local project scanning. Not for: scanning a local project for vulnerable deps (use dependency_audit), local secret scanning (use repo_scanner), or GitHub code scanning SARIF findings (use code_scanning_alerts).

Checks third-party packages for known CVEs and outdated versions using the OSV vulnerability database. Supports Python (requirements.txt, pyproject.toml, Pipfile), JavaScript (package.json), Go (go.mod), Java (pom.xml, build.gradle), and C++ (conanfile, vcpkg.json). No API key required. Use when: user asks about vulnerable packages, CVEs, supply chain risk, or outdated dependencies. Scope: local project directory — reads dependency files on disk. Not for: secrets leaked in source code (use repo_scanner), code quality issues (use python_lint_checker), or GitHub Dependabot alerts from a remote repo (use dependabot_alerts).

Scans local source files for leaked secrets (API keys, tokens, passwords, private keys), PII (emails, SSNs, credit cards), and missing .gitignore protections. Works on any language — scans file content, not package metadata. Use when: user asks about hardcoded credentials, leaked tokens, .env exposure, or PII in source files. Scope: local directory — no network access, no GitHub API. Not for: package vulnerabilities (use dependency_audit), code quality issues (use python_lint_checker), or GitHub code scanning findings from a remote repo (use code_scanning_alerts).

Fetch any URL and extract page content and SEO signals: title, meta description, Open Graph tags, canonical URL, robots directives, heading structure, word count, and link breakdown.

Search the web using a self-hosted SearXNG instance. Returns ranked results with title, URL, and snippet. Requires SearXNG running locally (docker compose up -d).

Inspect a local OpenAPI JSON/YAML, GraphQL, or JSON Schema contract for endpoints, auth schemes, required fields, and examples.

Lists entries and sizes in a local ZIP or TAR archive without extracting it. Use when an agent needs to understand archive contents safely before selecting files to process. Scope: local filesystem only and read-only; never extracts files and returns at most 5,000 entries. Not for archive creation or extraction.

Validate local CSV, JSON, JSONL, or SQLite data against a reusable JSON contract with required columns, uniqueness, nullability, enums, regexes, and numeric ranges.

Find bounded local code, config, and document references to a data file to infer its workspace lineage. Read-only.

Profiles a local CSV, JSON, or JSONL data file without modifying it. Returns inferred columns, data types, null counts, duplicate-row count, bounded sample rows, and simple PII category counts. Use when: understanding a dataset before writing a query or transformation. Scope: local filesystem only. Read-only; profiles at most 10,000 rows. Not for: full-scale analytics, modifying data, or sending data to a remote model.

Apply read-only quality checks to CSV, JSON, JSONL, or SQLite data: duplicate keys, null thresholds, type drift, invalid emails, and optional referential gaps.

Transforms a local CSV or JSONL file into a new output file. Supports CSV↔JSONL conversion, selecting columns, and exact-match row filtering. It never overwrites the input, and requires confirmed=true before writing. Use when: an agent has reviewed a dataset and needs a small, explicit local transformation. Scope: local filesystem. Writes only the requested new output file after confirmation. Not for: arbitrary code execution, overwriting source data, or large ETL jobs.

Runs a bounded, read-only SELECT or EXPLAIN SELECT query against a local SQLite database. It rejects write statements, multiple statements, PRAGMA, ATTACH, and transaction commands; connections are query-only. Use when: inspecting data after database_inspect has identified the relevant schema. Scope: local SQLite files only. Read-only; returns at most 500 rows and stops long-running queries. Not for: schema changes, inserts, updates, deletes, remote databases, or arbitrary SQL scripts.

Compare bounded extracted text from two local PDF, DOCX, XLSX, PPTX, HTML, Markdown, or text files. Read-only.

Compares two local text files and returns a bounded unified diff. Use when an agent needs to review changes or reconcile generated files. Scope: local filesystem only and read-only; each file is capped at 1 MB and the diff at 2,000 lines. Not for binary files or applying patches.

Extract bounded text and basic metadata locally from PDF, DOCX, XLSX, PPTX, HTML, Markdown, and TXT files. PDF extraction uses the installed pdftotext command.

Inspects a local file without reading its full contents. Returns path, size, extension, detected text/binary type, encoding estimate, SHA-256 hash, line count for text files, and a bounded preview. Use when: deciding how to safely read or process a file before using a data tool. Scope: local filesystem only. Read-only; previews are capped at 8 KB. Not for: searching many files (use file_search), profiling structured data (use data_profile), or modifying files.

Reads a bounded range from a local text file. Use when an agent needs exact file content after file_inspect or file_search. Scope: local filesystem only and read-only; returns at most 2,000 lines. Not for binary files, directory scanning, or file modification.

Selects a small random sample of local files from a directory. Use when an agent needs representative files for exploration without reading an entire tree. Scope: local filesystem only and read-only; skips common dependency/build directories. Set seed for a reproducible sample.

Inventories files in a local directory with paths, extensions, and sizes. Use when an agent needs to understand a workspace before reading or searching it. Scope: local filesystem only and read-only; skips common dependency/build directories and returns at most 5,000 files. Not for secret scanning (use repo_scanner).

Searches text files in a local directory for a literal query. Returns bounded matching paths, line numbers, and excerpts while respecting common ignored directories. Use when: locating data fields, config values, references, or documentation across a project. Scope: local filesystem only. Read-only. Searches at most 2,000 files and returns at most 200 matches. Not for: scanning for secrets or PII (use repo_scanner), or searching remote repositories.

Compares the column schema of two local CSV, JSON, JSONL, or SQLite sources. Returns columns unique to each side, shared columns, and type differences without returning data rows. Use when: checking whether two exports, datasets, or SQLite tables are compatible before migration or transformation. Scope: local filesystem only. Read-only. Not for: comparing row values, moving data, or querying remote databases.

Ranks local text files by relevance to a natural-language query using dependency-free TF-IDF token scoring. Use when literal file_search is too narrow and an agent needs conceptually related file names, identifiers, or text. Scope: local filesystem only, read-only, no embeddings or network calls; scans at most 1,000 text files up to 512 KB each. Not for exact line-level matches (use file_search).

Run bounded read-only filtering, sorting, grouping, and aggregations over local CSV, JSON, and JSONL files without importing data into a database.

Builds and searches a local vector index using an explicitly configured localhost embedding endpoint such as Ollama. Use when TF-IDF semantic_search is insufficient and an agent needs embedding-based relevance. Indexing writes a local JSON index only after confirm_write=true; embedding requests are rejected unless the endpoint is localhost. Not for remote embedding APIs or automatic background indexing.

Capture bounded text, title, timestamp, and term excerpts from a public web page; optionally save a reproducible local JSON evidence record with confirm_write=true.

Fetch public HTTP(S) sources to verify availability and whether specified quoted terms remain present. Network access; source content is untrusted.

Analyzes a list of files or tools currently in an agent's context and recommends which can be safely dropped for the current task — reducing token usage without losing task-critical information. Use when: context window is filling up, you have many files open and need to trim, or an agent wants to know which loaded resources are irrelevant to the active task. Scope: local analysis only — scores items by keyword overlap with the task description. No network access, no file reads. Not for: compressing file content (use token_optimizer), managing persisted memory facts (use memory_write/memory_read), or reading files (use get_file).

Restores full agent session context in one call — loads checkpoint, plan, milestones, recent learnings, and recent log entries. Use when: starting a new session, switching clients, or waking up an agent after a break. Call this first before any work. Scope: local filesystem. No network access. Not for: restoring only a checkpoint (use memory_restore), reading a single fact (use memory_read).

Initializes the centralized agent memory for a project — creates the memory directory, seeds project facts, and writes a starter strategy template. Use when: starting a new project, onboarding a new agent to an existing project, or resetting a project's memory baseline. Scope: local filesystem (~/.config/agentic-store/memory/). No network access. Not for: restoring a prior session (use restore_session), writing individual facts (use memory_write), or reading current state (use restore_session).

Compresses code or text to reduce token count before sending to a remote LLM — removes comments, docstrings, blank lines, and optionally produces a concise structural summary. Use when: a file or snippet is too large for a prompt, you need to trim context before an LLM call, or you want to estimate compression savings. Scope: local text processing only. No network access. Works on any language. Not for: permanent file modification (source is unchanged), context window management of files-in-session (use context_pruner), or reading files from disk (combine with get_file).

Appends a human-readable entry to the project changelog in agent memory. Use when: completing a feature, fixing a bug, or making a notable architectural change worth recording for collaborators or future agents. Scope: local filesystem (CHANGELOG.md in memory dir). No network access. Not for: session event logging (use memory_log), milestone tracking (use update_milestones).

Appends a new learning or insight to the project learnings log in agent memory. Use when: discovering a useful pattern, solving a tricky bug, or capturing a decision rationale that should inform future sessions. Scope: local filesystem (learnings.md in memory dir). No network access. Not for: saving full session context (use memory_checkpoint), tracking milestone progress (use update_milestones).

Updates the milestones tracker in agent memory — either replaces the full document or updates a single milestone's status inline. Use when: marking a milestone complete, adding new milestones, or syncing milestone state after work sessions. Scope: local filesystem (milestones.md in memory dir). No network access. Not for: tracking a full plan narrative (use update_plan), logging session events (use memory_log).

Writes or updates the project plan document stored in agent memory. Use when: creating an initial plan, revising scope, or updating the current approach after major decisions. Scope: local filesystem (plan.md in memory dir). No network access. Not for: tracking milestone status (use update_milestones), logging decisions per-session (use memory_checkpoint), or reading the plan back (use restore_session).

Saves a named snapshot of current session context for cross-client or cross-session continuity. Use when: pausing work and handing off to another client, ending a session with intent to resume, or bookmarking a significant milestone. Scope: local filesystem (~/.config/agentic-store/memory/checkpoints/). No network access. Not for: storing individual facts (use memory_write), logging events (use memory_log).

Appends an event to the agent session log, or reads recent log entries. Use when: recording decisions made, actions taken, or errors encountered during a session; or when reviewing what happened in a previous session. Scope: local append-only log (~/.config/agentic-store/memory/session.jsonl). No network access. Not for: storing persistent facts (use memory_write), saving a full session snapshot (use memory_checkpoint).

Reads facts from the persistent agent memory store. Use when: recalling previously stored decisions, preferences, or context at the start of a session. Scope: local filesystem (~/.config/agentic-store/memory/facts.json). No network access. Not for: searching memory (use memory_search), reading session logs (use memory_log with mode=read), or restoring a full checkpoint (use memory_restore).

Loads a saved checkpoint to restore session context. Use when: resuming work after switching clients, starting a new session after a break, or inspecting what was happening at a previous save point. Scope: local filesystem. No network access. Not for: reading individual facts (use memory_read), searching (use memory_search). Use name='latest' to restore the most recent checkpoint.

Full-text searches across all memory: facts, strategy notes, and checkpoint metadata. Use when: locating a fact whose key you don't remember, finding which checkpoint contains certain context, or auditing what the agent knows. Scope: local filesystem. No network access. Not for: reading a specific fact by key (use memory_read), restoring a checkpoint (use memory_restore).

Writes or updates a persistent fact in the agent memory store. Use when: storing decisions, preferences, project details, or any key-value data that should persist across sessions and clients. Scope: local filesystem (~/.config/agentic-store/memory/facts.json). No network access. Not for: logging events (use memory_log), saving session snapshots (use memory_checkpoint), or retrieving facts (use memory_read).

Create, read, or resolve an explicit local approval record for a sensitive agent action. Writes require confirm_write=true.

Sets, retrieves, or removes API tokens for any service connector using the system keyring. Run once per service — credentials persist across sessions and MCP clients. Use when: user needs to save a GitHub token, OpenAI key, or any other API credential for use by other tools. Scope: local machine keyring (or ~/.config/agentic-store/tokens.json fallback on headless systems). Not for: listing available tools (use tool_search) or testing if a connection works (use the webapp connector test).

Inspects a local SQLite database without changing it. Returns table names, column definitions, indexes, foreign keys, database size, and optional row counts. It opens the database read-only and never executes user-supplied SQL. Use when: an agent needs to understand a local SQLite schema before proposing a query, migration, or data-analysis step. Scope: local SQLite files only. Read-only. Not for: running SQL queries or modifying data; use a separate guarded query tool when that is available. PostgreSQL, MySQL, and remote database URLs are not supported by this tool.

Read or append structured development decisions with rationale, alternatives, risks, and artifact links. Appends require confirm_write=true.

Compare two local .env-style files by variable names and masked value fingerprints; never returns secret values.

Assemble a portable development handoff from explicit plan, task, risk, decision, and checkpoint artifacts. Writing requires confirm_write=true.

Checks whether specific services are currently running on the local machine — by process name or port. Returns running status, PID, and port for Docker, Redis, Postgres, Node, and any named service. Use when: you need to verify a dev server, database, or container runtime is up before running commands or tests. Scope: local machine only. Reads /proc or uses pgrep/lsof — no network calls. Not for: reading log output (use tail_system_logs), starting or stopping services, or checking remote hosts.

Validate an agent plan for structured steps, success criteria, and missing approval markers before execution. Read-only.

Inspects a local project and reports its Git state, detected languages and package manifests, available runtimes, declared test/lint/build commands, and common setup gaps. It never runs project scripts or changes files. Use when: starting work in an unfamiliar repository, deciding what validation to run, or diagnosing missing setup before a build or test. Scope: local filesystem and local Git metadata only. Read-only. Not for: executing tests or commands, scanning source code for secrets (use repo_scanner), or auditing dependencies for CVEs (use dependency_audit).

Read, add, or update local development risks with severity, mitigation, owner, due date, and status. Writes require confirm_write=true.

Reads the last N lines of a local log file — ideal for debugging runtime errors from dev servers, npm run dev, uvicorn, or any process that writes to a file. Use when: a process errored and you need to see recent log output, you're tailing a dev server log, or you want to check system/application logs without leaving the agent session. Scope: local filesystem only. Read-only. Any file the current user can read. Not for: streaming live log output (returns a snapshot), checking if a process is running (use list_processes), or reading structured log files as JSON (returns raw lines).

Relay is a free, open-source project delivery system for AI agents and humans. Create Epics and tickets, pass the baton between Codex, Claude, and people, assign workspaces, and retain decisions, Git evidence, validation, blockers, and handoff history. Writes require confirm_write=true.

Read or explicitly save a structured local checkpoint with a task goal, plan, completed steps, blockers, artifacts, and approval state.

Recommend a focused, risk-aware MCP tool profile from a user goal, privacy preference, and risk level. Read-only; does not apply configuration.

Audit a saved profile’s enabled tools, MCP risk annotations, connector requirements, and missing tool names. Read-only.

Create, read, update, delete, or select named AgenticStore tool profiles. Profile writes require confirm_write=true and take effect after an MCP-client restart.

Finds the best available MCP tools for a task with ranked natural-language matching, safety/capability filters, connector filters, and optional input summaries. Understands related terms such as semantic → vector/relevance and database → SQLite/schema/query. Use when: choosing the right tool before acting, finding local-only or read-only tools, or checking required inputs. Scope: reads the local tool registry only; no network access. Not for: executing a tool, configuring credentials, or managing MCP client configuration.

Create a bounded local workspace manifest with Git state, selected file hashes, manifests, and environment facts. Can compare to or explicitly write a local JSON snapshot.