Agents
Agents are AI workers that read and write your knowledge graph autonomously. You define what they do (system prompt, tools, model) and when they run (on demand, on a schedule, or in response to events).
Prerequisites: Agents require a generative model configured on the project. If you haven’t done that yet, see Model Setup first.
Concepts
Section titled “Concepts”| Concept | Description |
|---|---|
| Agent Definition | Reusable blueprint: system prompt, model, tools |
| Agent | Runtime instance: trigger type, schedule, enabled state |
| Agent Run | One execution: status, steps, messages, tool calls |
An Agent points to an Agent Definition. You trigger an Agent, which creates an Agent Run.
Step 1 — Create an Agent Definition
Section titled “Step 1 — Create an Agent Definition”The definition controls what the agent does.
memory defs create \ --name "document-summarizer" \ --system-prompt "You are an expert at summarizing technical documents. Extract key points and write a concise summary." \ --model "gemini-2.0-flash" \ --tools "search,graph_query,graph_create_object" \ --visibility project \ --max-steps 20| Flag | Description |
|---|---|
--name |
Unique name within the project (required) |
--system-prompt |
Instructions for the LLM |
--model |
Model name, e.g. gemini-2.0-flash, gemini-2.5-flash |
--tools |
Comma-separated tool names the agent may call |
--visibility |
project (default), internal (system only), external (ACP-exposed) |
--max-steps |
Hard cap on LLM steps per run (default: 500) |
To configure Google native tools or fine-tune temperature and token limits, use the Agent Definitions settings page in the Admin UI — see Google Native Tools below.
Step 2 — Create a Runtime Agent
Section titled “Step 2 — Create a Runtime Agent”The agent controls when the definition runs.
memory agents create \ --name "doc-summarizer" \ --trigger-type manualmemory agents create \ --name "nightly-report" \ --trigger-type schedule \ --cron "0 2 * * *"Cron format: minute hour dom month dow (standard 5-field).
The server also rejects a schedule that fires more often than every 15 minutes (its default safeguard).
memory agents create \ --name "auto-tagger" \ --trigger-type reaction \ --reaction-events "created,updated" \ --reaction-object-types "document"memory agents create \ --name "ci-trigger" \ --trigger-type webhookSee Webhook Hooks below for the token setup.
Step 3 — Trigger a Run
Section titled “Step 3 — Trigger a Run”memory agents trigger <agent-id>Step 4 — Monitor Runs
Section titled “Step 4 — Monitor Runs”memory agents runs <agent-id> --limit 101. Run a1b2c3d4 Status: completed Started: 2026-03-08 14:22:01 Completed: 2026-03-08 14:22:15 Duration: 14230ms
2. Run e5f6g7h8 Status: failed Error: max steps exceededStatuses: running · completed · failed · skipped · cancelled
Human-in-the-Loop
Section titled “Human-in-the-Loop”If the agent includes the ask_user tool, execution pauses when the agent calls it and waits for your response.
See pending questions
Section titled “See pending questions”memory agents questions list-project --status pendingRespond to resume execution
Section titled “Respond to resume execution”memory agents questions respond <question-id> "My answer here"Webhook Hooks
Section titled “Webhook Hooks”Webhooks let external systems (CI/CD, GitHub Actions) trigger an agent via HTTP.
Create a hook
Section titled “Create a hook”memory agents hooks create <agent-id> \ --label "GitHub Actions" \ --rate-limit 30 \ --burst-size 5Trigger from an external system
Section titled “Trigger from an external system”curl -X POST https://api.example.com/api/webhooks/agents/<hook-id> \ -H "Authorization: Bearer <token>"Manage hooks
Section titled “Manage hooks”memory agents hooks list <agent-id>memory agents hooks delete <agent-id> <hook-id>Available Tools
Section titled “Available Tools”Agents can be given access to tools from the following categories:
| Category | Tool names |
|---|---|
| Knowledge graph | graph_query, graph_create_object, graph_update_object, graph_search |
| Search | search |
| Workspace (bash/file) | workspace_bash, workspace_read, workspace_write, workspace_edit, workspace_glob, workspace_grep, workspace_git |
| Human-in-the-loop | ask_user |
| Coordination | spawn_agents, list_available_agents |
| Skills | skill |
Specify tools as a comma-separated list in the agent definition. Glob patterns are supported (e.g. graph_*).
Skills
Section titled “Skills”Skills are reusable Markdown workflow instructions stored in the database. An agent with the skill tool can load any skill by name at runtime, keeping system prompts lean and instructions easy to update without redeploying agents.
How it works
Section titled “How it works”- At run start, the executor retrieves the skills available to the agent (global + project-scoped, with project skills winning on name collision).
- If the total skill count is ≤ 50, all skill names and descriptions are listed in the tool description. If > 50, the executor embeds the agent’s trigger message and surfaces the top-10 semantically relevant skills.
- The agent calls
skill({name: "..."})to load a skill’s full Markdown content.
Opt in via the agent definition
Section titled “Opt in via the agent definition”Add "skill" to the agent’s tools list:
memory defs create \ --name "onboarding-agent" \ --system-prompt "You onboard new team members. Use the skill tool to load relevant playbooks." \ --model "gemini-2.0-flash" \ --tools "skill,graph_query,graph_create_object"Or update an existing definition:
memory defs update <definition-id> --tools "skill,search,graph_query"Manage skills via the CLI
Section titled “Manage skills via the CLI”Skills use a lowercase slug name (e.g. my-skill, max 64 characters). Letters, digits and single hyphens or dots are allowed; dots are reserved for learned skills (see below).
List skills
memory skills list # global skillsmemory skills list --project <project-id> # global + project-scoped, mergedCreate a skill
memory skills create \ --name "deploy-checklist" \ --description "Step-by-step deployment checklist for production releases" \ --content-file ./deploy-checklist.md
# Project-scoped (overrides a global skill with the same name within this project)memory skills create \ --name "deploy-checklist" \ --description "Custom deploy steps for this project" \ --content-file ./my-deploy.md \ --project <project-id>Import from a SKILL.md file (YAML frontmatter format)
memory skills import ./path/to/SKILL.mdmemory skills import ./path/to/SKILL.md --project <project-id>The file must have name and description in YAML frontmatter:
---name: deploy-checklistdescription: Step-by-step deployment checklist for production releases---# Deploy Checklist
1. Run tests2. Tag the release...Get, update, delete
memory skills get <id>memory skills update <id> --description "Updated description"memory skills update <id> --content-file ./new-content.mdmemory skills delete <id>memory skills delete <id> --confirm # skip confirmation promptScope and visibility
Section titled “Scope and visibility”| Scope | Created via | Visible to |
|---|---|---|
| Global | POST /api/skills (no project) |
All agents in all projects |
| Project-scoped | POST /api/projects/:id/skills |
Agents in that project only |
When a project-scoped skill has the same name as a global skill, the project-scoped version takes precedence for agents in that project.
Seed from existing SKILL.md files
Section titled “Seed from existing SKILL.md files”If you have existing .agents/skills/*/SKILL.md files following the OpenCode format, import them all at once:
for f in .agents/skills/*/SKILL.md; do memory skills import "$f"doneAutomatic skill capture (opt-in)
Section titled “Automatic skill capture (opt-in)”An agent can learn from its own successful runs: a bounded background review turns a run into a staged proposal, and a human decides whether it becomes a skill. The feature is off everywhere until a project opts in.
Enable it on a project
Open Settings → General → Skill capture and pick a mode (off, suggest,
or auto). The Auto-apply captured skills toggle sits below it and is only
enabled in auto. Or PATCH the project:
curl -X PATCH "$MEMORY_API/api/projects/$PROJECT_ID" \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{"skill_capture": {"mode": "suggest"}}'mode is off (default), suggest, or auto. suggest is the recommended
starting point: every candidate waits for approval. auto additionally requires
auto-apply to be on (the toggle above, or "autoApply": true in the API), and
passes only when the candidate is clean, confident, not a duplicate, not a
delete, within the daily caps, and the agent has at least one previously
approved proposal. Deletes are always human-reviewed.
Narrow it per agent
Each agent’s Settings → Skills page has an Automatic skill capture control:
Inherit project setting, Suggest only, or Off. The same override is
available as skillCapture: {"mode": "off"} on the agent definition. It can only
narrow the project policy — it never widens it, so the project mode stays the
master switch. An override that is not set inherits the project value.
What the agent writes. Learned skills are named {agent-slug}.{topic} (for
example research-assistant.handling-empty-results) and are auto-loaded on the
next run when the agent has autoLoadSkills enabled. Skills the agent writes are
marked as agent-created; the scheduled curator ages them active → stale → archived when unused. Pin a skill to stop ageing, or lock it to refuse further
agent writes.
Archived skills stay in the Agents → Skills list, marked with an Archived
badge, but are no longer loaded or retrieved by agents. Use Restore or
Restore & pin on that row (or open the skill first) to return it to active;
Restore & pin also pins it so the curator never ages it out again. Restoring
preserves every other metadata field. The same action is available over the API:
POST /api/projects/:projectId/skills/:id/restore # optional body: {"pin": true}Review the inbox
Open Agents → Skills. A Proposed skills panel sits above the skill list and shows every pending proposal: the skill name, the agent it came from, the change kind (create, patch or delete), the capture confidence, and the current linter and security findings. Approve applies the proposal; Reject discards it. Both actions return to the same panel, and a failed approve — the security scan runs again and can still block the write — leaves the proposal pending and shows the error. Approved and rejected proposals drop out of the panel; it lists pending decisions only.
The same inbox is available over the API:
GET /api/projects/:projectId/skills/proposals # pending by defaultGET /api/projects/:projectId/skills/proposals/:proposalIdPOST /api/projects/:projectId/skills/proposals/:proposalId/approvePOST /api/projects/:projectId/skills/proposals/:proposalId/rejectApproving applies the proposal through the normal skill write path, so content hashes, embeddings and provenance stay consistent. The security scan runs again at approval.
Operators can stop the whole loop without a migration by setting
MEMORY_SKILL_CAPTURE_DISABLED=1.
Google Native Tools
Section titled “Google Native Tools”Gemini models expose a set of built-in tools that are invoked directly by the model — no function-calling round-trip required. You opt into them per agent definition.
| Tool | What it does | Minimum model |
|---|---|---|
google_search |
Live web search via Google | Gemini 2.0 Flash |
code_execution |
Runs Python in a sandboxed environment; output is returned to the model | Gemini 2.0 Flash |
url_context |
Fetches and reads the content of URLs mentioned in the conversation | Gemini 2.5 Flash |
Configure via the Admin UI
Section titled “Configure via the Admin UI”- Go to Settings → Project → Agent Definitions.
- Click New Definition or edit an existing one.
- Under Model Configuration, enter a Gemini model name (e.g.
gemini-2.5-flash-preview-0514). - Check the native tools you want to enable.
- Click Save Definition.
Configure via the API
Section titled “Configure via the API”Include nativeTools in the model object when creating or updating a definition:
{ "name": "web-researcher", "systemPrompt": "You are a research assistant. Use web search to find current information.", "model": { "name": "gemini-2.5-flash-preview-0514", "temperature": 1.0, "nativeTools": ["google_search", "url_context"] }}PATCH /api/projects/{projectId}/agent-definitions/{id} accepts the same shape.
Configure via Blueprints
Section titled “Configure via Blueprints”name: web-researchersystemPrompt: | You are a research assistant. Use web search to find current information.model: name: gemini-2.5-flash-preview-0514 temperature: 1.0 nativeTools: - google_search - url_contexttools: - graph_create_object - graph_queryvisibility: projectModel support matrix
Section titled “Model support matrix”| Model | google_search |
url_context |
code_execution |
|---|---|---|---|
gemini-2.5-pro-* |
✓ | ✓ | ✓ |
gemini-2.5-flash-* |
✓ | ✓ | ✓ |
gemini-2.5-flash-lite-* |
✓ | ✓ | ✓ |
gemini-2.0-flash-* |
✓ | — | ✓ |
gemini-2.0-flash-lite-* |
— | — | — |
gemini-3-flash-* |
✓ | ✓ | ✓ |
gemini-3-pro-* |
✓ | ✓ | ✓ |
url_context was introduced in the Gemini 2.5 generation. Image generation variants (*-image-preview) support google_search only.
Blueprints (GitOps)
Section titled “Blueprints (GitOps)”Define agent definitions as YAML and apply them repeatably. Blueprints can also carry schema packs, skills, and seed data — see Blueprints.
name: document-summarizersystemPrompt: | You are an expert at summarizing technical documents.model: name: gemini-2.0-flash temperature: 0.7 maxSteps: 20tools: - search - graph_queryvisibility: projectmemory blueprints install ./my-blueprints --project my-projectmemory blueprints install ./my-blueprints --dry-run # preview onlymemory blueprints install ./my-blueprints --upgrade # update existingQuick Reference
Section titled “Quick Reference”# Definitionsmemory defs listmemory defs create --name <n> --system-prompt <p> --model <m> --tools <t1,t2>memory defs update <id> [flags]memory defs delete <id>
# Agentsmemory agents listmemory agents create --name <n> --trigger-type manual|schedule|reaction|webhookmemory agents trigger <id>memory agents runs <id> [--limit <n>]memory agents update <id> [flags]memory agents delete <id>
# Human-in-the-loopmemory agents questions list-project [--status pending]memory agents questions respond <question-id> "<answer>"
# Webhook hooksmemory agents hooks list <agent-id>memory agents hooks create <agent-id> --label <l>memory agents hooks delete <agent-id> <hook-id>
# Skillsmemory skills list [--project <id>] [--global]memory skills get <id>memory skills create --name <n> --description <d> --content-file <path> [--project <id>]memory skills update <id> [--description <d>] [--content-file <path>]memory skills delete <id> [--confirm]memory skills import <path/to/SKILL.md> [--project <id>]Safety Limits
Section titled “Safety Limits”| Limit | Default |
|---|---|
| Max steps per run | 500 (configurable via --max-steps) |
| Doom loop detection | Halts after 5 consecutive identical tool calls |
| Webhook rate limiting | Configurable per hook via --rate-limit (req/min) |