@agentled/cli 0.7.7 → 0.7.8

package/skills/agentled/references/credits-apps-and-errors.md

@@ -0,0 +1,40 @@
+# Top Apps, Credit-Efficient Testing & Validation Errors
+
+> Loaded on demand from the Agentled skill. `list_apps` / `get_app_actions`
+> (MCP) and `agentled apps` (CLI) are the **authoritative** sources for app
+> schemas — this file is a fast reference plus the testing/error playbook.
+
+## Top Apps Quick Reference
+
+| App | Action | Credits | Key Inputs |
+|-----|--------|---------|------------|
+| `agentled` | `get-linkedin-company-from-url` | 5 | `profileUrls` |
+| `agentled` | `get-linkedin-profile-from-url` | 2 | `profileUrls` |
+| `agentled` | `find-email-person-domain` | 3 | `firstName`, `lastName`, `domain` |
+| `hunter` | `find-email-person-domain` | 3 | `firstName`, `lastName`, `domain` |
+| `web-scraping` | `scrape` | 0 | `url` |
+| `http-request` | `request` | 0 | `url`, `method`, `headers`, `body` |
+| `notion` | `get-page-markdown` | 1 | `pageUrl` |
+| `browser-use` | `run-task` | 15 | `task`, `startUrl` |
+| `agentled` | `call-workflow` | varies | `workflowId`, `input` |
+
+Use `list_apps` and `get_app_actions` for full schemas of all available apps. Use `list_models` for supported AI model IDs.
+
+## Credit-Efficient Testing
+
+Each execution costs real credits. Follow these rules:
+
+1. **One execution at a time** — don't start new ones unnecessarily
+2. **Retry, don't restart** — use `retry_execution` to continue from a failed step instead of starting over
+3. **Test in isolation** — use `test_ai_action`, `test_app_action`, or `test_code_action` to verify steps before wiring them into a workflow
+4. **Reuse prior output** — when testing downstream steps, use output data from a prior successful execution as mock input
+
+## Common Validation Errors
+
+| Error | Fix |
+|-------|-----|
+| `"references non-existent next step"` | Ensure some step has `next: { stepId: "X" }` pointing to the missing step |
+| `"missing prompt template"` | Add `pipelineStepPrompt.template` to AI steps |
+| `"Unknown action"` | Verify `actionId` format via `get_app_actions` |
+| `"is unreachable"` | Connect every step via `next.stepId` from the trigger chain |
+| `"unsupported model"` | Use a valid internal model ID (e.g., `claude-4-6-sonnet`, not `claude-sonnet-4-6`). Run `list_models` for all valid IDs. |

package/skills/agentled/references/editing-workflows.md

