Skip to content

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.

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.


The definition controls what the agent does.

Terminal window
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.


The agent controls when the definition runs.

Terminal window
memory agents create \
--name "doc-summarizer" \
--trigger-type manual

Terminal window
memory agents trigger <agent-id>

Terminal window
memory agents runs <agent-id> --limit 10
1. 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 exceeded

Statuses: running · completed · failed · skipped · cancelled


If the agent includes the ask_user tool, execution pauses when the agent calls it and waits for your response.

Terminal window
memory agents questions list-project --status pending
Terminal window
memory agents questions respond <question-id> "My answer here"

Webhooks let external systems (CI/CD, GitHub Actions) trigger an agent via HTTP.

Terminal window
memory agents hooks create <agent-id> \
--label "GitHub Actions" \
--rate-limit 30 \
--burst-size 5
Terminal window
curl -X POST https://api.example.com/api/webhooks/agents/<hook-id> \
-H "Authorization: Bearer <token>"
Terminal window
memory agents hooks list <agent-id>
memory agents hooks delete <agent-id> <hook-id>

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 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.

  1. At run start, the executor retrieves the skills available to the agent (global + project-scoped, with project skills winning on name collision).
  2. 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.
  3. The agent calls skill({name: "..."}) to load a skill’s full Markdown content.

Add "skill" to the agent’s tools list:

Terminal window
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:

Terminal window
memory defs update <definition-id> --tools "skill,search,graph_query"

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

Terminal window
memory skills list # global skills
memory skills list --project <project-id> # global + project-scoped, merged

Create a skill

Terminal window
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)

Terminal window
memory skills import ./path/to/SKILL.md
memory skills import ./path/to/SKILL.md --project <project-id>

The file must have name and description in YAML frontmatter:

---
name: deploy-checklist
description: Step-by-step deployment checklist for production releases
---
# Deploy Checklist
1. Run tests
2. Tag the release
...

Get, update, delete

Terminal window
memory skills get <id>
memory skills update <id> --description "Updated description"
memory skills update <id> --content-file ./new-content.md
memory skills delete <id>
memory skills delete <id> --confirm # skip confirmation prompt
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.

If you have existing .agents/skills/*/SKILL.md files following the OpenCode format, import them all at once:

Terminal window
for f in .agents/skills/*/SKILL.md; do
memory skills import "$f"
done

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:

Terminal window
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:

Terminal window
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:

Terminal window
GET /api/projects/:projectId/skills/proposals # pending by default
GET /api/projects/:projectId/skills/proposals/:proposalId
POST /api/projects/:projectId/skills/proposals/:proposalId/approve
POST /api/projects/:projectId/skills/proposals/:proposalId/reject

Approving 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.


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
  1. Go to Settings → Project → Agent Definitions.
  2. Click New Definition or edit an existing one.
  3. Under Model Configuration, enter a Gemini model name (e.g. gemini-2.5-flash-preview-0514).
  4. Check the native tools you want to enable.
  5. Click Save Definition.

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.

agents/web-researcher.yaml
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
tools:
- graph_create_object
- graph_query
visibility: project
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.


Define agent definitions as YAML and apply them repeatably. Blueprints can also carry schema packs, skills, and seed data — see Blueprints.

agents/document-summarizer.yaml
name: document-summarizer
systemPrompt: |
You are an expert at summarizing technical documents.
model:
name: gemini-2.0-flash
temperature: 0.7
maxSteps: 20
tools:
- search
- graph_query
visibility: project
Terminal window
memory blueprints install ./my-blueprints --project my-project
memory blueprints install ./my-blueprints --dry-run # preview only
memory blueprints install ./my-blueprints --upgrade # update existing

Terminal window
# Definitions
memory defs list
memory defs create --name <n> --system-prompt <p> --model <m> --tools <t1,t2>
memory defs update <id> [flags]
memory defs delete <id>
# Agents
memory agents list
memory agents create --name <n> --trigger-type manual|schedule|reaction|webhook
memory agents trigger <id>
memory agents runs <id> [--limit <n>]
memory agents update <id> [flags]
memory agents delete <id>
# Human-in-the-loop
memory agents questions list-project [--status pending]
memory agents questions respond <question-id> "<answer>"
# Webhook hooks
memory agents hooks list <agent-id>
memory agents hooks create <agent-id> --label <l>
memory agents hooks delete <agent-id> <hook-id>
# Skills
memory 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>]

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)