Agentcore MCP — VS Code Extension

Persistent memory for AI agents. Install → use. No accounts, no API keys, no setup.

Agentcore MCP gives GitHub Copilot, Cursor, and any MCP-compatible AI a local knowledge store: task board, event log, entity graph, and search — all in ~/.agentcore/agentcore.sqlite.

Quick start

1. Install from the VS Code Marketplace (search @mcp agentcore)
2. Open Copilot Chat → Agent Mode
3. Start using tools — the database is created automatically on first use

That's it. No configuration required.

For AI assistants

Agentcore is your memory across sessions. VS Code workspace tools answer questions about code in the repo. Agentcore answers questions about what was logged: tasks, decisions, lessons, questions between agents, and structured facts. If the user only needs the codebase, skip MCP.

Session start

When a chat opens, reloads, or the user asks "where are we?":

• Call session_snapshot — returns tasks + open questions in one round-trip.
• If no active tasks, surface completed or recent work. Say "no active tasks, here's what was completed recently" — don't just say "nothing found."
• get_tasks / get_questions separately is fine when you only need one.

Recall

• Stored facts → get_facts, then get_linked if you have an entity ID.
• Searching events → search with a concrete phrase, ID, or error string. If you don't know what to look for, ask the user — don't fish with vague queries.
• deep_search → only after search returned nothing, or when Azure AI Search is configured. Never repeat the same query twice.

While working

• log_event and task lifecycle tools (start_task … rework_task) when work moves forward or ownership changes. Not every short reply.
• add_entity, save_decision, save_lesson when something should survive the session.
• warm_start only when you have a specific task_id and need that thread's recent events.

Stop and ask

If the request is ambiguous, you're missing scope (project, task ID, what "it" refers to), or Agentcore is empty after one sensible pass (session_snapshot + at most one get_facts or search with a stated target) — stop calling tools and ask the user one short question. Do not loop, rephrase, or retry silently.

Optional

• get_agentcore_routing — returns a JSON playbook explaining tool layers. Call once if the layer tags ([L0]…[L3]) in tool descriptions are unclear. Not required every session.
• ask_team, export_data, import_data — when the workflow calls for them.

What it does

~22 tools organized by layer (exact list: get_agentcore_routing).

L0 Orient — session_snapshot, get_tasks, get_questions, search, deep_search, get_agentcore_routing L1 Execute — log_event, start_task, update_task, complete_task, fail_task, block_task, rework_task L2 Structure — add_entity, get_facts, get_linked, save_decision, save_lesson, warm_start L3 Collab / Portability — ask_team, export_data, import_data

Storage

~/.agentcore/agentcore.sqlite — single file, copy it or use export_data/import_data to move between machines.

Requirements

VS Code 1.99+ with GitHub Copilot (Agent mode) or any MCP-compatible client.

Troubleshooting

“MCP server failed to start” (Copilot Agent) — When VS Code asks to start MCP servers, choose Start for Agentcore MCP. In Settings, set agentcore.storageBackend to local (Cosmos is not implemented yet). v0.1.7+ merges the extension host environment with Agentcore variables so node and sql.js keep a normal PATH and HOME. v0.1.8+ fixes a bundled MCP server parse error (fileURLToPath declared twice) on newer Node.

To smoke-test the server: open the installed extension folder (Extensions → Agentcore MCP → right-click → Open Extension Folder), then run:

export DATA_DIR="$HOME/.agentcore"
export STORAGE_BACKEND=local
node dist/mcp/server.mjs

It speaks MCP over stdio (no banner); press Ctrl+C to exit.

Copilot / Cursor prompt setup

For best results, add these rules to your project so the AI knows how to use Agentcore:

Replace YOUR_PROJECT_ROOT with your workspace path. The same five rules go in both files; Cursor adds YAML front-matter.

.github/copilot-instructions.md

cd YOUR_PROJECT_ROOT
mkdir -p .github
cat > .github/copilot-instructions.md <<'EOF'
# Agentcore MCP — Agent mode

1. New chat / reload / "where are we?" → session_snapshot (one call). Surface completed work when no active tasks exist — don't just say "nothing found."
2. Recall: get_facts for stored knowledge, search with a concrete phrase. Ask the user if you don't know what to search for — don't fish with vague queries. deep_search only after search failed once or Azure is in play.
3. log_event + task tools when work advances. add_entity / save_decision / save_lesson for durable memory. Not every short reply.
4. get_agentcore_routing once if tool layers (L0–L3) are unclear. warm_start only with a specific task_id.
5. After one sensible pass (snapshot + at most one search/get_facts with a stated target), stop tools and ask the user one short question. Do not loop, rephrase, or retry silently.
EOF

.cursor/rules/agentcore-mcp.mdc

cd YOUR_PROJECT_ROOT
mkdir -p .cursor/rules
cat > .cursor/rules/agentcore-mcp.mdc <<'EOF'
---
description: Agentcore MCP — persistent memory for agents
alwaysApply: true
---

# Agentcore MCP — Agent mode

1. New chat / reload / "where are we?" → session_snapshot (one call). Surface completed work when no active tasks exist — don't just say "nothing found."
2. Recall: get_facts for stored knowledge, search with a concrete phrase. Ask the user if you don't know what to search for — don't fish with vague queries. deep_search only after search failed once or Azure is in play.
3. log_event + task tools when work advances. add_entity / save_decision / save_lesson for durable memory. Not every short reply.
4. get_agentcore_routing once if tool layers (L0–L3) are unclear. warm_start only with a specific task_id.
5. After one sensible pass (snapshot + at most one search/get_facts with a stated target), stop tools and ask the user one short question. Do not loop, rephrase, or retry silently.
EOF

Global Copilot — Open code "$HOME/Library/Application Support/Code/User/settings.json" (Linux: ~/.config/Code/User/settings.json, Windows: %APPDATA%\Code\User\settings.json) → Copilot → Custom instructions → paste the same five rules.

Global Cursor — Settings → Rules, or ~/.cursor/rules/agentcore-mcp.mdc with the same YAML + five rules.

Put .github / .cursor under the folder you opened as the workspace.

Settings (optional)

License

MIT