# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Agoragentic Agent OS and Marketplace Router Agent OS Governed Memory API
  version: 1.0.0
extends: openapi/agoragentic-com-agent-os-governed-memory-api-openapi.yml
actions:
- target: $.info
  update:
    x-apievangelist-phrasing:
      method: generated
      generated: '2026-09-26'
      generator: build-phrasing.py
      label: Generated by API Evangelist
      operations: 18
- target: $.paths['/agent-os/deployments/{deployment_id}/memory'].get
  update:
    x-apievangelist-phrasing:
      intent: List a deployment's governed memory items
      effect: read
      questions:
      - What memories has my deployed agent stored so far?
      - Can I list only memory of a certain type or under a path prefix?
      instructions:
      - text: List the governed memory items for deployment {deployment_id}.
        slots:
          deployment_id: path.deployment_id
      - text: Show {status} memory items of type {type} on branch {branch} for deployment {deployment_id}.
        slots:
          status: query.status
          type: query.type
          branch: query.branch
          deployment_id: path.deployment_id
      - text: List memory under path prefix {path_prefix} in deployment {deployment_id}.
        slots:
          path_prefix: query.path_prefix
          deployment_id: path.deployment_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/agent-os/deployments/{deployment_id}/memory'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a versioned memory item
      effect: write
      questions:
      - How do I save a new fact into my agent's memory with an initial commit?
      - Can I write a memory item directly at a semantic path on a branch?
      instructions:
      - text: Create a {type} memory at {path} in deployment {deployment_id} with content {content}.
        slots:
          type: requestBody.type
          path: requestBody.path
          deployment_id: path.deployment_id
          content: requestBody.content
      - text: Commit a new memory item summarized as {summary} on branch {branch} of deployment {deployment_id}.
        slots:
          summary: requestBody.summary
          branch: requestBody.branch
          deployment_id: path.deployment_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/agent-os/deployments/{deployment_id}/memory/candidates'].post
  update:
    x-apievangelist-phrasing:
      intent: Propose a memory candidate for review
      effect: write
      questions:
      - Can my agent propose a memory that a human approves before it is used?
      - Which kinds of memory stay approval-gated instead of auto-written?
      instructions:
      - text: Propose a memory candidate for deployment {deployment_id} with summary {summary}.
        slots:
          deployment_id: path.deployment_id
          summary: requestBody.summary
      - text: Submit a {sensitivity} {type} memory candidate for review in deployment {deployment_id}, citing {source_refs}.
        slots:
          sensitivity: requestBody.sensitivity
          type: requestBody.type
          deployment_id: path.deployment_id
          source_refs: requestBody.source_refs
      method: generated
      generated: '2026-09-26'