@@ -0,0 +1,109 @@
+# Editing Existing Workflows — Merge Model
+
+> Loaded on demand from the Agentled skill. Read this before editing any
+> dictionary-shaped step field (`stepInputData.fieldUpdates`,
+> `pipelineStepPrompt.responseStructure`, `knowledgeSync.fieldMapping`) or any
+> `context.*` / `metadata.*` workflow-level field.
+
+For live workflows, prefer per-step tools over bulk updates:
+
+- `update_step(workflowId, stepId, updates)` — change one step (prompt, inputs, next, etc.)
+- `add_step(workflowId, step, insertAfter?)` — insert a new step
+- `remove_step(workflowId, stepId)` — delete a step and re-wire neighbors
+- After edits: `validate_workflow` → `publish_workflow` (or `promote_draft` for live workflows)
+
+## Merge model
+
+`update_step` accepts three explicit operations on the same call. At least one must be non-empty.
+
+- **`updates`** — partial step patch, **deep-merged ONE LEVEL deep**. Top-level scalars are replaced; nested objects (e.g. `pipelineStepPrompt`, `stepInputData`) get their direct keys merged with the stored value's keys. Keys nested two levels deep are overwritten as a unit, not merged.
+- **`replace: string[]`** — dot-paths whose values from `updates` are assigned **wholesale**, skipping the deep-merge. Use this for **dictionary-shaped fields where keys are user data** (not config) — patching one inner key with `updates` alone silently wipes the others.
+- **`unset: string[]`** — dot-paths to delete. Each path must currently exist on the step (validated against the original — you cannot unset something you just created in the same call).
+
+**Read-before-write for dictionary fields.** Before editing `stepInputData.fieldUpdates`, `pipelineStepPrompt.responseStructure`, `knowledgeSync.fieldMapping`, or any field where keys are user data: call `get_step({ workflowId, stepId })`, modify locally, send the full new object back via `replace[]`. Cheap (~1KB) and avoids the "patched one key, silently wiped the others" trap.
+
+**Diff in the response.** Every `update_step` returns `diff: { addedPaths, changedPaths, removedPaths }` and `warnings[]`. If the merge silently removed ≥6 fields without an explicit `unset`, a warning fires. Read it.
+
+## What to use where
+
+| Path / field | API | How to edit | Notes |
+|---|---|---|---|
+| `name`, `goal`, `description`, `pipelineStepPrompt.template`, `creditCost` | `update_step` | `updates` | Plain scalar; safe to send alone. |
+| `next`, `loopConfig`, `entryConditions` (full block) | `update_step` | `updates` | Direct nested config; sending the new value wholesale is fine — these are config, not user-data dictionaries. |
+| `tools`, `integrations` | `update_step` | `updates` | Arrays are replaced wholesale by design. To append, fetch with `get_step`, splice locally, send the full new array. |
+| `stepInputData.fieldUpdates` (kg.update-rows / kg.upsert-rows) | `update_step` | `get_step` → `updates` (full dict) + `replace: ["stepInputData.fieldUpdates"]` | Keys are user data; default one-level merge replaces this dict and can drop sibling mappings. |
+| `pipelineStepPrompt.responseStructure` | `update_step` | `get_step` → `updates` (full struct) + `replace: ["pipelineStepPrompt.responseStructure"]` | Output-shape dictionary; treat as user data. |
+| `knowledgeSync.fieldMapping` | `update_step` | `get_step` → `updates` (full mapping) + `replace: ["knowledgeSync.fieldMapping"]` | Source→target dict; same trap as `fieldUpdates`. |
+| `renderer.config` (when preserving sibling keys matters) | `update_step` | `updates` (full `renderer.config`) + `replace: ["renderer.config"]` | ⚠ `replace: ["renderer.config.layout"]` does NOT protect `renderer.config`'s siblings — the one-level deep-merge runs first on `updates.renderer`. Replace at the parent level. |
+| `entryConditions.criteria` (when preserving the rest of `entryConditions`) | `update_step` | `updates: { entryConditions: {...full block...} }` | Send the full `entryConditions` block; one-level merge already does the right thing for direct children. |
+| Removing a step input or stale field | `update_step` | `unset: ["stepInputData.oldKey"]` | Cleanest way to remove. Path must exist on the original. |
+| `context.inputPages`, `context.outputPages`, `context.executionInputConfig` | `update_workflow_context` | Three explicit verbs (`updates` / `replace` / `unset`) on workflow-relative paths, OR legacy `{ contextKey, value }` for wholesale per-key replacement | **Workflow-level, not step-level.** `update_step` cannot reach `context.*`. See workflow-level merge model below. |
+| `metadata` | `update_workflow_context` | Same three verbs on `metadata.*` paths; one-level shallow-merge under `updates.metadata` | Workflow-level. Metadata edits bypass the draft snapshot (write direct to Pipeline row even on live workflows). |
+
+**Type changes.** `step.type` is technically mutable but stale type-specific fields (`pipelineStepPrompt`, `app`, `tools`, `orchestratorConfig`) persist unless you `unset` them. For clean conversions, prefer `remove_step` + `add_step`. If editing in place, list the incompatible fields under `unset`.
+
+**Live workflows.** Edits are routed to a draft snapshot. Response includes `editingDraft: true`. Inspect via `get_draft`, ship via `promote_draft`, throw away via `discard_draft`. For high-stakes edits, `create_snapshot` first as a manual checkpoint.
+
+**Draft staleness.** When a draft already exists, every `update_step` / `get_step` response carries a `draft` summary:
+
+```jsonc
+"draft": {
+  "exists": true,
+  "draftCreatedAt": "...",
+  "liveUpdatedAt": "...",
+  "stale": true,                  // live advanced past draft.createdAt
+  "modifiedStepIds": ["step-x"],  // step IDs whose JSON differs between draft and live
+  "modifiedFields": ["steps"]     // top-level config keys that differ
+}
+```
+
+If `draft.stale === true`, the live workflow has been touched (template upgrade, UI edit, deploy) since the draft was forked. Promoting the draft will land its values for fields you didn't touch in this session — those values may be older than current live. Recovery: `discard_draft` and re-apply your edit, or call `get_draft` to inspect what's pending. The `update_step` response also pushes a staleness string into `warnings[]`.
+
+**Never** send a full `steps[]` array via `update_workflow`. Use `update_step`, `add_step`, `remove_step` instead.
+
+## Workflow-level merge model (`update_workflow_context`)
+
+`update_workflow_context` is the workflow-level analog of `update_step` — same three verbs, but on **workflow-relative paths** (`context.executionInputConfig.fields`, `metadata.tags`, …). Step-relative paths like `pipelineStepPrompt.template` are rejected here, and conversely `update_step` rejects `context.*` / `metadata.*` paths. The boundary is hard.
+
+Allowed path prefixes for `replace[]` / `unset[]`:
+
+- `context.inputPages`
+- `context.outputPages`
+- `context.executionInputConfig`
+- `metadata`
+
+Out-of-scope paths (e.g. `steps`, `name`) → `PATH_OUT_OF_SCOPE` (400). Other typed errors mirror `update_step`: `EMPTY_PAYLOAD`, `INVALID_PATH`, `REPLACE_VALUE_MISSING`, `UNSET_PATH_NOT_FOUND`. The response includes `diff: { addedPaths, changedPaths, removedPaths }` and `warnings[]` (≥6 silent removals fires the warning).
+
+Recipes:
+
+```jsonc
+// Flip executionInputConfig.internal — same merge-order trap as update_step.
+// Fetch (get_workflow), merge locally, replace at the parent level:
+{
+  "updates": { "context": { "executionInputConfig": {...full merged executionInputConfig with internal: true...} } },
+  "replace": ["context.executionInputConfig"]
+}
+
+// Replace inputPages wholesale:
+{
+  "updates": { "context": { "inputPages": [...new pages...] } },
+  "replace": ["context.inputPages"]
+}
+
+// Add a metadata tag (one-level shallow-merge — siblings preserved):
+{ "updates": { "metadata": { "tags": ["beta"] } } }
+
+// Delete an obsolete metadata key:
+{ "unset": ["metadata.legacyFlag"] }
+```
+
+Live workflows: context edits route to the draft snapshot. Metadata is NOT part of the snapshot config — it always writes direct to the Pipeline row, immediately and on the live workflow.
+
+⚠ **Mixed metadata + context in one call** is the sharp edge: metadata is applied immediately while context becomes pending in the draft. `discard_draft` reverts the pending context changes but **does NOT revert metadata** — metadata never went to the draft. If you need a single atomic checkpoint covering both, `create_snapshot` first or split the call into two.
+
+A legacy `{ contextKey, value }` body shape is still accepted as a **compatibility shape** for one-shot wholesale replacement of a single root context key. It can't edit metadata, doesn't return `diff` / `warnings`, and is not the recommended path for new code — prefer the three-verb shape above.
+
+## Post-authoring
+
+1. Test: `start_workflow` with sample input
+2. Check results: `get_execution` to see step outputs

