chore: import upstream snapshot with attribution
This commit is contained in:
wehub-resource-sync
@@ -0,0 +1,38 @@
|
||||
# Troubleshooting agentmemory skills
|
||||
|
||||
Shared recovery steps for all user-invocable agentmemory skills. Each skill's
|
||||
Troubleshooting section points here instead of duplicating the block.
|
||||
|
||||
## "MCP tool not available"
|
||||
|
||||
If a `memory_*` MCP tool does not appear, the stdio MCP shim never started.
|
||||
Walk these in order:
|
||||
|
||||
1. Run `/plugin list` in the host and confirm `agentmemory` shows as enabled.
|
||||
2. Restart the host. The plugin's `.mcp.json` is only read on startup, so a
|
||||
freshly installed or re-enabled plugin will not register tools mid-session.
|
||||
3. Check `/mcp` and confirm the `agentmemory` server shows a live connection.
|
||||
|
||||
## REST fallback
|
||||
|
||||
When the MCP tools stay unavailable but the daemon is running, call the REST
|
||||
API directly:
|
||||
|
||||
1. Set `AGENTMEMORY_URL` to the daemon base URL (default `http://localhost:3111`).
|
||||
2. Add `Authorization: Bearer $AGENTMEMORY_SECRET` ONLY when `AGENTMEMORY_SECRET`
|
||||
is set. The default localhost daemon is open and rejects a stray header.
|
||||
|
||||
Endpoint map by skill:
|
||||
|
||||
| Skill | REST call |
|
||||
| --------------- | --------------------------------------------------------------- |
|
||||
| remember | `POST /agentmemory/remember` |
|
||||
| recall | `POST /agentmemory/smart-search` |
|
||||
| recap | `GET /agentmemory/sessions` + `POST /agentmemory/smart-search` |
|
||||
| handoff | `GET /agentmemory/sessions` + `POST /agentmemory/smart-search` |
|
||||
| session-history | `GET /agentmemory/sessions` |
|
||||
| commit-context | `GET /agentmemory/session/by-commit?sha=<sha>` |
|
||||
| commit-history | `GET /agentmemory/commits` (URL-encode every query param) |
|
||||
|
||||
The daemon reads `.mcp.json` on startup only, so any port or auth change needs a
|
||||
restart before either transport sees it.
|
||||
@@ -0,0 +1,28 @@
|
||||
# agentmemory connect adapters reference
|
||||
|
||||
Generated from `src/cli/connect/index.ts`. Do not edit the block below by hand; run `npm run skills:gen` after adding or removing an adapter.
|
||||
|
||||
<!-- AUTOGEN:agents START - generated by scripts/skills/generate.ts, do not edit by hand -->
|
||||
`agentmemory connect <agent>` wires the memory server into a host agent. 18 adapters:
|
||||
|
||||
| Agent | Name | Protocol |
|
||||
| --- | --- | --- |
|
||||
| Antigravity | `antigravity` | Using MCP via mcp_config.json. Antigravity replaces Gemini CLI (sunset 2026-06-18). |
|
||||
| Claude Code | `claude-code` | Using MCP. Hooks are also available, see https://github.com/rohitg00/agentmemory#claude-code-one-block-paste-it. |
|
||||
| Cline | `cline` | Using MCP via ~/.cline/mcp.json (CLI). VS Code users: add the same block via Cline Settings → MCP Servers → Edit JSON. |
|
||||
| Codex CLI | `codex` | Using MCP. Hooks ship via the Codex plugin; on Codex Desktop, also pass --with-hooks to install the global hooks.json workaround for openai/codex#16430. |
|
||||
| Continue | `continue` | Using MCP via ~/.continue/config.yaml (preferred) or config.json (legacy, only when no yaml). |
|
||||
| GitHub Copilot CLI | `copilot-cli` | Using MCP. Install the plugin too for full hooks/skills coverage. |
|
||||
| Cursor | `cursor` | Using MCP (the only protocol Cursor speaks). Memory bridge runs at :3111 underneath. |
|
||||
| Droid (Factory.ai) | `droid` | Using MCP via ~/.factory/mcp.json. The `/mcp` slash command inside droid lists configured servers. |
|
||||
| Gemini CLI | `gemini-cli` | Using MCP (the only protocol Gemini CLI speaks). Memory bridge runs at :3111 underneath. |
|
||||
| Hermes Agent | `hermes` | Using MCP. Hooks are also available, see https://github.com/rohitg00/agentmemory/tree/main/integrations/hermes. |
|
||||
| Kiro | `kiro` | Using MCP via ~/.kiro/settings/mcp.json (user-level). Workspace overrides live in .kiro/settings/mcp.json. |
|
||||
| OpenClaw | `openclaw` | Using MCP. Hooks are also available, see https://github.com/rohitg00/agentmemory/tree/main/integrations/openclaw. |
|
||||
| OpenCode | `opencode` | Using MCP via ~/.config/opencode/opencode.json (top-level `mcp` key). For full auto-capture, also install the bundled plugin in plugin/opencode/. |
|
||||
| OpenHuman | `openhuman` | Using native hooks (REST API at :3111). MCP not required. |
|
||||
| pi | `pi` | Using native hooks (REST API at :3111). MCP not required. |
|
||||
| Qwen Code | `qwen` | Using MCP via ~/.qwen/settings.json. Qwen Code's hook system can also be wired separately, see docs. |
|
||||
| Warp | `warp` | Using MCP via ~/.warp/.mcp.json. Skills auto-discover from .claude/skills/ if the Claude Code plugin is also installed. |
|
||||
| Zed | `zed` | Using MCP via ~/.config/zed/settings.json (key: context_servers). |
|
||||
<!-- AUTOGEN:agents END -->
|
||||
@@ -0,0 +1,34 @@
|
||||
---
|
||||
name: agentmemory-agents
|
||||
description: How agentmemory wires into host coding agents via the connect command. Use when installing agentmemory into a specific agent, when asked which agents are supported, or when a connect adapter writes the wrong config path.
|
||||
user-invocable: false
|
||||
---
|
||||
|
||||
`agentmemory connect <agent>` merges the memory server into a host agent's config and preserves any existing servers. REST is the underlying protocol; for MCP-only hosts the adapter wires the stdio MCP bridge.
|
||||
|
||||
## Quick start
|
||||
|
||||
```bash
|
||||
agentmemory connect claude-code # or cursor, codex, gemini-cli, ...
|
||||
```
|
||||
|
||||
After wiring, restart the host or run its MCP reload (for example `/mcp` in Claude Code) so it picks up the server. Then confirm the agent lists agentmemory's tools.
|
||||
|
||||
## Workflow
|
||||
|
||||
1. Detect the calling agent. If unknown, default to `claude-code`.
|
||||
2. Run `agentmemory connect <name>` using a name from the table in REFERENCE.md.
|
||||
3. Verify: the host should show the full tool set with a server running. Only 7 tools means the MCP shim could not reach a server (see ../_shared/TROUBLESHOOTING.md).
|
||||
|
||||
## Notes
|
||||
|
||||
- The action skills (remember, recall, and the rest) are installed separately with `npx skills add rohitg00/agentmemory`. `connect` makes tools available; skills teach the agent when to use them.
|
||||
- Windows: use WSL2. Native Windows runs the server but `connect` is not supported there.
|
||||
|
||||
## See also
|
||||
|
||||
- agentmemory-mcp-tools, agentmemory-rest-api, agentmemory-hooks.
|
||||
|
||||
## Reference
|
||||
|
||||
The full adapter list with display names and protocol notes lives in REFERENCE.md, generated from `src/cli/connect/`.
|
||||
@@ -0,0 +1,33 @@
|
||||
---
|
||||
name: agentmemory-architecture
|
||||
description: How agentmemory is built, the iii engine primitives it runs on, its storage model, ports, and the viewer. Use when reasoning about how memory is stored or retrieved end to end, when extending the system, or when answering how agentmemory works under the hood.
|
||||
user-invocable: false
|
||||
---
|
||||
|
||||
agentmemory is a memory server for coding agents. It runs locally, captures observations, indexes them for hybrid retrieval, and serves them back over REST and MCP. It is built on the iii engine.
|
||||
|
||||
## iii primitives
|
||||
|
||||
Everything is a function, a trigger, or worker state on the iii engine. There is no separate plugin system; the worker registers functions (`mem::*`) and HTTP triggers (`api::*`) and the engine routes calls. agentmemory does not bypass iii; new capability is a new function plus a trigger.
|
||||
|
||||
## Retrieval model
|
||||
|
||||
Recall is hybrid: BM25 keyword search plus vector similarity plus graph expansion over linked concepts. The default install needs no API key because embeddings run on-device and BM25 needs none. An LLM provider only adds richer summaries and auto-injection, both opt-in.
|
||||
|
||||
## Storage and lifecycle
|
||||
|
||||
Memories carry content, concepts, files, importance, and timestamps, grouped into sessions and optionally linked to commits. A lifecycle of capture, compress, consolidate, and forget keeps the store useful over time rather than letting it grow unbounded.
|
||||
|
||||
## Ports
|
||||
|
||||
REST is the anchor at 3111. Streams = N+1 (3112), viewer = N+2 (3113), engine = N+46023 (49134). `--instance N` shifts the whole block by N*100.
|
||||
|
||||
## Viewer
|
||||
|
||||
A real-time web viewer at `http://localhost:3113` shows memory building as sessions run. Useful for demos and for confirming capture is working.
|
||||
|
||||
## See also
|
||||
|
||||
- agentmemory-mcp-tools and agentmemory-rest-api for the surfaces.
|
||||
- agentmemory-hooks for automatic capture.
|
||||
- agentmemory-config for ports and feature flags.
|
||||
@@ -0,0 +1,42 @@
|
||||
# agentmemory configuration reference
|
||||
|
||||
Generated by scanning `src/` for `AGENTMEMORY_*` usage. Do not edit the block below by hand; run `npm run skills:gen` after adding or removing a variable. Internal markers ending in two underscores are excluded.
|
||||
|
||||
<!-- AUTOGEN:env START - generated by scripts/skills/generate.ts, do not edit by hand -->
|
||||
Configuration is read from the environment and from `~/.agentmemory/.env` (no `export` prefix). 34 recognized variables:
|
||||
|
||||
- `AGENTMEMORY_AGENT_SCOPE`
|
||||
- `AGENTMEMORY_ALLOW_AGENT_SDK`
|
||||
- `AGENTMEMORY_AUTO_COMPRESS`
|
||||
- `AGENTMEMORY_COMMIT_SHA`
|
||||
- `AGENTMEMORY_COPILOT_MCP_BLOCK`
|
||||
- `AGENTMEMORY_CWD`
|
||||
- `AGENTMEMORY_DEBUG`
|
||||
- `AGENTMEMORY_DROP_STALE_INDEX`
|
||||
- `AGENTMEMORY_EXPORT_ROOT`
|
||||
- `AGENTMEMORY_FOLLOWUP_WINDOW_SECONDS`
|
||||
- `AGENTMEMORY_FORCE_PROXY`
|
||||
- `AGENTMEMORY_GRAPH_WEIGHT`
|
||||
- `AGENTMEMORY_III_CONFIG`
|
||||
- `AGENTMEMORY_III_VERSION`
|
||||
- `AGENTMEMORY_IMAGE_EMBEDDINGS`
|
||||
- `AGENTMEMORY_IMAGE_STORE_MAX_BYTES`
|
||||
- `AGENTMEMORY_INJECT_CONTEXT`
|
||||
- `AGENTMEMORY_LLM_TIMEOUT_MS`
|
||||
- `AGENTMEMORY_MCP_BLOCK`
|
||||
- `AGENTMEMORY_PROBE_TIMEOUT_MS`
|
||||
- `AGENTMEMORY_PROJECT_NAME`
|
||||
- `AGENTMEMORY_PROVIDER`
|
||||
- `AGENTMEMORY_REFLECT`
|
||||
- `AGENTMEMORY_SDK_CHILD`
|
||||
- `AGENTMEMORY_SECRET`
|
||||
- `AGENTMEMORY_SESSION_ID`
|
||||
- `AGENTMEMORY_SLOTS`
|
||||
- `AGENTMEMORY_SUPPRESS_COST_WARNING`
|
||||
- `AGENTMEMORY_TOOLS`
|
||||
- `AGENTMEMORY_URL`
|
||||
- `AGENTMEMORY_USE_DOCKER`
|
||||
- `AGENTMEMORY_VERBOSE`
|
||||
- `AGENTMEMORY_VIEWER_HOST`
|
||||
- `AGENTMEMORY_VIEWER_URL`
|
||||
<!-- AUTOGEN:env END -->
|
||||
@@ -0,0 +1,37 @@
|
||||
---
|
||||
name: agentmemory-config
|
||||
description: agentmemory configuration, environment variables, ports, and feature flags. Use when enabling a feature, changing ports, setting an API key, configuring auth, or explaining why a feature is off by default.
|
||||
user-invocable: false
|
||||
---
|
||||
|
||||
agentmemory reads configuration from the environment and from `~/.agentmemory/.env` (one `KEY=value` per line, no `export` prefix). Restart the server after changing it.
|
||||
|
||||
## Quick start
|
||||
|
||||
Enable richer memory and set a provider key in `~/.agentmemory/.env`:
|
||||
|
||||
```env
|
||||
ANTHROPIC_API_KEY=sk-ant-...
|
||||
AGENTMEMORY_AUTO_COMPRESS=true
|
||||
AGENTMEMORY_INJECT_CONTEXT=true
|
||||
```
|
||||
|
||||
## Defaults worth knowing
|
||||
|
||||
- No API key is required. Without one, agentmemory runs zero-LLM with BM25 plus local embeddings.
|
||||
- Token-spending features ship OFF on purpose: `AGENTMEMORY_AUTO_COMPRESS` (LLM summaries) and `AGENTMEMORY_INJECT_CONTEXT` (auto context injection) both cost tokens proportional to tool-use frequency.
|
||||
- Tool visibility: `AGENTMEMORY_TOOLS=all` (default) or `core` for the lean set.
|
||||
- Auth: set `AGENTMEMORY_SECRET` to require `Authorization: Bearer` on the REST API.
|
||||
|
||||
## Ports
|
||||
|
||||
REST is the anchor at 3111. Streams = N+1 (3112), viewer = N+2 (3113), engine = N+46023 (49134). Relocate the whole block with `--port <N>` or `--instance <N>`.
|
||||
|
||||
## See also
|
||||
|
||||
- agentmemory-rest-api for how the secret is used.
|
||||
- agentmemory-architecture for the port quartet rationale.
|
||||
|
||||
## Reference
|
||||
|
||||
The full recognized-variable list lives in REFERENCE.md, generated by scanning `src/`.
|
||||
@@ -0,0 +1,20 @@
|
||||
# agentmemory hooks reference
|
||||
|
||||
Generated from `plugin/hooks/hooks.json`. Do not edit the block below by hand; run `npm run skills:gen` after changing the hook registration.
|
||||
|
||||
<!-- AUTOGEN:hooks START - generated by scripts/skills/generate.ts, do not edit by hand -->
|
||||
The Claude Code plugin registers hooks on 12 lifecycle events to capture observations automatically:
|
||||
|
||||
- `Notification`
|
||||
- `PostToolUse`
|
||||
- `PostToolUseFailure`
|
||||
- `PreCompact`
|
||||
- `PreToolUse`
|
||||
- `SessionEnd`
|
||||
- `SessionStart`
|
||||
- `Stop`
|
||||
- `SubagentStart`
|
||||
- `SubagentStop`
|
||||
- `TaskCompleted`
|
||||
- `UserPromptSubmit`
|
||||
<!-- AUTOGEN:hooks END -->
|
||||
@@ -0,0 +1,39 @@
|
||||
---
|
||||
name: agentmemory-hooks
|
||||
description: The agentmemory plugin hooks that capture observations automatically across the agent session lifecycle. Use when explaining how memory gets captured without manual saves, when debugging missing observations, or when tuning what gets recorded.
|
||||
user-invocable: false
|
||||
---
|
||||
|
||||
The Claude Code plugin registers lifecycle hooks so memory is captured automatically. You do not have to call `memory_save` for routine work; the hooks observe tool use, prompts, and session boundaries and write observations for you.
|
||||
|
||||
## Quick start
|
||||
|
||||
Install the plugin and the hooks register themselves:
|
||||
|
||||
```bash
|
||||
/plugin marketplace add rohitg00/agentmemory
|
||||
/plugin install agentmemory
|
||||
```
|
||||
|
||||
Watch observations land live at `http://localhost:3113`.
|
||||
|
||||
## What the hooks do
|
||||
|
||||
- Session start and end frame each unit of work and let `handoff` resume it.
|
||||
- Tool-use hooks capture what changed and why, the raw material for `recall` and `recap`.
|
||||
- Prompt-submit captures intent. Pre-compact preserves context before the host trims it.
|
||||
- A post-commit hook links commits to sessions, which powers `commit-context` and `commit-history`.
|
||||
|
||||
## Important
|
||||
|
||||
- Capture is on by default and is zero-LLM. Turning observations into LLM summaries (`AGENTMEMORY_AUTO_COMPRESS`) and injecting them back into context (`AGENTMEMORY_INJECT_CONTEXT`) are separate opt-ins because they spend tokens.
|
||||
- If observations are missing, confirm the plugin is enabled and the server is running. See ../_shared/TROUBLESHOOTING.md.
|
||||
|
||||
## See also
|
||||
|
||||
- agentmemory-config for the capture and injection flags.
|
||||
- The handoff, recap, and session-history skills consume what these hooks record.
|
||||
|
||||
## Reference
|
||||
|
||||
The exact registered hook events live in REFERENCE.md, generated from `plugin/hooks/hooks.json`.
|
||||
@@ -0,0 +1,65 @@
|
||||
# agentmemory MCP tools reference
|
||||
|
||||
Generated from `src/mcp/tools-registry.ts`. Do not edit the block below by hand; run `npm run skills:gen` after changing the registry.
|
||||
|
||||
<!-- AUTOGEN:tools START - generated by scripts/skills/generate.ts, do not edit by hand -->
|
||||
agentmemory exposes 53 MCP tools. 8 are in the lean core set (`--tools core` or `AGENTMEMORY_TOOLS=core`); the rest load with `--tools all` (default).
|
||||
|
||||
| Tool | Core | Parameters | Purpose |
|
||||
| --- | --- | --- | --- |
|
||||
| `memory_action_create` | | `title`*: string, `description`: string, `priority`: number, `project`: string, `tags`: string, `parentId`: string, `requires`: string | Create an actionable work item with typed dependencies. Actions track what agents need to do and how work items relate to each other. |
|
||||
| `memory_action_update` | | `actionId`*: string, `status`: string, `result`: string, `priority`: number | Update an action's status, priority, or details. Set status to 'done' to complete it and unblock dependent actions. |
|
||||
| `memory_audit` | | `operation`: string, `limit`: number | View the audit trail of memory operations. |
|
||||
| `memory_checkpoint` | | `operation`*: string, `name`: string, `checkpointId`: string, `status`: string, `type`: string, `linkedActionIds`: string | Create or resolve an external checkpoint (CI result, approval, deploy status) that gates action progress. |
|
||||
| `memory_claude_bridge_sync` | | `direction`*: string | Sync memory state to/from Claude Code's native MEMORY.md file. |
|
||||
| `memory_commit_lookup` | | `sha`*: string | Look up the agent session(s) that produced a specific git commit, given its SHA. Returns the commit metadata and linked sessions. |
|
||||
| `memory_commits` | | `branch`: string, `repo`: string, `limit`: number | List recent commits linked to agent sessions, optionally filtered by branch or repo. |
|
||||
| `memory_compress_file` | | `filePath`*: string | Compress a markdown file to reduce token usage while preserving headings, URLs, and code blocks. Creates a .original.md backup before writing. |
|
||||
| `memory_consolidate` | yes | `tier`: string | Run the 4-tier memory consolidation pipeline (working -> episodic -> semantic -> procedural). |
|
||||
| `memory_crystallize` | | `actionIds`*: string, `project`: string, `sessionId`: string | Compress completed action chains into compact crystal digests using LLM summarization. Extracts narrative, key outcomes, files affected, and lessons. |
|
||||
| `memory_diagnose` | yes | `categories`: string | Run health checks across all subsystems (actions, leases, sentinels, sketches, signals, sessions, memories, mesh). Identifies stuck, orphaned, and inconsistent state. |
|
||||
| `memory_export` | | none | Export all memory data as JSON. |
|
||||
| `memory_facet_query` | | `matchAll`: string, `matchAny`: string, `targetType`: string | Query targets by facet tags with AND/OR logic. Find all actions tagged priority:urgent AND team:backend. |
|
||||
| `memory_facet_tag` | | `targetId`*: string, `targetType`*: string, `dimension`*: string, `value`*: string | Attach a structured tag (dimension:value) to an action, memory, or observation for multi-dimensional categorization. |
|
||||
| `memory_file_history` | | `files`*: string, `sessionId`: string | Get past observations about specific files. |
|
||||
| `memory_frontier` | | `project`: string, `agentId`: string, `limit`: number | Get all unblocked actions ranked by priority and urgency. Returns the frontier of actionable work with no unsatisfied dependencies. |
|
||||
| `memory_governance_delete` | | `memoryIds`*: string, `reason`: string | Delete specific memories with audit trail. |
|
||||
| `memory_graph_query` | | `startNodeId`: string, `nodeType`: string, `maxDepth`: number, `query`: string | Query the knowledge graph for entities and relationships. |
|
||||
| `memory_heal` | | `categories`: string, `dryRun`: string | Auto-fix all fixable issues found by diagnostics. Unblocks stuck actions, expires stale leases, cleans up orphaned data. |
|
||||
| `memory_insight_list` | | `project`: string, `minConfidence`: number, `limit`: number | List synthesized insights, higher-order observations derived from patterns across memories, lessons, and crystals. |
|
||||
| `memory_lease` | | `actionId`*: string, `agentId`*: string, `operation`*: string, `result`: string, `ttlMs`: number | Acquire, release, or renew an exclusive lease on an action. Prevents multiple agents from working on the same thing. |
|
||||
| `memory_lesson_recall` | | `query`*: string, `project`: string, `minConfidence`: number, `limit`: number | Search lessons by query. Returns lessons sorted by confidence and recency. Use to check what the agent has learned before making decisions. |
|
||||
| `memory_lesson_save` | yes | `content`*: string, `context`: string, `confidence`: number, `project`: string, `tags`: string | Save a lesson learned from this session. Lessons have confidence scores that strengthen when reinforced and decay when not used. Duplicate content auto-strengthens the existing lesson. |
|
||||
| `memory_mesh_sync` | | `peerId`: string, `direction`: string | Sync memories and actions with peer agentmemory instances for multi-agent collaboration. |
|
||||
| `memory_next` | | `project`: string, `agentId`: string | Get the single most important next action to work on. Combines dependency resolution, priority, and recency into a score. |
|
||||
| `memory_obsidian_export` | | `vaultDir`: string, `types`: string | Export memories, lessons, and crystals as Obsidian-compatible Markdown files with YAML frontmatter and wikilinks for graph view. |
|
||||
| `memory_patterns` | | `project`: string | Detect recurring patterns across sessions. |
|
||||
| `memory_profile` | | `project`*: string, `refresh`: string | User/project profile with top concepts and file patterns. |
|
||||
| `memory_recall` | yes | `query`*: string, `limit`: number, `format`: string, `token_budget`: number | Search past session observations for relevant context. Use when you need to recall what happened in previous sessions, find past decisions, or look up how a file was modified before. |
|
||||
| `memory_reflect` | yes | `project`: string, `maxClusters`: number | Traverse the knowledge graph, group related memories by concept clusters, and synthesize higher-order insights via LLM. Returns new and reinforced insights. |
|
||||
| `memory_relations` | | `memoryId`*: string, `maxHops`: number, `minConfidence`: number | Query the memory relationship graph. |
|
||||
| `memory_routine_run` | | `routineId`*: string, `project`: string, `initiatedBy`: string | Instantiate a frozen workflow routine, creating actions for each step with proper dependencies. |
|
||||
| `memory_save` | yes | `content`*: string, `type`: string, `concepts`: string, `files`: string, `project`: string | Explicitly save an important insight, decision, or pattern to long-term memory. |
|
||||
| `memory_sentinel_create` | | `name`*: string, `type`*: string, `config`: string, `linkedActionIds`: string, `expiresInMs`: number | Create an event-driven sentinel that watches for conditions (webhook, timer, threshold, pattern, approval) and auto-unblocks gated actions when triggered. |
|
||||
| `memory_sentinel_trigger` | | `sentinelId`*: string, `result`: string | Externally fire a sentinel, providing an optional result payload. Unblocks any gated actions. |
|
||||
| `memory_sessions` | yes | none | List recent sessions with their status and observation counts. |
|
||||
| `memory_signal_read` | | `agentId`*: string, `unreadOnly`: string, `threadId`: string, `limit`: number | Read messages for an agent. Marks delivered messages as read. |
|
||||
| `memory_signal_send` | | `from`*: string, `to`: string, `content`*: string, `type`: string, `replyTo`: string | Send a message to another agent or broadcast. Supports threading, typed messages, and TTL expiration. |
|
||||
| `memory_sketch_create` | | `title`*: string, `description`: string, `expiresInMs`: number, `project`: string | Create an ephemeral action graph for exploratory work. Auto-expires after TTL. Can be promoted to permanent actions or discarded. |
|
||||
| `memory_sketch_promote` | | `sketchId`*: string, `project`: string | Promote a sketch's ephemeral actions to permanent actions. Makes the exploratory work official. |
|
||||
| `memory_slot_append` | | `label`*: string, `text`*: string | Append text to an existing slot. Fails with 413 if the append would exceed the slot's sizeLimit, agent must compact via memory_slot_replace first. |
|
||||
| `memory_slot_create` | | `label`*: string, `content`: string, `sizeLimit`: number, `description`: string, `pinned`: string, `scope`: string | Create a new slot. Reject if a slot with the same label already exists. |
|
||||
| `memory_slot_delete` | | `label`*: string | Delete a slot. Seeded default slots can be deleted unless marked readOnly. |
|
||||
| `memory_slot_get` | | `label`*: string | Read a single slot by label. |
|
||||
| `memory_slot_list` | | none | List all memory slots (pinned + project + global). Slots are editable, size-limited memory units the agent can read and modify across sessions. |
|
||||
| `memory_slot_replace` | | `label`*: string, `content`*: string | Replace slot content in place. Fails if content exceeds sizeLimit. |
|
||||
| `memory_smart_search` | yes | `query`*: string, `expandIds`: string, `limit`: number | Hybrid semantic+keyword search with progressive disclosure. |
|
||||
| `memory_snapshot_create` | | `message`: string | Create a git-versioned snapshot of current memory state. |
|
||||
| `memory_team_feed` | | `limit`: number | Get recent shared items from all team members. |
|
||||
| `memory_team_share` | | `itemId`*: string, `itemType`*: string | Share a memory or observation with team members. |
|
||||
| `memory_timeline` | | `anchor`*: string, `project`: string, `before`: number, `after`: number | Chronological observations around an anchor point. |
|
||||
| `memory_verify` | | `id`*: string | Verify a memory or observation by tracing its citation chain back to source observations and session context. Returns provenance information including confidence scores. |
|
||||
| `memory_vision_search` | | `queryText`: string, `queryImageRef`: string, `queryImageBase64`: string, `topK`: number, `sessionId`: string | Cross-modal image search via CLIP embeddings. Pass queryText to find screenshots matching a description, or queryImageBase64/queryImageRef to find similar images. Requires AGENTMEMORY_IMAGE_EMBEDDINGS=true. |
|
||||
|
||||
`*` marks required parameters.
|
||||
<!-- AUTOGEN:tools END -->
|
||||
@@ -0,0 +1,39 @@
|
||||
---
|
||||
name: agentmemory-mcp-tools
|
||||
description: Map of every agentmemory MCP tool, what each does, and its parameters. Use when choosing which memory tool to call, when a tool name or argument is unclear, or when answering what agentmemory can do via MCP.
|
||||
user-invocable: false
|
||||
---
|
||||
|
||||
agentmemory exposes its full capability set as MCP tools. This skill is the index: it tells you which tool to reach for and where to find exact parameters.
|
||||
|
||||
## Quick start
|
||||
|
||||
Save then recall:
|
||||
|
||||
1. `memory_save` with `content` (the insight), `concepts` (comma-separated keywords), `files` (comma-separated paths).
|
||||
2. `memory_smart_search` with `query` and `limit` to retrieve it later. This runs hybrid BM25 plus vector plus graph-expanded search.
|
||||
|
||||
## Tool families
|
||||
|
||||
- Capture: `memory_save`, `memory_observe` flows, `memory_compress_file`.
|
||||
- Retrieve: `memory_smart_search`, `memory_recall`, `memory_file_history`, `memory_timeline`, `memory_vision_search`.
|
||||
- Sessions and commits: `memory_sessions`, `memory_commits`, `memory_commit_lookup`.
|
||||
- Knowledge and graph: `memory_lesson_save`, `memory_lesson_recall`, `memory_graph_query`, `memory_relations`, `memory_patterns`, `memory_crystallize`.
|
||||
- Structured slots: `memory_slot_create`, `memory_slot_append`, `memory_slot_get`, `memory_slot_list`, `memory_slot_replace`, `memory_slot_delete`.
|
||||
- Governance and health: `memory_governance_delete`, `memory_audit`, `memory_verify`, `memory_heal`, `memory_diagnose`.
|
||||
|
||||
## Workflow
|
||||
|
||||
1. Pick the narrowest tool for the task. Prefer `memory_smart_search` for open recall, `memory_recall` when you already have a focused query, `memory_sessions` for session listings.
|
||||
2. Look up exact parameter names and which are required in REFERENCE.md before calling.
|
||||
3. Pass only documented fields. REST handlers whitelist fields and drop unknown ones.
|
||||
|
||||
## See also
|
||||
|
||||
- agentmemory-rest-api for the HTTP equivalents.
|
||||
- agentmemory-config for tool-visibility and feature flags.
|
||||
- The user-invocable action skills (remember, recall, recap, handoff, forget) wrap the most common tools.
|
||||
|
||||
## Reference
|
||||
|
||||
Full tool table with parameters and the core-set marking lives in REFERENCE.md, generated from source so it never drifts.
|
||||
@@ -0,0 +1,129 @@
|
||||
# agentmemory REST API reference
|
||||
|
||||
Generated from `src/triggers/api.ts`. Do not edit the block below by hand; run `npm run skills:gen` after changing the registered endpoints.
|
||||
|
||||
<!-- AUTOGEN:rest START - generated by scripts/skills/generate.ts, do not edit by hand -->
|
||||
The REST API is the primary surface. All paths are under `http://localhost:3111` (override with `--port`). When `AGENTMEMORY_SECRET` is set, send `Authorization: Bearer $AGENTMEMORY_SECRET`; localhost is otherwise open.
|
||||
|
||||
117 registered endpoints:
|
||||
|
||||
| Method | Path |
|
||||
| --- | --- |
|
||||
| POST | `/agentmemory/actions` |
|
||||
| POST | `/agentmemory/actions/edges` |
|
||||
| GET | `/agentmemory/actions/get` |
|
||||
| POST | `/agentmemory/actions/update` |
|
||||
| GET | `/agentmemory/audit` |
|
||||
| POST | `/agentmemory/auto-forget` |
|
||||
| GET | `/agentmemory/branch/detect` |
|
||||
| GET | `/agentmemory/branch/sessions` |
|
||||
| GET | `/agentmemory/branch/worktrees` |
|
||||
| POST | `/agentmemory/cascade-update` |
|
||||
| POST | `/agentmemory/checkpoints` |
|
||||
| POST | `/agentmemory/checkpoints/resolve` |
|
||||
| GET | `/agentmemory/claude-bridge/read` |
|
||||
| POST | `/agentmemory/claude-bridge/sync` |
|
||||
| GET | `/agentmemory/commits` |
|
||||
| POST | `/agentmemory/compress-file` |
|
||||
| GET | `/agentmemory/config/flags` |
|
||||
| POST | `/agentmemory/consolidate` |
|
||||
| POST | `/agentmemory/consolidate-pipeline` |
|
||||
| POST | `/agentmemory/context` |
|
||||
| GET | `/agentmemory/crystals` |
|
||||
| POST | `/agentmemory/crystals/auto` |
|
||||
| POST | `/agentmemory/crystals/create` |
|
||||
| POST | `/agentmemory/diagnostics` |
|
||||
| GET | `/agentmemory/diagnostics/followup` |
|
||||
| POST | `/agentmemory/diagnostics/heal` |
|
||||
| POST | `/agentmemory/enrich` |
|
||||
| POST | `/agentmemory/evict` |
|
||||
| POST | `/agentmemory/evolve` |
|
||||
| GET | `/agentmemory/export` |
|
||||
| POST | `/agentmemory/facets` |
|
||||
| POST | `/agentmemory/facets/query` |
|
||||
| POST | `/agentmemory/facets/remove` |
|
||||
| GET | `/agentmemory/facets/stats` |
|
||||
| POST | `/agentmemory/file-context` |
|
||||
| POST | `/agentmemory/flow/compress` |
|
||||
| POST | `/agentmemory/forget` |
|
||||
| GET | `/agentmemory/frontier` |
|
||||
| POST | `/agentmemory/generate-rules` |
|
||||
| POST | `/agentmemory/governance/bulk-delete` |
|
||||
| DELETE | `/agentmemory/governance/memories` |
|
||||
| POST | `/agentmemory/graph/build` |
|
||||
| POST | `/agentmemory/graph/extract` |
|
||||
| POST | `/agentmemory/graph/query` |
|
||||
| POST | `/agentmemory/graph/reset` |
|
||||
| POST | `/agentmemory/graph/snapshot-rebuild` |
|
||||
| GET | `/agentmemory/graph/stats` |
|
||||
| GET | `/agentmemory/health` |
|
||||
| POST | `/agentmemory/import` |
|
||||
| GET | `/agentmemory/insights` |
|
||||
| POST | `/agentmemory/insights/search` |
|
||||
| POST | `/agentmemory/leases/acquire` |
|
||||
| POST | `/agentmemory/leases/release` |
|
||||
| POST | `/agentmemory/leases/renew` |
|
||||
| POST | `/agentmemory/lessons` |
|
||||
| POST | `/agentmemory/lessons/search` |
|
||||
| POST | `/agentmemory/lessons/strengthen` |
|
||||
| GET | `/agentmemory/livez` |
|
||||
| GET | `/agentmemory/memories` |
|
||||
| GET | `/agentmemory/memories/:id` |
|
||||
| GET | `/agentmemory/mesh/export` |
|
||||
| POST | `/agentmemory/mesh/peers` |
|
||||
| POST | `/agentmemory/mesh/receive` |
|
||||
| POST | `/agentmemory/mesh/sync` |
|
||||
| POST | `/agentmemory/migrate` |
|
||||
| GET | `/agentmemory/next` |
|
||||
| GET | `/agentmemory/observations` |
|
||||
| POST | `/agentmemory/observe` |
|
||||
| POST | `/agentmemory/obsidian/export` |
|
||||
| POST | `/agentmemory/patterns` |
|
||||
| GET | `/agentmemory/procedural` |
|
||||
| GET | `/agentmemory/profile` |
|
||||
| POST | `/agentmemory/reflect` |
|
||||
| POST | `/agentmemory/relations` |
|
||||
| POST | `/agentmemory/remember` |
|
||||
| POST | `/agentmemory/replay/import-jsonl` |
|
||||
| GET | `/agentmemory/replay/load` |
|
||||
| GET | `/agentmemory/replay/sessions` |
|
||||
| POST | `/agentmemory/routines` |
|
||||
| POST | `/agentmemory/routines/run` |
|
||||
| GET | `/agentmemory/routines/status` |
|
||||
| POST | `/agentmemory/search` |
|
||||
| GET | `/agentmemory/semantic` |
|
||||
| POST | `/agentmemory/sentinels` |
|
||||
| POST | `/agentmemory/sentinels/cancel` |
|
||||
| POST | `/agentmemory/sentinels/check` |
|
||||
| POST | `/agentmemory/sentinels/trigger` |
|
||||
| GET | `/agentmemory/session/by-commit` |
|
||||
| POST | `/agentmemory/session/commit` |
|
||||
| POST | `/agentmemory/session/end` |
|
||||
| POST | `/agentmemory/session/start` |
|
||||
| GET | `/agentmemory/sessions` |
|
||||
| GET | `/agentmemory/signals` |
|
||||
| POST | `/agentmemory/signals/send` |
|
||||
| POST | `/agentmemory/sketches` |
|
||||
| POST | `/agentmemory/sketches/add` |
|
||||
| POST | `/agentmemory/sketches/discard` |
|
||||
| POST | `/agentmemory/sketches/gc` |
|
||||
| POST | `/agentmemory/sketches/promote` |
|
||||
| GET | `/agentmemory/slot` |
|
||||
| POST | `/agentmemory/slot/append` |
|
||||
| POST | `/agentmemory/slot/reflect` |
|
||||
| POST | `/agentmemory/slot/replace` |
|
||||
| GET | `/agentmemory/slots` |
|
||||
| POST | `/agentmemory/smart-search` |
|
||||
| POST | `/agentmemory/snapshot/create` |
|
||||
| POST | `/agentmemory/snapshot/restore` |
|
||||
| GET | `/agentmemory/snapshots` |
|
||||
| POST | `/agentmemory/summarize` |
|
||||
| GET | `/agentmemory/team/feed` |
|
||||
| GET | `/agentmemory/team/profile` |
|
||||
| POST | `/agentmemory/team/share` |
|
||||
| POST | `/agentmemory/timeline` |
|
||||
| POST | `/agentmemory/verify` |
|
||||
| GET | `/agentmemory/viewer` |
|
||||
| POST | `/agentmemory/vision-embed` |
|
||||
| POST | `/agentmemory/vision-search` |
|
||||
<!-- AUTOGEN:rest END -->
|
||||
@@ -0,0 +1,43 @@
|
||||
---
|
||||
name: agentmemory-rest-api
|
||||
description: The agentmemory HTTP REST API surface, the primary protocol for talking to the memory server. Use when calling agentmemory over HTTP, when MCP is unavailable and you need a fallback, or when integrating a host that does not speak MCP.
|
||||
user-invocable: false
|
||||
---
|
||||
|
||||
REST is agentmemory's primary surface. MCP is a bridge on top of it. Every memory operation has an HTTP endpoint under `http://localhost:3111/agentmemory/*`.
|
||||
|
||||
## Quick start
|
||||
|
||||
```bash
|
||||
# liveness
|
||||
curl -fsS http://localhost:3111/agentmemory/livez
|
||||
|
||||
# save
|
||||
curl -X POST http://localhost:3111/agentmemory/remember \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"content":"chose JWT refresh rotation","concepts":["jwt-refresh-rotation"]}'
|
||||
|
||||
# recall
|
||||
curl -X POST http://localhost:3111/agentmemory/smart-search \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"query":"auth token strategy","limit":5}'
|
||||
```
|
||||
|
||||
## Auth
|
||||
|
||||
By default localhost is open and no auth is needed. When `AGENTMEMORY_SECRET` is set, every request needs `Authorization: Bearer $AGENTMEMORY_SECRET`. See agentmemory-config.
|
||||
|
||||
## Conventions
|
||||
|
||||
- Save returns `201`, reads return `200`, validation errors return `400`.
|
||||
- Handlers whitelist body fields and drop unknown ones, so passing extra keys is safe but ignored.
|
||||
- The port is configurable with `--port` or `--instance`; streams, viewer, and engine derive from it.
|
||||
|
||||
## See also
|
||||
|
||||
- agentmemory-mcp-tools for the MCP equivalents.
|
||||
- agentmemory-config for the port quartet and the secret.
|
||||
|
||||
## Reference
|
||||
|
||||
The full endpoint list with methods lives in REFERENCE.md, generated from `src/triggers/api.ts`.
|
||||
@@ -0,0 +1,71 @@
|
||||
# commit-context worked examples
|
||||
|
||||
## 1. Line range with a linked session
|
||||
|
||||
User: "Why is this retry loop here?" (pointing at lines 40-52 of refresh.ts)
|
||||
|
||||
Find the SHA:
|
||||
|
||||
```bash
|
||||
git blame -L 40,52 src/auth/refresh.ts
|
||||
# 9a1b2c3d (dev 2026-06-07) ... retry on revoked token
|
||||
```
|
||||
|
||||
Look it up:
|
||||
|
||||
```json
|
||||
memory_commit_lookup { "sha": "9a1b2c3d4e5f60718293a4b5c6d7e8f901234567" }
|
||||
```
|
||||
|
||||
Response:
|
||||
|
||||
```json
|
||||
{
|
||||
"commit": { "sha": "9a1b2c3d...", "short": "9a1b2c3", "branch": "main",
|
||||
"author": "dev", "message": "rotate refresh tokens" },
|
||||
"sessions": [ { "id": "7f3a9c21", "project": "app", "observationCount": 14,
|
||||
"summary": "Reworked refresh rotation" } ]
|
||||
}
|
||||
```
|
||||
|
||||
Present:
|
||||
|
||||
> `9a1b2c3` on `main` by dev: "rotate refresh tokens". Linked to session
|
||||
> `7f3a9c2` "Auth refresh rework" (14 obs). The retry loop handles a token
|
||||
> revoked mid-flight, per the session's high-importance observations.
|
||||
|
||||
## 2. Function lookup, commit predates linking
|
||||
|
||||
User: "What was the agent doing when it wrote validateScope?"
|
||||
|
||||
```bash
|
||||
git log -L :validateScope:src/auth/scope.ts -n 1
|
||||
# 1122aabb ...
|
||||
```
|
||||
|
||||
```json
|
||||
memory_commit_lookup { "sha": "1122aabbccddeeff00112233445566778899aabb" }
|
||||
```
|
||||
|
||||
Response:
|
||||
|
||||
```json
|
||||
{ "commit": null }
|
||||
```
|
||||
|
||||
Present:
|
||||
|
||||
> `1122aab` predates agent session linking, so there is no recorded session.
|
||||
> From `git show`: it added `validateScope` to enforce per-token scopes. I can
|
||||
> show the full diff if useful.
|
||||
|
||||
## 3. Bare path
|
||||
|
||||
User: "Give me context on src/middleware/limit.ts."
|
||||
|
||||
```bash
|
||||
git log -n 1 -- src/middleware/limit.ts
|
||||
```
|
||||
|
||||
Take the SHA, run `memory_commit_lookup`, present commit plus linked session in
|
||||
the same shape as example 1.
|
||||
@@ -0,0 +1,64 @@
|
||||
---
|
||||
name: commit-context
|
||||
description: Trace a file, function, or line back to the agent session that produced its current commit. Use when the user asks "why is this code here", "what was the agent doing when this changed", "who wrote this", or wants context on a specific location in the codebase.
|
||||
argument-hint: "[file, function, or line]"
|
||||
user-invocable: true
|
||||
---
|
||||
|
||||
The user wants commit context for: $ARGUMENTS
|
||||
|
||||
## Quick start
|
||||
|
||||
```bash
|
||||
git blame -L 40,52 src/auth/refresh.ts # -> SHA 9a1b2c3d
|
||||
```
|
||||
|
||||
```json
|
||||
memory_commit_lookup { "sha": "9a1b2c3d4e5f60718293a4b5c6d7e8f901234567" }
|
||||
```
|
||||
|
||||
Expected output:
|
||||
|
||||
```text
|
||||
9a1b2c3 on main by dev: "rotate refresh tokens"
|
||||
Linked session 7f3a9c2 "Auth refresh rework", 14 obs.
|
||||
```
|
||||
|
||||
## Why
|
||||
|
||||
Report only what git and the lookup return. When the lookup gives `commit: null`,
|
||||
the commit predates session linking; do not invent intent.
|
||||
|
||||
## Workflow
|
||||
|
||||
1. Find the SHA: `git blame -L <start>,<end> <file>` for a line range;
|
||||
`git log -L :<function>:<file>` for a function; `git log -n 1 -- <file>` for a
|
||||
bare path.
|
||||
2. Look it up: `memory_commit_lookup { "sha": "<full-sha>" }`.
|
||||
3. Present the commit (sha, short sha, branch, author, message), the linked
|
||||
session(s) (id, project, started/ended, observation count, summary), and the
|
||||
importance >= 7 observations via `memory_recall` when available.
|
||||
|
||||
## Anti-patterns
|
||||
|
||||
WRONG: lookup returns `{ "commit": null }`, you narrate "the agent was
|
||||
refactoring auth" from the diff alone.
|
||||
|
||||
RIGHT: "This commit predates session linking, so there is no recorded agent
|
||||
session. From `git show`: it changed token rotation in refresh.ts."
|
||||
|
||||
## Checklist
|
||||
|
||||
- SHA came from git blame/log, not a guess.
|
||||
- `commit: null` reported as "predates linking", no fabricated session.
|
||||
- Session details quote the lookup response verbatim.
|
||||
- No intent claimed beyond what observations state.
|
||||
|
||||
## See also
|
||||
|
||||
- `commit-history`: list many agent-linked commits at once.
|
||||
- `recall`: dig deeper into the linked session's observations.
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
See ../_shared/TROUBLESHOOTING.md if `memory_commit_lookup` is not available.
|
||||
@@ -0,0 +1,71 @@
|
||||
# commit-history worked examples
|
||||
|
||||
## 1. Branch filter
|
||||
|
||||
User: "Show agent commits on main."
|
||||
|
||||
Invocation:
|
||||
|
||||
```json
|
||||
memory_commits { "branch": "main", "limit": 100 }
|
||||
```
|
||||
|
||||
Response:
|
||||
|
||||
```json
|
||||
{
|
||||
"commits": [
|
||||
{ "short": "9a1b2c3", "branch": "main", "authoredAt": "2026-06-07T09:12:00Z",
|
||||
"message": "rotate refresh tokens", "sessionIds": ["7f3a9c21"],
|
||||
"observationCount": 14, "files": 3 },
|
||||
{ "short": "b21d004", "branch": "main", "authoredAt": "2026-06-05T14:40:00Z",
|
||||
"message": "rate limiter audit", "sessionIds": ["b21d004e"],
|
||||
"observationCount": 9, "files": 1 }
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
Present:
|
||||
|
||||
> - `9a1b2c3` main 2026-06-07 "rotate refresh tokens", session `7f3a9c2` (14 obs, 3 files)
|
||||
> - `b21d004` main 2026-06-05 "rate limiter audit", session `b21d004` (9 obs, 1 file)
|
||||
|
||||
## 2. Bare number as limit
|
||||
|
||||
User: "commit-history 5"
|
||||
|
||||
Treat `5` as the limit:
|
||||
|
||||
```json
|
||||
memory_commits { "limit": 5 }
|
||||
```
|
||||
|
||||
Render the five newest linked commits in the same format.
|
||||
|
||||
## 3. Empty result
|
||||
|
||||
User: "Show agent commits on release-2.0."
|
||||
|
||||
```json
|
||||
memory_commits { "branch": "release-2.0", "limit": 100 }
|
||||
```
|
||||
|
||||
Response:
|
||||
|
||||
```json
|
||||
{ "commits": [] }
|
||||
```
|
||||
|
||||
Present:
|
||||
|
||||
> No agent-linked commits on `release-2.0`. Drop the branch filter to see all
|
||||
> linked commits, or try a different branch.
|
||||
|
||||
REST fallback for this same call, with encoding:
|
||||
|
||||
```http
|
||||
GET /agentmemory/commits?branch=release-2.0&limit=100
|
||||
```
|
||||
|
||||
Build it with `URLSearchParams` so a branch like `feat/a&b` becomes
|
||||
`feat%2Fa%26b` rather than breaking the query.
|
||||
@@ -0,0 +1,62 @@
|
||||
---
|
||||
name: commit-history
|
||||
description: List recent git commits linked to agent sessions, optionally filtered by branch or repo. Use when the user asks "show agent commits", "what has the agent shipped", "list linked commits", or wants commits with their session context.
|
||||
argument-hint: "[branch=... repo=... limit=...]"
|
||||
user-invocable: true
|
||||
---
|
||||
|
||||
The user wants a list of agent-linked commits. Filter args: $ARGUMENTS
|
||||
|
||||
## Quick start
|
||||
|
||||
```json
|
||||
memory_commits { "branch": "main", "limit": 20 }
|
||||
```
|
||||
|
||||
Expected output:
|
||||
|
||||
```text
|
||||
9a1b2c3 main 2026-06-07 "rotate refresh tokens" · session 7f3a9c2 (14 obs)
|
||||
b21d004 main 2026-06-05 "rate limiter audit" · session b21d004 (9 obs)
|
||||
```
|
||||
|
||||
## Why
|
||||
|
||||
Render only the commits the tool returned, newest first. An empty result means
|
||||
the filter matched nothing, not that work is missing.
|
||||
|
||||
## Workflow
|
||||
|
||||
1. Parse `$ARGUMENTS` for `branch=<name>`, `repo=<url-or-fragment>`,
|
||||
`limit=<n>`. A bare numeric token is the limit. Defaults: no branch, no repo,
|
||||
limit 100, max 500.
|
||||
2. Call `memory_commits` with the parsed filters.
|
||||
3. Render reverse-chronologically: short sha, branch, authored timestamp, first
|
||||
line of the message, linked session id(s) (first 8) with observation counts,
|
||||
and file count when `files` is present.
|
||||
4. Empty result: tell the user the filter matched nothing and suggest dropping
|
||||
the branch or repo filter.
|
||||
|
||||
## Anti-patterns
|
||||
|
||||
WRONG (REST fallback): concatenate `?branch=` + raw branch name, so a name with
|
||||
`?`, `&`, or `#` corrupts the query string.
|
||||
|
||||
RIGHT: URL-encode every value with `URLSearchParams`/`encodeURIComponent` before
|
||||
appending to `GET /agentmemory/commits`.
|
||||
|
||||
## Checklist
|
||||
|
||||
- Filters parsed; bare number treated as limit; limit capped at 500.
|
||||
- Output is reverse-chronological.
|
||||
- Session ids and observation counts come straight from the response.
|
||||
- REST fallback URL-encodes branch, repo, and limit.
|
||||
|
||||
## See also
|
||||
|
||||
- `commit-context`: drill into one commit's session.
|
||||
- `recall`: search the observations behind a linked session.
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
See ../_shared/TROUBLESHOOTING.md if `memory_commits` is not available.
|
||||
@@ -0,0 +1,75 @@
|
||||
# forget worked examples
|
||||
|
||||
## 1. Delete a leaked secret
|
||||
|
||||
User: "Forget that note where I pasted the API key."
|
||||
|
||||
Search:
|
||||
|
||||
```json
|
||||
memory_smart_search { "query": "api key", "limit": 20 }
|
||||
```
|
||||
|
||||
Response:
|
||||
|
||||
```json
|
||||
{
|
||||
"results": [
|
||||
{ "id": "abc12345", "sessionId": "7f3a9c21", "title": "Pasted staging API key",
|
||||
"narrative": "STAGING_KEY=sk-live-..." }
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
Present and gate:
|
||||
|
||||
> Found 1 match:
|
||||
> - `abc12345` (session `7f3a9c2`) "Pasted staging API key"
|
||||
>
|
||||
> Delete this memory? (yes/no)
|
||||
|
||||
After the user says yes:
|
||||
|
||||
```json
|
||||
memory_governance_delete { "memoryIds": ["abc12345"], "reason": "user privacy request" }
|
||||
```
|
||||
|
||||
Response:
|
||||
|
||||
```json
|
||||
{ "deleted": 1 }
|
||||
```
|
||||
|
||||
Present:
|
||||
|
||||
> Deleted 1 memory (`abc12345`).
|
||||
|
||||
## 2. Drop a whole session's observations
|
||||
|
||||
User: "Delete everything from the throwaway spike session."
|
||||
|
||||
Search, identify the session, then collect every memory id in it:
|
||||
|
||||
```json
|
||||
memory_smart_search { "query": "spike prototype throwaway", "limit": 20 }
|
||||
```
|
||||
|
||||
Response has 4 results all with `sessionId: c98f1100`. Show all four, get a yes,
|
||||
then pass every id:
|
||||
|
||||
```json
|
||||
memory_governance_delete {
|
||||
"memoryIds": ["m1", "m2", "m3", "m4"],
|
||||
"reason": "drop throwaway spike session"
|
||||
}
|
||||
```
|
||||
|
||||
Never send `{ "sessionId": "c98f1100" }`; the MCP deletes by memory id only.
|
||||
|
||||
## 3. User declines
|
||||
|
||||
User: "Actually, on second thought, keep them."
|
||||
|
||||
Do not call delete. Confirm:
|
||||
|
||||
> Understood, nothing deleted. The 4 memories from session `c98f110` are intact.
|
||||
@@ -0,0 +1,66 @@
|
||||
---
|
||||
name: forget
|
||||
description: Delete specific observations from agentmemory after showing them and getting explicit confirmation. Use when the user says "forget this", "delete memory", "remove that note", or wants to scrub specific data for privacy.
|
||||
argument-hint: "[what to forget - session ID, file path, or search term]"
|
||||
user-invocable: true
|
||||
---
|
||||
|
||||
The user wants to remove data from agentmemory: $ARGUMENTS
|
||||
|
||||
## Quick start
|
||||
|
||||
```json
|
||||
memory_smart_search { "query": "old api key in config", "limit": 20 }
|
||||
```
|
||||
|
||||
Show the matches, get a yes, then:
|
||||
|
||||
```json
|
||||
memory_governance_delete { "memoryIds": ["abc12345", "def67890"], "reason": "user privacy request" }
|
||||
```
|
||||
|
||||
Expected output:
|
||||
|
||||
```text
|
||||
Found 2 matching memories. Confirmed. Deleted 2 memories.
|
||||
```
|
||||
|
||||
## Why
|
||||
|
||||
This is destructive and irreversible. Show exactly what will be deleted and get
|
||||
an explicit yes before calling delete. Delete by memory ID, never a bare session.
|
||||
|
||||
## Workflow
|
||||
|
||||
1. Search with `memory_smart_search`, the user's text as `query`, `limit: 20`.
|
||||
2. Show what matched: session ids, memory ids, titles. Ask for explicit
|
||||
confirmation. Do not proceed on silence or a vague "sure, whatever".
|
||||
3. On confirmation, call `memory_governance_delete` with `memoryIds` (array or
|
||||
comma-separated string) and optional `reason` (default `plugin skill request`).
|
||||
4. To drop a whole session, collect every memory id in that session from the
|
||||
search results and pass them all. The MCP does not accept a bare `sessionId`.
|
||||
5. Report the deletion count back.
|
||||
|
||||
## Anti-patterns
|
||||
|
||||
WRONG: search returns matches, you immediately call `memory_governance_delete`
|
||||
without showing them or waiting for a yes.
|
||||
|
||||
RIGHT: list the matches, ask "Delete these 2? (yes/no)", and only delete after
|
||||
an explicit yes.
|
||||
|
||||
## Checklist
|
||||
|
||||
- Matches were shown to the user before any delete.
|
||||
- An explicit yes was received, not assumed.
|
||||
- `memoryIds` holds real ids from the search, never a bare `sessionId`.
|
||||
- Final message states the actual count deleted.
|
||||
|
||||
## See also
|
||||
|
||||
- `remember`: the write side; forget is its undo.
|
||||
- `recall`: find the exact memory id before deleting.
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
See ../_shared/TROUBLESHOOTING.md if `memory_smart_search` or `memory_governance_delete` is not available.
|
||||
@@ -0,0 +1,56 @@
|
||||
# handoff worked examples
|
||||
|
||||
## 1. Resume with an open question
|
||||
|
||||
User: "Where were we?"
|
||||
|
||||
Project cwd: `/Users/dev/app`. Invocation:
|
||||
|
||||
```json
|
||||
memory_sessions { "limit": 20 }
|
||||
```
|
||||
|
||||
Response:
|
||||
|
||||
```json
|
||||
{
|
||||
"sessions": [
|
||||
{ "id": "7f3a9c21", "cwd": "/Users/dev/app", "title": "Auth refresh rework",
|
||||
"status": "completed", "startedAt": "2026-06-07T09:00:00Z",
|
||||
"summary": "Reworked refresh rotation. Open: should logout revoke all device tokens?",
|
||||
"concepts": ["jwt-refresh-rotation", "logout"] }
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
Pull supporting context:
|
||||
|
||||
```json
|
||||
memory_recall { "query": "jwt-refresh-rotation logout", "limit": 10 }
|
||||
```
|
||||
|
||||
Present:
|
||||
|
||||
> Resuming `7f3a9c2` "Auth refresh rework".
|
||||
> **Open question:** should logout revoke all device tokens or just the current one?
|
||||
> Touched `auth/refresh.ts`, `auth/logout.ts`. Refresh rotation is done.
|
||||
> **Next step:** decide the revoke scope, then finish `auth/logout.ts`.
|
||||
|
||||
## 2. Sibling-repo guard
|
||||
|
||||
Project cwd: `/Users/dev/repo-a`. Sessions include one with `cwd:
|
||||
/Users/dev/repo-a-staging`.
|
||||
|
||||
A raw prefix would match `repo-a-staging`. The boundary check rejects it because
|
||||
`/Users/dev/repo-a-staging` does not equal `/Users/dev/repo-a` and does not start
|
||||
with `/Users/dev/repo-a/`. Pick the real `repo-a` session instead, or fall back
|
||||
to the most recent session overall if none matches.
|
||||
|
||||
## 3. Empty session
|
||||
|
||||
User: "Resume."
|
||||
|
||||
If the matched session has zero observations:
|
||||
|
||||
> The most recent session `c98f110` for this project has no recorded
|
||||
> observations. Nothing to hand off. Want to start fresh from the current state?
|
||||
@@ -0,0 +1,68 @@
|
||||
---
|
||||
name: handoff
|
||||
description: Resume the most recent agent session for the current working directory, leading with any unanswered question. Use when the user says "where were we", "resume", "handoff", "pick up where I left off", or starts a session with no fresh context.
|
||||
argument-hint: "[optional cwd override]"
|
||||
user-invocable: true
|
||||
---
|
||||
|
||||
The user wants to resume work. Optional cwd override: $ARGUMENTS
|
||||
|
||||
## Quick start
|
||||
|
||||
```json
|
||||
memory_sessions { "limit": 20 }
|
||||
```
|
||||
|
||||
Pick the most recent session whose `cwd` matches this project, then:
|
||||
`memory_recall { "query": "<session top concepts>", "limit": 10 }`.
|
||||
|
||||
Expected output:
|
||||
|
||||
```text
|
||||
Resuming 7f3a9c2 "Auth refresh rework".
|
||||
Open question: should logout revoke all device tokens or just the current one?
|
||||
Next step: decide revoke scope, then update auth/logout.ts.
|
||||
```
|
||||
|
||||
## Why
|
||||
|
||||
Match the session by directory boundary, not raw prefix, so a sibling repo never
|
||||
gets mistaken for this one. Never invent observations for an empty session.
|
||||
|
||||
## Workflow
|
||||
|
||||
1. Resolve the project path: if `$ARGUMENTS` is given, normalize it to absolute
|
||||
(`path.resolve(process.cwd(), $ARGUMENTS)`); else use the cwd.
|
||||
2. Call `memory_sessions`. Pick the most recent session whose normalized `cwd`
|
||||
matches by directory boundary: equality, OR `cwd.startsWith(projectPath + sep)`,
|
||||
OR `projectPath.startsWith(cwd + sep)`. Prefer `completed` over `abandoned`.
|
||||
No match: fall back to the single most recent session overall.
|
||||
3. If the session ended on an unanswered user-facing question, surface it FIRST.
|
||||
Look in `summary` or recent `conversation` observations whose `narrative`
|
||||
ends in `?`.
|
||||
4. Summarize: title/summary, key files, key decisions or errors, using
|
||||
`memory_recall` on the top concepts, limit 10.
|
||||
5. End with one concrete "next step?" pointer.
|
||||
|
||||
## Anti-patterns
|
||||
|
||||
WRONG: `session.cwd.startsWith(projectPath)` matches `/repo-a-staging` when the
|
||||
project is `/repo-a`, resuming the wrong repo's session.
|
||||
|
||||
RIGHT: `session.cwd === projectPath || session.cwd.startsWith(projectPath + sep)`,
|
||||
a directory-boundary check that cannot cross sibling repos.
|
||||
|
||||
## Checklist
|
||||
|
||||
- cwd override resolved to an absolute, normalized path.
|
||||
- Match used a directory-boundary check, not a raw prefix.
|
||||
- Unanswered question (if any) leads the response.
|
||||
- Empty session is reported plainly, with an offer to start fresh.
|
||||
|
||||
## See also
|
||||
|
||||
- `recap`, `session-history`, `recall`: same session data, broader views.
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
See ../_shared/TROUBLESHOOTING.md if `memory_sessions` or `memory_recall` is not available.
|
||||
@@ -0,0 +1,74 @@
|
||||
# recall worked examples
|
||||
|
||||
## 1. Hit on a past decision
|
||||
|
||||
User: "Did we ever decide how to cache sessions?"
|
||||
|
||||
Invocation:
|
||||
|
||||
```json
|
||||
memory_smart_search { "query": "session caching decision", "limit": 10 }
|
||||
```
|
||||
|
||||
Response:
|
||||
|
||||
```json
|
||||
{
|
||||
"results": [
|
||||
{ "sessionId": "7f3a9c21", "type": "decision", "title": "Drop Redis for iii state store",
|
||||
"narrative": "We decided to drop Redis and use the iii-engine state store for session caching.",
|
||||
"importance": 8 }
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
Present:
|
||||
|
||||
> Yes. In session `7f3a9c21` you decided to drop Redis and use the iii-engine
|
||||
> state store for session caching (importance 8).
|
||||
|
||||
## 2. Multiple results across sessions
|
||||
|
||||
User: "Recall anything about the rate limiter."
|
||||
|
||||
Invocation:
|
||||
|
||||
```json
|
||||
memory_smart_search { "query": "rate limiter", "limit": 10 }
|
||||
```
|
||||
|
||||
Response:
|
||||
|
||||
```json
|
||||
{
|
||||
"results": [
|
||||
{ "sessionId": "b21d004e", "type": "code", "title": "limit.ts counts per-IP",
|
||||
"narrative": "Rate limiter counts per-IP, not per-user.", "importance": 6 },
|
||||
{ "sessionId": "c98f1100", "type": "conversation", "title": "Discussed sliding window",
|
||||
"narrative": "Considered a sliding-window limiter, deferred.", "importance": 4 }
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
Present them grouped by session, leading with the per-IP code note.
|
||||
|
||||
## 3. No results
|
||||
|
||||
User: "Recall the GraphQL schema migration."
|
||||
|
||||
Invocation:
|
||||
|
||||
```json
|
||||
memory_smart_search { "query": "graphql schema migration", "limit": 10 }
|
||||
```
|
||||
|
||||
Response:
|
||||
|
||||
```json
|
||||
{ "results": [] }
|
||||
```
|
||||
|
||||
Present:
|
||||
|
||||
> No memories matched that. Try `schema change`, `graphql`, or `migration` as
|
||||
> narrower terms, or `recap this week` to scan recent sessions.
|
||||
@@ -0,0 +1,60 @@
|
||||
---
|
||||
name: recall
|
||||
description: Search agentmemory for past observations, sessions, and learnings about a topic using hybrid BM25 plus vector plus graph search. Use when the user says "recall", "what did we do about", "did we ever", "have we seen", or needs context from past sessions.
|
||||
argument-hint: "[search query]"
|
||||
user-invocable: true
|
||||
---
|
||||
|
||||
The user wants to recall past context about: $ARGUMENTS
|
||||
|
||||
## Quick start
|
||||
|
||||
```json
|
||||
memory_smart_search { "query": "jwt refresh token rotation", "limit": 10 }
|
||||
```
|
||||
|
||||
Expected output:
|
||||
|
||||
```text
|
||||
2 results across 2 sessions.
|
||||
[importance 8] decision · "Rotate refresh tokens on every use" (session 7f3a9c21)
|
||||
[importance 5] code · "limit.ts counts per-IP" (session b21d004e)
|
||||
```
|
||||
|
||||
## Why
|
||||
|
||||
Only surface what the tool returned. Never fabricate an observation, a session
|
||||
id, or an importance score. If nothing comes back, say so.
|
||||
|
||||
## Workflow
|
||||
|
||||
1. Call `memory_smart_search` with the user's text as `query` and `limit: 10`.
|
||||
Pass `project` when the user scopes to a specific repo.
|
||||
2. Group results by session.
|
||||
3. For each observation show its type, title, and narrative.
|
||||
4. Lead with the high-signal observations (importance >= 7).
|
||||
5. If zero results, suggest 2-3 alternative search terms and stop. Do not guess.
|
||||
|
||||
## Anti-patterns
|
||||
|
||||
WRONG: results are empty, so you write "We probably discussed token expiry last
|
||||
week" from assumption.
|
||||
|
||||
RIGHT: "No memories matched that query. Try `refresh token`, `session expiry`,
|
||||
or `auth rotation`."
|
||||
|
||||
## Checklist
|
||||
|
||||
- Every observation shown came from the tool response.
|
||||
- Results grouped by session, high-importance first.
|
||||
- Empty results trigger alternative-term suggestions, not invention.
|
||||
- No session id or score was paraphrased or rounded.
|
||||
|
||||
## See also
|
||||
|
||||
- `remember`: the write side; recall retrieves what it stores.
|
||||
- `recap`, `handoff`, `session-history`: session-scoped views of the same data.
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
See ../_shared/TROUBLESHOOTING.md if `memory_smart_search` is not available.
|
||||
@@ -0,0 +1,60 @@
|
||||
# recap worked examples
|
||||
|
||||
## 1. This week
|
||||
|
||||
User: "Recap this week."
|
||||
|
||||
Window: last 7 days. Invocation:
|
||||
|
||||
```json
|
||||
memory_sessions { "limit": 30 }
|
||||
```
|
||||
|
||||
Response (after filtering to cwd and the 7-day window):
|
||||
|
||||
```json
|
||||
{
|
||||
"sessions": [
|
||||
{ "id": "7f3a9c21", "cwd": "/Users/dev/app", "title": "Auth refresh rework",
|
||||
"startedAt": "2026-06-07T09:00:00Z", "observationCount": 14, "status": "completed",
|
||||
"concepts": ["jwt-refresh-rotation", "auth-flow"] },
|
||||
{ "id": "b21d004e", "cwd": "/Users/dev/app", "title": "Rate limiter audit",
|
||||
"startedAt": "2026-06-05T14:00:00Z", "observationCount": 9, "status": "completed",
|
||||
"concepts": ["rate-limiter", "per-ip-bug"] }
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
Per session, pull highlights:
|
||||
|
||||
```json
|
||||
memory_recall { "query": "jwt-refresh-rotation auth-flow", "limit": 3 }
|
||||
```
|
||||
|
||||
Present:
|
||||
|
||||
> **2026-06-07**
|
||||
> - `7f3a9c2` Auth refresh rework, 14 obs, completed
|
||||
> - [8] Rotate refresh tokens on every use
|
||||
>
|
||||
> **2026-06-05**
|
||||
> - `b21d004e` Rate limiter audit, 9 obs, completed
|
||||
> - [7] limit.ts counts per-IP, not per-user
|
||||
>
|
||||
> 2 sessions across 2 days, 23 observations.
|
||||
|
||||
## 2. Bare number
|
||||
|
||||
User: "recap 3"
|
||||
|
||||
Treat as `last 3`. Call `memory_sessions { "limit": 3 }`, group by date, same format.
|
||||
|
||||
## 3. Empty window
|
||||
|
||||
User: "Recap today."
|
||||
|
||||
If `memory_sessions` returns no session whose `startedAt` is today and whose
|
||||
`cwd` matches:
|
||||
|
||||
> No sessions today for this project. The most recent was yesterday, `7f3a9c2`
|
||||
> Auth refresh rework. Want a recap of that instead?
|
||||
@@ -0,0 +1,63 @@
|
||||
---
|
||||
name: recap
|
||||
description: Summarize the last N agent sessions for the current project, grouped by date, with highlight observations per session. Use when the user asks "recap", "what have we been doing", "today", "this week", or wants a rollup of recent work.
|
||||
argument-hint: "[last N | today | this week]"
|
||||
user-invocable: true
|
||||
---
|
||||
|
||||
The user wants a recap. Time window args: $ARGUMENTS
|
||||
|
||||
## Quick start
|
||||
|
||||
```json
|
||||
memory_sessions { "limit": 30 }
|
||||
```
|
||||
|
||||
Then per surviving session: `memory_recall { "query": "<top concepts>", "limit": 3 }`.
|
||||
|
||||
Expected output:
|
||||
|
||||
```text
|
||||
2026-06-07
|
||||
7f3a9c2 · "Auth refresh rework" · 14 obs · completed
|
||||
- [8] Rotate refresh tokens on every use
|
||||
3 sessions across 2 days, 41 observations.
|
||||
```
|
||||
|
||||
## Why
|
||||
|
||||
Only summarize sessions and observations the tools returned. An empty window is
|
||||
a real answer, not a prompt to invent activity.
|
||||
|
||||
## Workflow
|
||||
|
||||
1. Parse `$ARGUMENTS`: `today` = current local date; `this week` = last 7 days;
|
||||
`last <n>` or bare numeric = most recent N; empty = `last 10`.
|
||||
2. Call `memory_sessions`, filter to the current project (match `cwd` against the
|
||||
working directory), apply the window, sort by `startedAt` descending.
|
||||
3. Group survivors by local calendar date (YYYY-MM-DD).
|
||||
4. Per session list id (first 8), title or first prompt, observation count,
|
||||
status. Indent 2-3 highlights (importance >= 7) from `memory_recall`.
|
||||
5. End with "N sessions across M days, K observations."
|
||||
|
||||
## Anti-patterns
|
||||
|
||||
WRONG: window is empty, so you summarize "a productive week of auth work" from
|
||||
memory of the conversation.
|
||||
|
||||
RIGHT: "No sessions in the last 7 days for this project."
|
||||
|
||||
## Checklist
|
||||
|
||||
- Window parsed correctly from the argument.
|
||||
- Sessions filtered to the current project's cwd.
|
||||
- Highlights come from `memory_recall`, not paraphrase.
|
||||
- Totals line reflects the actual counts shown.
|
||||
|
||||
## See also
|
||||
|
||||
- `handoff`, `session-history`, `recall`: same session data, different lens.
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
See ../_shared/TROUBLESHOOTING.md if `memory_sessions` or `memory_recall` is not available.
|
||||
@@ -0,0 +1,67 @@
|
||||
# remember worked examples
|
||||
|
||||
## 1. Saving a decision
|
||||
|
||||
User: "Remember that we decided to drop Redis and use the iii-engine state store for session caching."
|
||||
|
||||
Invocation:
|
||||
|
||||
```json
|
||||
memory_save {
|
||||
"content": "We decided to drop Redis and use the iii-engine state store for session caching to remove a moving part.",
|
||||
"concepts": "session-caching, iii-state-store, dropped-redis",
|
||||
"files": ""
|
||||
}
|
||||
```
|
||||
|
||||
Response:
|
||||
|
||||
```json
|
||||
{ "id": "7f3a9c21", "concepts": ["session-caching", "iii-state-store", "dropped-redis"], "saved": true }
|
||||
```
|
||||
|
||||
Present:
|
||||
|
||||
> Saved. Tagged it `session-caching`, `iii-state-store`, `dropped-redis`, so a
|
||||
> later recall on caching or Redis will surface this decision.
|
||||
|
||||
## 2. Saving a code-specific gotcha
|
||||
|
||||
User: "Save this: the rate limiter in middleware/limit.ts counts per-IP, not per-user, so logged-in users on shared IPs collide."
|
||||
|
||||
Invocation:
|
||||
|
||||
```json
|
||||
memory_save {
|
||||
"content": "The rate limiter in middleware/limit.ts counts per-IP, not per-user, so logged-in users on shared IPs collide.",
|
||||
"concepts": "rate-limiter, per-ip-bug, shared-ip-collision",
|
||||
"files": "src/middleware/limit.ts"
|
||||
}
|
||||
```
|
||||
|
||||
Response:
|
||||
|
||||
```json
|
||||
{ "id": "b21d004e", "concepts": ["rate-limiter", "per-ip-bug", "shared-ip-collision"], "saved": true }
|
||||
```
|
||||
|
||||
Present:
|
||||
|
||||
> Saved memory `b21d004e` referencing `src/middleware/limit.ts`. Concepts:
|
||||
> `rate-limiter`, `per-ip-bug`, `shared-ip-collision`.
|
||||
|
||||
## 3. Vague request, no files
|
||||
|
||||
User: "Remember this for later."
|
||||
|
||||
Ask once for the substance, then save:
|
||||
|
||||
```json
|
||||
memory_save {
|
||||
"content": "Staging deploys must run the migration job before the app rollout, never after.",
|
||||
"concepts": "staging-deploy, migration-ordering, rollout-sequence",
|
||||
"files": ""
|
||||
}
|
||||
```
|
||||
|
||||
Present the confirmation with the concepts echoed back.
|
||||
@@ -0,0 +1,61 @@
|
||||
---
|
||||
name: remember
|
||||
description: Save an insight, decision, or learning to agentmemory's long-term storage with searchable concept tags. Use when the user says "remember this", "save this", "note that", "don't forget", or wants to preserve knowledge for future sessions.
|
||||
argument-hint: "[what to remember]"
|
||||
user-invocable: true
|
||||
---
|
||||
|
||||
The user wants to save this to long-term memory: $ARGUMENTS
|
||||
|
||||
## Quick start
|
||||
|
||||
```json
|
||||
memory_save {
|
||||
"content": "We rotate JWT refresh tokens on every use; the old token is revoked server-side in auth/refresh.ts.",
|
||||
"concepts": "jwt-refresh-rotation, token-revocation, auth-flow",
|
||||
"files": "src/auth/refresh.ts"
|
||||
}
|
||||
```
|
||||
|
||||
Expected output:
|
||||
|
||||
```text
|
||||
Saved memory abc12345 with 3 concepts: jwt-refresh-rotation, token-revocation, auth-flow.
|
||||
```
|
||||
|
||||
## Why
|
||||
|
||||
A memory is only as useful as the terms that retrieve it. Tag with specific
|
||||
concepts so a future `recall` finds it, and preserve the user's own phrasing.
|
||||
|
||||
## Workflow
|
||||
|
||||
1. Pull the core insight, decision, or fact out of `$ARGUMENTS`.
|
||||
2. Extract 2-5 lowercased concept phrases. Prefer specific over generic
|
||||
(`jwt-refresh-rotation` beats `auth`).
|
||||
3. Extract referenced file paths (absolute or repo-relative). Empty if none.
|
||||
4. Call `memory_save` with `content`, `concepts` (comma-separated string), and
|
||||
`files` (comma-separated string).
|
||||
5. Confirm the save and echo the concepts so the user knows the retrieval terms.
|
||||
|
||||
## Anti-patterns
|
||||
|
||||
WRONG: `concepts: "stuff, code, notes"` (generic tags nothing can find later).
|
||||
|
||||
RIGHT: `concepts: "jwt-refresh-rotation, token-revocation"` (specific, retrievable).
|
||||
|
||||
## Checklist
|
||||
|
||||
- Content preserves the user's phrasing, not a paraphrase.
|
||||
- Concepts are specific, lowercased, 2-5 items.
|
||||
- File paths are real references, not guesses.
|
||||
- Confirmation echoes the exact concepts tagged.
|
||||
|
||||
## See also
|
||||
|
||||
- `recall`: retrieve what you save here (the pair to this skill).
|
||||
- `forget`: remove a memory you saved by mistake.
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
See ../_shared/TROUBLESHOOTING.md if `memory_save` is not available.
|
||||
@@ -0,0 +1,59 @@
|
||||
# session-history worked examples
|
||||
|
||||
## 1. Standard timeline
|
||||
|
||||
User: "Show me the session history."
|
||||
|
||||
Invocation:
|
||||
|
||||
```json
|
||||
memory_sessions { "limit": 20 }
|
||||
```
|
||||
|
||||
Response:
|
||||
|
||||
```json
|
||||
{
|
||||
"sessions": [
|
||||
{ "id": "7f3a9c21", "project": "app", "startedAt": "2026-06-07T09:00:00Z",
|
||||
"status": "completed", "observationCount": 14,
|
||||
"summary": "Reworked refresh rotation",
|
||||
"highlights": [ { "type": "decision", "title": "Rotate refresh tokens on every use" } ] },
|
||||
{ "id": "b21d004e", "project": "app", "startedAt": "2026-06-05T14:00:00Z",
|
||||
"status": "completed", "observationCount": 9,
|
||||
"highlights": [ { "type": "code", "title": "limit.ts counts per-IP" } ] }
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
Present:
|
||||
|
||||
> - `7f3a9c2` app, 2026-06-07 09:00, completed, 14 obs
|
||||
> - decision: Rotate refresh tokens on every use (summary: Reworked refresh rotation)
|
||||
> - `b21d004` app, 2026-06-05 14:00, completed, 9 obs
|
||||
> - code: limit.ts counts per-IP
|
||||
|
||||
## 2. Session with no observations
|
||||
|
||||
If a returned session has `observationCount: 0`, list it but say so:
|
||||
|
||||
> - `c98f110` app, 2026-06-04 11:00, abandoned, 0 obs (no recorded work)
|
||||
|
||||
## 3. Empty history
|
||||
|
||||
User: "What did we do last time?"
|
||||
|
||||
```json
|
||||
memory_sessions { "limit": 20 }
|
||||
```
|
||||
|
||||
Response:
|
||||
|
||||
```json
|
||||
{ "sessions": [] }
|
||||
```
|
||||
|
||||
Present:
|
||||
|
||||
> No recorded sessions yet for this project. Once you work with memory capture
|
||||
> on, they will show here. Use `remember` to save a note now.
|
||||
@@ -0,0 +1,61 @@
|
||||
---
|
||||
name: session-history
|
||||
description: Show what happened in recent past sessions on this project as a clean timeline. Use when the user asks "what did we do last time", "session history", "past sessions", or wants an overview of previous work.
|
||||
user-invocable: true
|
||||
---
|
||||
|
||||
The user wants an overview of recent sessions on this project.
|
||||
|
||||
## Quick start
|
||||
|
||||
```json
|
||||
memory_sessions { "limit": 20 }
|
||||
```
|
||||
|
||||
Expected output:
|
||||
|
||||
```text
|
||||
7f3a9c2 · app · 2026-06-07 09:00 · completed · 14 obs
|
||||
- decision: Rotate refresh tokens on every use
|
||||
b21d004 · app · 2026-06-05 14:00 · completed · 9 obs
|
||||
- code: limit.ts counts per-IP
|
||||
```
|
||||
|
||||
## Why
|
||||
|
||||
Only show sessions and observations the tool returned. An empty history is a
|
||||
real answer, never a cue to invent past work.
|
||||
|
||||
## Workflow
|
||||
|
||||
1. Call `memory_sessions` with `limit: 20` for a meaningful window.
|
||||
2. Present in reverse chronological order: session id (first 8), project, start
|
||||
time, status.
|
||||
3. For sessions with observations, show the key highlights (type plus title).
|
||||
4. Note the total observation count per session.
|
||||
5. When a session summary exists, surface its title and the key decisions.
|
||||
|
||||
## Anti-patterns
|
||||
|
||||
WRONG: the tool returns two sessions, you describe "several sessions of steady
|
||||
progress" and add ones you remember from the conversation.
|
||||
|
||||
RIGHT: show exactly the two sessions returned, each with its real id, status, and
|
||||
observation count.
|
||||
|
||||
## Checklist
|
||||
|
||||
- Every session shown came from the tool response.
|
||||
- Order is reverse-chronological.
|
||||
- Per-session observation counts match the response.
|
||||
- No session or highlight was invented or merged.
|
||||
|
||||
## See also
|
||||
|
||||
- `recap`: same data grouped by date with highlights.
|
||||
- `handoff`: jump straight into the most recent session.
|
||||
- `recall`: search across all sessions by topic.
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
See ../_shared/TROUBLESHOOTING.md if `memory_sessions` is not available.
|
||||
@@ -0,0 +1,40 @@
|
||||
---
|
||||
name: write-agentmemory-skill
|
||||
description: The house format and rules for writing or updating an agentmemory skill. Use when adding a new skill, restructuring an existing one, or reviewing a skill contribution for consistency.
|
||||
user-invocable: false
|
||||
---
|
||||
|
||||
agentmemory skills follow one tiered format so they stay skimmable, accurate, and current. Match it exactly.
|
||||
|
||||
## Directory layout
|
||||
|
||||
```text
|
||||
plugin/skills/<name>/
|
||||
SKILL.md (required, under 100 lines)
|
||||
REFERENCE.md (optional, dense facts; auto-generate data tables)
|
||||
EXAMPLES.md (optional, worked transcripts)
|
||||
```
|
||||
|
||||
## SKILL.md rules
|
||||
|
||||
- Frontmatter: `name`, `description`, optional `argument-hint`, and `user-invocable`. Set `user-invocable: true` only for skills the user runs as a slash command; reference and knowledge skills are `false`.
|
||||
- Description is two sentences and the only thing the agent sees when deciding to load the skill. Sentence one states the capability. Sentence two starts "Use when" and lists concrete triggers. Keep it distinct from sibling skills, under 1024 chars, third person.
|
||||
- Body order: Quick start (one concrete example), Why (the governing principle), Workflow (numbered steps with decision gates), Anti-patterns (a WRONG vs RIGHT callout for the top mistake), Checklist, See also (cross-link siblings), Reference or Troubleshooting pointer.
|
||||
- Stay under 100 lines. Move dense facts to REFERENCE.md and examples to EXAMPLES.md.
|
||||
- Cross-references link one level deep only. Shared recovery steps live in `../_shared/TROUBLESHOOTING.md`, never inlined.
|
||||
|
||||
## Keep it current
|
||||
|
||||
Facts that exist in source (tool names and parameters, REST endpoints, env vars, connect adapters, hook events) are generated, never hand-typed. Edit the source, then run `npm run skills:gen`. CI runs `npm run skills:check` and fails on drift, so generated tables cannot fall behind the code.
|
||||
|
||||
## Style
|
||||
|
||||
No external or competitor product names. No emojis. No em-dashes. No filler. State the thing and stop.
|
||||
|
||||
## Checklist
|
||||
|
||||
- Description has a "Use when" sentence with real triggers.
|
||||
- SKILL.md is under 100 lines.
|
||||
- No time-sensitive claims and no duplicated troubleshooting block.
|
||||
- Concrete example present; generated facts come from the generator.
|
||||
- Cross-links resolve and go one level deep.
|
||||
Reference in New Issue
Block a user