- target: $.paths['/agent-os/deployments/{deployment_id}/memory/branches'].get
  update:
    x-apievangelist-phrasing:
      intent: List a deployment's memory branches
      effect: read
      questions:
      - Which memory branches exist for my deployment and what are their head commits?
      - Can I see only active memory branches?
      instructions:
      - text: List memory branches for deployment {deployment_id}.
        slots:
          deployment_id: path.deployment_id
      - text: Show up to {limit} memory branches with status {status} in deployment {deployment_id}.
        slots:
          limit: query.limit
          status: query.status
          deployment_id: path.deployment_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/agent-os/deployments/{deployment_id}/memory/branches'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a memory branch for isolation
      effect: write
      questions:
      - Can I branch my agent's memory for an experiment without touching the main line?
      - How do I make a separate memory branch for a codebase worktree?
      instructions:
      - text: Create memory branch {branch} in deployment {deployment_id}.
        slots:
          branch: requestBody.branch
          deployment_id: path.deployment_id
      - text: Branch {branch} off {parent_branch} with scope {scope} for deployment {deployment_id}.
        slots:
          branch: requestBody.branch
          parent_branch: requestBody.parent_branch
          scope: requestBody.scope
          deployment_id: path.deployment_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/agent-os/deployments/{deployment_id}/memory/commits'].get
  update:
    x-apievangelist-phrasing:
      intent: List memory commit history
      effect: read
      questions:
      - What is the commit history of my agent's memory?
      - Can I see every commit that touched one memory item?
      instructions:
      - text: List memory commits for deployment {deployment_id}.
        slots:
          deployment_id: path.deployment_id
      - text: Show the commits for memory item {memory_id} on branch {branch} in deployment {deployment_id}.
        slots:
          memory_id: query.memory_id
          branch: query.branch
          deployment_id: path.deployment_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/agent-os/deployments/{deployment_id}/memory/commits/{commit_id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Read one memory commit and its snapshot
      effect: read
      questions:
      - What exactly changed in a specific memory commit?
      - Can I read the stored snapshot attached to a single commit?
      instructions:
      - text: Get memory commit {commit_id} in deployment {deployment_id}.
        slots:
          commit_id: path.commit_id
          deployment_id: path.deployment_id
      - text: Show the snapshot stored with commit {commit_id} for deployment {deployment_id}.
        slots:
          commit_id: path.commit_id
          deployment_id: path.deployment_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/agent-os/deployments/{deployment_id}/memory/checkout'].post
  update:
    x-apievangelist-phrasing:
      intent: Check out a read-only memory snapshot
      effect: read
      questions:
      - Can I view my agent's memory as it was at an earlier commit without changing the branch?
      - Does checking out an old memory commit modify current memory?
      instructions:
      - text: Check out memory as of commit {commit_id} for deployment {deployment_id}.
        slots:
          commit_id: requestBody.commit_id
          deployment_id: path.deployment_id
      - text: Give me a read-only view of deployment {deployment_id} memory at commit {commit_id}.
        slots:
          deployment_id: path.deployment_id
          commit_id: requestBody.commit_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/agent-os/deployments/{deployment_id}/memory/revert'].post
  update:
    x-apievangelist-phrasing:
      intent: Revert a memory commit
      effect: write
      questions:
      - How do I undo a bad memory change my agent committed?
      - Does reverting a memory commit erase the audit history?
      instructions:
      - text: Revert memory commit {commit_id} in deployment {deployment_id}.
        slots:
          commit_id: requestBody.commit_id
          deployment_id: path.deployment_id
      - text: Roll back commit {commit_id} on deployment {deployment_id} because {reason}.
        slots:
          commit_id: requestBody.commit_id
          deployment_id: path.deployment_id
          reason: requestBody.reason
      method: generated
      generated: '2026-09-26'
- target: $.paths['/agent-os/deployments/{deployment_id}/memory/blame'].get
  update:
    x-apievangelist-phrasing:
      intent: Find who last changed a memory path
      effect: read
      questions:
      - Which commit and actor last wrote a particular memory path?
      - Where did the information at this memory path come from?
      instructions:
      - text: Blame memory path {path} in deployment {deployment_id}.
        slots:
          path: query.path
          deployment_id: path.deployment_id
      - text: Show the source refs and author of {path} on branch {branch} for deployment {deployment_id}.
        slots:
          path: query.path
          branch: query.branch
          deployment_id: path.deployment_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/agent-os/deployments/{deployment_id}/memory/diff'].get
  update:
    x-apievangelist-phrasing:
      intent: Diff two memory commits
      effect: read
      questions:
      - What is different between two versions of my agent's memory?
      - Can I compare a commit against a chosen base commit?
      instructions:
      - text: Diff memory commit {target_commit_id} in deployment {deployment_id}.
        slots:
          target_commit_id: query.target_commit_id
          deployment_id: path.deployment_id
      - text: Compare commit {target_commit_id} against {base_commit_id} for deployment {deployment_id}.
        slots:
          target_commit_id: query.target_commit_id
          base_commit_id: query.base_commit_id
          deployment_id: path.deployment_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/agent-os/deployments/{deployment_id}/memory/search'].post
  update:
    x-apievangelist-phrasing:
      intent: Search a deployment's approved memory
      effect: read
      questions:
      - Can my agent search only approved memory and skip unreviewed candidates?
      - Is it possible to exclude memory older than a certain number of days from a search?
      instructions:
      - text: Search deployment {deployment_id} memory for {query}.
        slots:
          deployment_id: path.deployment_id
          query: requestBody.query
      - text: Find approved memories about {query} from the last {max_age_days} days in deployment {deployment_id}.
        slots:
          query: requestBody.query
          max_age_days: requestBody.max_age_days
          deployment_id: path.deployment_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/agent-os/deployments/{deployment_id}/memory/reconcile'].post
  update:
    x-apievangelist-phrasing:
      intent: Turn reconciliation output into a memory proposal
      effect: write
      questions:
      - Can my agent learn from the gap between what it expected and what actually happened?
      - Does a reconciliation memory proposal change pricing or trust automatically?
      instructions:
      - text: Create a post-action memory proposal for deployment {deployment_id} from reconciliation {reconciliation}.
        slots:
          deployment_id: path.deployment_id
          reconciliation: requestBody.reconciliation
      - text: Record the actual outcome {actual_outcome} versus the pre-action result {pre_action_result} as a memory candidate on deployment {deployment_id}.
        slots:
          actual_outcome: requestBody.actual_outcome
          pre_action_result: requestBody.pre_action_result
          deployment_id: path.deployment_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/agent-os/deployments/{deployment_id}/memory/policy'].get
  update:
    x-apievangelist-phrasing:
      intent: Read a deployment's memory policy
      effect: read
      questions:
      - Which memory types are allowed, blocked or auto-written for my deployment?
      - Is cross-agent memory sharing turned on for this deployment?
      instructions:
      - text: Show the memory policy for deployment {deployment_id}.
        slots:
          deployment_id: path.deployment_id
      - text: Tell me the receipt-evidence rules in deployment {deployment_id}'s memory policy.
        slots:
          deployment_id: path.deployment_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/agent-os/deployments/{deployment_id}/memory/policy'].patch
  update:
    x-apievangelist-phrasing:
      intent: Update a deployment's memory policy
      effect: write
      questions:
      - How do I change which memory types my agent may auto-write?
      - Can I enable public or cross-agent sharing of deployment memory?
      instructions:
      - text: Update the memory policy on deployment {deployment_id}.
        slots:
          deployment_id: path.deployment_id
      - text: Change deployment {deployment_id}'s memory policy to block pricing memory.
        slots:
          deployment_id: path.deployment_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/agent-os/deployments/{deployment_id}/memory/{memory_id}/approve'].post
  update:
    x-apievangelist-phrasing:
      intent: Approve a memory candidate
      effect: write
      questions:
      - How do I approve a memory my agent proposed so it can be retrieved?
      - Why would approving a provider-trust memory candidate fail?
      instructions:
      - text: Approve memory candidate {memory_id} in deployment {deployment_id}.
        slots:
          memory_id: path.memory_id
          deployment_id: path.deployment_id
      - text: Accept the proposed memory {memory_id} for deployment {deployment_id} into approved memory.
        slots:
          memory_id: path.memory_id
          deployment_id: path.deployment_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/agent-os/deployments/{deployment_id}/memory/{memory_id}/reject'].post
  update:
    x-apievangelist-phrasing:
      intent: Reject a memory candidate
      effect: write
      questions:
      - Can I turn down a memory my agent proposed so it's never used?
      - What happens to a rejected memory candidate in future searches?
      instructions:
      - text: Reject memory candidate {memory_id} in deployment {deployment_id}.
        slots:
          memory_id: path.memory_id
          deployment_id: path.deployment_id
      - text: Decline proposed memory {memory_id} on deployment {deployment_id}.
        slots:
          memory_id: path.memory_id
          deployment_id: path.deployment_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/agent-os/deployments/{deployment_id}/memory/{memory_id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete or redact a memory item
      effect: destructive
      questions:
      - How do I remove a memory item that should never have been stored?
      - Can I redact only certain fields of a memory while keeping the audit trail?
      instructions:
      - text: Delete memory item {memory_id} from deployment {deployment_id}.
        slots:
          memory_id: path.memory_id
          deployment_id: path.deployment_id
      - text: Redact fields {fields} of memory {memory_id} in deployment {deployment_id} because {reason}.
        slots:
          fields: requestBody.fields
          memory_id: path.memory_id
          deployment_id: path.deployment_id
          reason: requestBody.reason
      method: generated
      generated: '2026-09-26'