ziiagentmemory 0.1.0

package/plugin/skills/agentmemory-config/REFERENCE.md

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

package/plugin/skills/agentmemory-config/SKILL.md

@@ -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/`.

package/plugin/skills/agentmemory-hooks/REFERENCE.md

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

package/plugin/skills/agentmemory-hooks/SKILL.md

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

package/plugin/skills/agentmemory-mcp-tools/REFERENCE.md

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

package/plugin/skills/agentmemory-mcp-tools/SKILL.md

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

package/plugin/skills/agentmemory-rest-api/REFERENCE.md

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

package/plugin/skills/agentmemory-rest-api/SKILL.md

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

package/plugin/skills/commit-context/EXAMPLES.md

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

package/plugin/skills/commit-context/SKILL.md

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

package/plugin/skills/commit-history/EXAMPLES.md

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