package/skills/agentled/references/email-workflows.md

@@ -0,0 +1,122 @@
+# Email Workflows — Triggers, Dedup & the Composed Email Step
+
+> Loaded on demand from the Agentled skill. Read this for any workflow that
+> reads or sends email. Pairs with the `08-composed-email-approval` pattern
+> (`agentled examples 08-composed-email-approval`).
+
+## Trigger choice: polling vs event
+
+**Default to Schedule trigger + label-based dedup** for all email intake workflows (deal flow, triage, review, digest). Only propose an App Event trigger when the user explicitly needs sub-minute latency.
+
+| User asks for | Trigger |
+|---------------|---------|
+| "process inbound emails", "triage daily", "review pitches" | **Schedule** (polling) |
+| "as soon as", "real-time", "within X seconds/minutes" | **App event** |
+
+## Canonical email polling pattern
+
+```
+schedule trigger → GMAIL_FETCH_EMAILS (-label:processed newer_than:1d) → loop: [process] → GMAIL_ADD_LABEL (mark processed) → milestone
+```
+
+Step order:
+1. **`GMAIL_CREATE_LABEL`** — create/get the `processed` label (idempotent, returns label ID)
+2. **`GMAIL_FETCH_EMAILS`** — query `-label:processed newer_than:1d` (or wider window as needed)
+3. **Loop** — process each email (AI analysis, KG storage, enrichment, etc.)
+4. **`GMAIL_ADD_LABEL`** — apply `{{steps.ensure-label.id}}` to mark email done (dedup gate)
+
+## Label ID rule (prevents `400: Invalid label`)
+
+Gmail requires **label IDs** (e.g., `Label_3456789012345`), not display names (e.g., `"processed"` or `"agentled"`).
+
+**Always resolve via `GMAIL_CREATE_LABEL`** and reference its returned `id`:
+```json
+{ "stepInputData": { "label_id": "{{steps.ensure-label.id}}" } }
+```
+Never pass a string label name directly to `GMAIL_ADD_LABEL`.
+
+See `docs/workflows/triggers.md` for the full decision framework, query examples, and common mistakes.
+
+---
+
+## Email Step Pattern (AI Draft → Approve → Send)
+
+Email steps use a single `aiAction` step (never separate "draft" + "gmail send" appAction steps). The AI drafts the email, a human approves, then the platform sends it.
+
+### 1. Outreach Profile Input Page
+
+When a workflow sends emails, add an outreach profile input page to `context.inputPages` so the user can configure sender identity:
+
+```json
+{
+  "title": "Outreach Profile",
+  "pathname": "outreach-profile",
+  "configuration": {
+    "contextKey": "outreachProfile",
+    "shortDescriptionFields": ["name", "fromEmail"],
+    "fields": [
+      { "name": "name", "label": "Sender Name", "type": "text", "required": true },
+      { "name": "fromEmailLabel", "label": "From Name", "type": "text", "required": true },
+      { "name": "fromEmail", "label": "From Email", "type": "connected_emails_selector_multiple", "required": true },
+      { "name": "replyToEmail", "label": "Reply-To Email (optional)", "type": "text" }
+    ]
+  }
+}
+```
+
+### 2. Composed Email Step
+
+```json
+{
+  "id": "send_email",
+  "type": "aiAction",
+  "name": "Send Email",
+  "pipelineStepPrompt": {
+    "type": "email",
+    "template": "Draft a personalized email...\n{{steps.previous_step.data}}\nReturn JSON ONLY per schema.",
+    "responseStructure": {
+      "email": {
+        "from": "{{context.outreachProfile.fromEmail}}",
+        "to": "recipient@example.com",
+        "subject": "Email subject line",
+        "body": "Email body (email-safe HTML)",
+        "bodyType": "html"
+      }
+    },
+    "responseType": "json"
+  },
+  "renderer": {
+    "type": "Email",
+    "config": { "fromContextKey": "outreachProfile" }
+  },
+  "onApproval": {
+    "action": "schedule-email",
+    "executedText": "Email sent by {{name}} at {{date}}",
+    "scheduledText": "Email scheduled to be sent for {{date}} by {{name}}",
+    "failedText": "Email failed to send."
+  },
+  "integrations": [{
+    "type": "oneOf",
+    "label": "Email",
+    "connectorType": "email",
+    "options": [
+      { "name": "Gmail", "url": "https://gmail.com", "isUserAccountConnectionRequired": true },
+      { "name": "Outlook", "url": "https://outlook.com", "isUserAccountConnectionRequired": true }
+    ],
+    "selectionHint": "preferConnected"
+  }],
+  "creditCost": 10,
+  "next": { "conditions": { "approvalRequired": true } }
+}
+```
+
+### Key Requirements
+
+- **Always** include `outreachProfile` input page when using email
+- `pipelineStepPrompt.type: "email"` — tells the system this is an email step
+- `renderer.config.fromContextKey: "outreachProfile"` — links renderer to sender profile
+- `onApproval.action: "schedule-email"` — triggers the actual send; without it, approval does nothing
+- `next.conditions.approvalRequired: true` — blocks the pipeline until human approval
+- Email body must be email-safe HTML (`<p>`, `<br>`, `<a>`, `<strong>` — no CSS, no scripts)
+- **Never** use separate "draft" + "gmail send" appAction steps for outreach
+- Set an output page `displayConfig.executionNameTemplate` that names the entity and the outreach state. For single-entity outreach, use `{{entityName}} - Email Drafted` before approval and `{{entityName}} - Email Sent` or `{{entityName}} - Contacted` after the post-send status step, e.g. `Joe Dan - VC Firm Name - Email Drafted`; add `{{today}}` only when a short date helps. For batch runs, summarize counts instead, e.g. `26 May - 4 sourced - 3 contacted`.

