Skip to Content
DocumentationCompanion MemoryUse cases & workflows

Use cases and workflows

Companion Memory is designed to solve real-world coordination problems without sacrificing personal sovereignty or handing private archives to cloud aggregators.

The five workflows below show the wire payloads, local search evaluation, disclosure ceilings, and audit records for common coordination tasks.

Use case 1: Family photo requests (“Photos from the lake trip”)

Scenario: Maya wants to make a photo album from last summer’s family trip to Lake Tahoe. She asks Jordan: “Do you have photos of us from the lake trip?“

1. Request composition

Maya’s Companion analyzes her prompt and constructs a structured ask body (contentAskSchema):

{
  "askId": "a1b2c3d4-e5f6-7a8b-9c0d-1e2f3a4b5c6d",
  "askerHandle": "maya",
  "prompt": "Do you have photos of us from the lake trip?",
  "request": {
    "archetype": "content",
    "subject": "lake trip",
    "dataClass": "photos",
    "from": "2024-07-01T00:00:00Z",
    "to": "2024-07-31T23:59:59Z"
  }
}

2. Local retrieval execution

When the ask arrives at Jordan’s appliance, Jordan has not configured a standing grant for Maya. The ask queues in Jordan’s For you inbox.

Jordan’s Companion runs the search locally to prepare the preview:

  • Identifies the Lake Tahoe trip entity in the graph.
  • Finds 42 matching photographs taken between July 12 and July 18, 2024.
  • Identifies that 14 photos include non-family bystanders and 2 include GPS coordinates of Jordan’s private campsite.

3. Review decision

Jordan opens the review card in Companion Memory:

  1. Card badge: no standing grant (Review required).
  2. Would search: content · photos.
  3. Jordan’s choices:
    • Approve and answer: Grants the requested level.
    • Answer with less: Selects A summary only.
    • Decline: Refuses the ask.

Jordan selects A summary only.

4. What crossing the boundary looks like

Data tierRecords on Jordan’s applianceData sent to Maya
Raw files42 high-resolution JPEG/RAW files (1.4 GB)None
Location tagsPrecise campsite latitude/longitude coordinatesNone
FacesFace embeddings of all individuals in the frameNone
Answer payloadMatched 42 items"Found 42 photos from Lake Tahoe in July 2024."

5. Audit anchoring

Jordan’s appliance records the interaction in ci.ask_audit:

  • backing_entities: 42 document UUIDs (Jordan’s private record of what was searched).
  • disclosed_entities: [] (Empty, because summary rungs disclose zero references).
  • disclosed_count: 42 (The magnitude confirmed).
  • d: ESaid... (Canonical SHA-256 SAID digest anchoring the record).

Use case 2: Frictionless calendar coordination (“Free for lunch on Friday?”)

Scenario: Alex’s assistant wants to schedule lunch with Taylor: “Free for lunch on Friday between 12:00 and 14:00?“

1. Standing grant configuration

Taylor frequently schedules meetings with Alex and has configured a standing grant:

  • Who: Alex (peer-alex-uuid).
  • Data class: calendar.
  • Allowed archetype (queryType): availability (Free/busy checks).
  • Maximum ceiling: boolean (Rung 1).
  • Mode: auto (grant-auto, answering automatically without human review).

2. Search evaluation and redaction

Taylor’s Companion receives the ask (availabilityAskSchema):

{
  "askId": "b2c3d4e5-f6a7-8b9c-0d1e-2f3a4b5c6d7e",
  "askerHandle": "alex",
  "prompt": "Free for lunch on Friday between 12 and 2?",
  "request": {
    "archetype": "availability",
    "from": "2026-10-30T12:00:00Z",
    "to": "2026-10-30T14:00:00Z",
    "minMinutes": 60,
    "purpose": "lunch"
  }
}

Taylor has a calendar entry:

  • Title: “Dr. Smith - Therapy”
  • Time: 11:30 - 12:30
  • Category: health / sensitive