package/skills/agentled/references/entity-pipeline.md

@@ -0,0 +1,106 @@
+# Entity Pipeline Pattern (Source → KG → Process)
+
+> Loaded on demand from the Agentled skill. Read this whenever the user wants
+> to find leads, source companies, collect contacts, or discover entities to
+> act on later. Pairs with `13-entity-pipeline-lifecycle`
+> (`agentled examples 13-entity-pipeline-lifecycle`).
+
+When a user asks about **finding leads, sourcing companies, collecting contacts, or discovering any entities they want to act on later**, propose this two-workflow architecture instead of a single monolithic workflow.
+
+## Why
+
+Sourcing and processing have different cadences and costs. Decoupling them lets you:
+- Source from many places (LinkedIn, web scrape, Crunchbase, email, webhooks) into one canonical list
+- Process (enrich, score, outreach) only new entities, on a schedule, without re-processing already-handled ones
+- Retry or re-run either phase independently without touching the other
+
+## Workflow 1 — Sourcing (runs on trigger or schedule)
+
+Finds entities from one or more sources and writes them into a shared KG list with `status: "new"`. Uses `kg.upsert-rows` with a caller-supplied `userKey` on each row so re-runs dedup (O(1), no table scan).
+
+```json
+// Step: write sourced entities to KG
+{
+  "id": "save-to-kg",
+  "type": "appAction",
+  "name": "Save to KG",
+  "app": { "id": "kg", "actionId": "kg.upsert-rows", "source": "native" },
+  "stepInputData": {
+    "listKey": "sourced-startups",
+    // rows must be [{ userKey, rowData }, ...] — userKey is the dedup contract.
+    // Use any stable caller-defined id: URL, domain, LinkedIn URL, etc.
+    "rows": "{{steps.extract.items}}",
+    "mergeStrategy": "merge",   // preserve fields added downstream (scores, notes)
+    "status": "new"
+  },
+  "next": { "stepId": "done" }
+}
+```
+
+**Key rules:**
+- Always include a `status` on sourcing writes (default `"new"`) so the processing workflow can filter on it
+- Give every row a stable `userKey` (URL, domain, LinkedIn URL — any caller-defined id that won't change). Same `userKey` in the same list = same DynamoDB row, forever
+- Use `mergeStrategy: "merge"` so downstream-added fields (scores, status updates) survive re-upserts from the source
+- Multiple sourcing workflows can write to the same `listKey` — they converge into one canonical list
+- Use `kg.add-rows` only for one-shot, never-re-run writes where duplicates are acceptable
+
+## Workflow 2 — Processing (runs on schedule, e.g. weekly)
+
+Reads only `status: "new"` rows, processes them (enrich, score, outreach, etc.), then updates status to `"processed"` (or `"scored"`, `"outreached"`, etc.) so they're never picked up again.
+
+```json
+// Step 1: read new entities
+{
+  "id": "read-new",
+  "type": "appAction",
+  "name": "Read New Entities",
+  "app": { "id": "kg", "actionId": "kg.read-list", "source": "native" },
+  "stepInputData": {
+    "listKey": "sourced-startups",
+    "filters": "{\"status\": \"new\"}",
+    "limit": "50"
+  },
+  "next": { "stepId": "process-loop" }
+}
+
+// Step 2: loop → enrich / score / outreach each entity
+// ... your enrichment and scoring steps here, using {{currentItem.url}} etc. ...
+
+// Step N: mark as processed
+{
+  "id": "mark-processed",
+  "type": "appAction",
+  "name": "Mark Processed",
+  "app": { "id": "kg", "actionId": "kg.update-rows", "source": "native" },
+  "stepInputData": {
+    "listKey": "sourced-startups",
+    "rowIds": "{{steps.process-loop.processedIds}}",
+    "fieldUpdates": "{\"status\": \"processed\"}"
+  },
+  "next": { "stepId": "done" }
+}
+```
+
+## Status values (suggested convention)
+
+| Value | Meaning |
+|-------|---------|
+| `new` | Sourced, not yet processed |
+| `scored` | Enriched and scored, not yet outreached |
+| `outreached` | Outreach sent |
+| `rejected` | Filtered out during scoring |
+| `processed` | Generic "done" for non-outreach pipelines |
+
+Use whatever values make sense for the use case — the pattern is the same.
+
+## When to propose this pattern
+
+Suggest it whenever the user says any of:
+- "find leads / companies / contacts"
+- "source startups / investors / candidates"
+- "collect entities from multiple sources"
+- "build a list I can act on later"
+- "score / enrich / outreach to a list"
+- "run this once a week on new items"
+
+The default answer is **two workflows**: one that sources into KG, one that processes from KG. A single do-everything workflow is only appropriate when the user has a fixed one-shot input and no recurring need.

package/skills/agentled/references/outreach-and-scale.md

@@ -0,0 +1,43 @@
+# Outreach Scale, Segmentation & Discovery Questions
+
+> Loaded on demand from the Agentled skill. Read this for any outbound, sales,
+> investor, founder, or lead-generation workflow — classify the motion before
+> designing.
+
+## What to ask — and what not to ask
+
+After orienting on the workspace, ask **at most three to five** targeted questions. Focus only on what the workspace inspection cannot answer.
+
+**Good questions:**
+- "What is the primary goal: source more paying leads, run each event smoothly, or report pipeline health?"
+- "Where is the bottleneck today: finding leads, getting replies, converting to paid, or operational follow-up?"
+- "What is the system of record for payments/bookings right now: Stripe webhook, a booking page, a manual form, or a KG list?"
+- "Which actions must be approval-gated: customer emails, status changes, or all customer-facing messages?"
+- "What success metric should this optimize: conversions per week, leads contacted, confirmations, fill rate, or operator time saved?"
+
+**Do not ask:**
+- Step type names, app action names, schema syntax, or implementation details — discover these from the workspace and CLI.
+- Every possible future integration question before the first useful slice is designed.
+- Anything answerable by running `agentled workspace inspect`.
+
+## Outreach scale and segmentation
+
+For outbound, sales, investor, founder, or lead-generation workflows, classify the motion before designing the workflow. See `docs/OUTREACH_SCALE_GUIDANCE.md`.
+
+**Core diagnostic:**
+- PCPL = prospects contacted / positive replies over the last 30 days. PCPL at or below 250 is a scalable winner; above 250 means diagnose deliverability, then copy, then offer-audience match.
+- Daily volume = last 30 days sent / 22 working days.
+- TAM = total reachable prospects in the CRM, KG list, enrichment tool, or target account universe.
+- Reply ops = whether positive replies are handled quickly and followed up persistently.
+
+**Tier guidance:**
+- Tier 1 (~100/day, a few thousand prospects): enrich every account, route by strongest signal, use high-touch multi-channel outreach. This is the default for most small Agentled Ops / AngelHive-style motions.
+- Tier 2 (~1,000/day, 50K-100K prospects): split into top 200-500 home-run accounts with Tier 1 treatment plus segmented automation for the long tail.
+- Tier 3 (~10K/day, hundreds of thousands): test angle x offer x segment, generate script variations, keep tests running in parallel, and track PCPL per combination.
+- Tier 4 (50K-100K/day, millions): require provider segmentation, live monitoring, sender reserve capacity, hourly testing cadence, and reply-handling SLAs before increasing volume.
+
+**Workflow implications:**
+- Small TAM problems are usually segmentation and signal-enrichment problems, not copy-only problems.
+- Store `outreachAngle`, `offer`, `segment`, `campaignVariant`, `channelUsed`, `sender`, `contactedAt`, `replyStatus`, `meetingStatus`, and `positiveReplyAt` when the KG schema allows it.
+- Configure business metrics for prospects contacted, positive replies, PCPL, meetings/bookings/paid confirmations, bounce/failed-send count, and segment/angle performance. These are `analyticsConfig` business metrics, not ROI assumptions.
+- Literal PCPL should use `type: "ratio"` with `ratioMode: "raw"`. Use the default percentage ratio behavior for rates such as `positive_replies / prospects_contacted`.

package/skills/agentled/references/persistent-memory.md

@@ -0,0 +1,106 @@
+# Persistent Memory
+
+> Loaded on demand from the Agentled skill. Workflows can store and recall
+> memories that persist across executions. Memory is opt-in — existing
+> workflows are unaffected.
+
+Two mechanisms: MCP tools (manage memory externally) and pipeline-step configuration (memory inside workflows).
+
+## MCP Tools (for managing memory externally)
+
+| Tool | Purpose | Key Params |
+|------|---------|------------|
+| `recall_memory` | Get a specific memory by key | `key`, `scope?`, `workflowId?` |
+| `search_memories` | Search by natural language query | `query?`, `category?`, `scope?`, `workflowId?`, `limit?` |
+| `store_memory` | Save a persistent memory | `key`, `value`, `category?`, `scope?`, `workflowId?`, `confidence?`, `merge?` |
+| `list_memories` | List all memories in a scope | `scope?`, `workflowId?`, `category?`, `limit?` |
+| `delete_memory` | Delete a memory by key | `key`, `scope?`, `workflowId?` |
+
+**Scopes**: `workspace` (shared across all workflows) or `workflow` (scoped to one workflow, default).
+
+**Categories**: `fact` (known truth), `insight` (pattern/learning), `preference` (user preference), `outcome` (result to track).
+
+**Merge strategies** (for `store_memory`): `overwrite` (default), `append`, `max`, `min`, `increment`.
+
+**Confidence**: 0-100. Memories with confidence >= 70 are automatically synced to the Knowledge Graph.
+
+## Pipeline Step Configuration (for memory inside workflows)
+
+### Auto-extraction (pipeline-level)
+
+Enable on the pipeline to automatically extract memories after each execution completes:
+
+```json
+{
+  "persistentMemoryConfig": {
+    "autoExtract": true,
+    "scopes": ["pipeline"],
+    "categories": ["fact", "insight", "outcome"],
+    "maxPerExtraction": 10,
+    "extractionModelTier": "mini"
+  }
+}
+```
+
+### Explicit per-step writes
+
+Configure specific steps to write memories from their output:
+
+```json
+{
+  "id": "score-company",
+  "type": "aiAction",
+  "persistentMemory": {
+    "writes": [
+      {
+        "key": "score_{{input.company_name}}",
+        "valuePath": "total_score",
+        "category": "outcome",
+        "scope": "pipeline",
+        "confidence": 85
+      }
+    ]
+  }
+}
+```
+
+The `valuePath` extracts from the step's output using dot notation. The `key` supports template variables.
+
+### Builtin tool for AI steps (`workspace_memory`)
+
+AI steps with type `aiActionWithTools` can use the `workspace_memory` builtin tool to read/write memory during execution:
+
+```json
+{
+  "id": "analyze",
+  "type": "aiActionWithTools",
+  "name": "Analyze with Memory",
+  "tools": [{ "builtinType": "workspace_memory" }],
+  "pipelineStepPrompt": {
+    "template": "Recall what we know about this company, then analyze...",
+    "responseStructure": { "analysis": "string" }
+  },
+  "creditCost": 10,
+  "next": { "stepId": "done" }
+}
+```
+
+The AI agent can then call `recall`, `search`, or `store` actions within the tool during execution. This is the same pattern used by KG tools (`kg_search`, `kg_traverse`, etc.).
+
+## Memory Patterns
+
+**1. Learning workflow** — accumulates knowledge over repeated runs:
+```
+trigger → enrich → AI analyze (with workspace_memory tool) → milestone
+```
+The AI step recalls prior scores, compares trends, and stores updated insights.
+
+**2. Explicit score tracking** — saves structured data for cross-run comparison:
+```
+trigger → score company → [persistentMemory.writes: score_{{company}}] → milestone
+```
+
+**3. Workspace-wide preferences** — store ICP criteria, outreach templates, or scoring weights shared across workflows:
+```
+store_memory(key: "target_icp", value: { industry: "SaaS", minEmployees: 50 }, scope: "workspace", category: "preference")
+```