3. The privacy guarantee

Because the standing grant permits only the boolean rung:

  • The title, category, attendees, and location are never evaluated for disclosure.
  • The engine computes a boolean overlap check: hasConflict = true.
  • The answer returned to Alex is false.

Alex’s assistant receives an immediate confirmation that Taylor is unavailable, with zero risk of disclosing private medical or personal calendar details.

Use case 3: Professional network queries (“Do you know anyone at Acme?”)

Scenario: Elena is looking for a contact at Acme Corp and asks Marcus: “Do you know anyone who works at Acme?“

1. Graph traversal

Marcus’s Companion evaluates the relationship ask ({ "archetype": "relationship", "subject": "Acme Corp" }) against the local entity graph:

  • Matches entity Acme Corp (organization).
  • Traverses incoming employed_at edges.
  • Finds two contacts:
    1. Sarah Chen (VP of Engineering, frequent email correspondent).
    2. David Miller (Technical Recruiter, met once at a conference).

2. Enforcement of the count ceiling

Elena has the peer trust tier on Marcus’s appliance. The standing rule restricts contact queries to count (Rung 2):

  • Ceiling applied: Rung 2 (count).
  • Entities withheld: All name, email, and position records are scrubbed.
  • Answer delivered: "Marcus knows 2 people at Acme Corp."

Elena learns that Marcus can help with an introduction, but Marcus retains complete discretion over whether to reveal Sarah or David’s identity.

Use case 4: Autonomous agent delegation (Cross-appliance MCP tools)

Scenario: An autonomous AI coding agent (for example, OpenClaw running on a developer’s desktop) needs architecture documentation from a remote team lead’s Companion Memory.

1. Agent tool invocation

The developer’s agent invokes the Memory MCP tool:

{
  "tool": "ask_peer",
  "arguments": {
    "peerHandle": "team-lead",
    "prompt": "What is the token expiration policy in the auth architecture?",
    "dataClass": "documents"
  }
}

2. Sovereign peer signature

The developer’s Companion uses its Ed25519 KERI key to sign the HTTP message:

POST /agent/v1/ask HTTP/1.1
Host: lead.internal.net
Signature-Input: sig1=("@method" "@target-uri" "content-digest");created=1730040000;keyid="did:keri:D...dev-aid"
Signature: sig1=:base64signature...:
Content-Digest: sha-256=:digest...:
Content-Type: application/json

3. Verification without third-party tokens

The team lead’s appliance:

  1. Reconstructs @target-uri from its configured endpoint.
  2. Verifies the Ed25519 signature directly against the developer’s registered public key.
  3. Authenticates the caller as did:keri:D...dev-aid without contacting Companion Portal or verifying an external JWT.
  4. Executes the retrieval, redacts internal environment variables and secret tokens, and returns the approved documentation.

Use case 5: Ephemeral shared searches for external projects

Scenario: Liam wants to share renovation receipts and contractor invoices with an insurance adjuster who does not use Companion Memory.

1. Query pinning

Liam creates a Saved Search in Companion Memory:

  • Filters: category: receipt, tag: kitchen-renovation, date >= 2026-01-01.
  • Matches: 18 invoice documents and 4 building inspection PDFs.

2. Capability token generation

Liam selects Share Search:

  • Access model: Capability token.
  • TTL: 7 days.
  • Passcode: Optional second factor.

3. Read-only sandboxing

When the adjuster opens the URL:

  • The request bypasses session sign-in and authenticates exclusively via the capability token.
  • The SQL query is strictly pinned to Liam’s saved criteria. The adjuster cannot alter parameters to search for medical records, emails, or unrelated files.
  • When Liam finishes the insurance claim, he clicks Revoke Access, immediately invalidating the capability token.
Last updated on
Asking & sharing architectureDecentralized trust (KERI & ToIP)