retrieve_memory

Invoke retrieve_memory via JSON-RPC tools/call on POST /v1/mcp/memory.

Read-only tool. Retrieves company memory context — does not write to chat history or modify your PAM workspace.

When to call

Pass a prompt when the task may depend on company-specific context. Prefer retrieval before guessing about:

People, teams, and ownership
Projects, decisions, and priorities
Processes, customers, and internal terminology
Documents, meetings, and historical context

Parameters

string

required

Natural-language description of the context your agent needs.Maximum length: 8,000 characters.

string

Optional stable conversation ID. You can omit it — the server falls back to the MCP handshake Mcp-Session-Id (one per user account, 30-day TTL). When a session ID is resolved (explicit or fallback), the server stores your last 5 prompts in Redis (30-day TTL) and may include the last 3 prior prompts in the triage step only when triage is enabled on the server. It does not carry prior retrieval results or maintain agent-side conversation memory.

Only prompt and session_id are accepted. Any other argument returns invalid_arguments.

Response fields

On success, the tool returns HTTP 200 with content (agent-readable text) and structuredContent (machine-readable metadata).

`content`

Field	Description
`content[].type`	Always `"text"` in v1
`content[].text`	Markdown report for your agent — summary, reasoning, ranked facts, and optional document excerpts

`structuredContent`

Field	Description
`status`	`"ok"` or `"error"`
`memory_ready`	Whether company memory is available for retrieval
`readiness_state`	Readiness label (for example `ready_rich`)
`content_text`	Same markdown as `content[].text`
`triage`	Routing decision, reasoning, and optional rewritten query
`phase1`	Section targeting metadata (searched paths, strategy, token estimate)
`retrieval`	Ranked facts, entities, relationships, documents, and coverage stats
`diagnostics`	Request ID, duration, token estimate, and sections searched

Key fields inside retrieval:

Field	Description
`context_summary`	Short executive summary of what was found
`facts`	Ranked statements with relevance scores and source paths
`entities`	People and organizations tied to the query
`relationships`	Graph edges between entities
`documents`	Relevant document excerpts (may be truncated in the response)
`total_items`	Count of retrieved items
`avg_relevance_score`	Average relevance across returned items
`coverage_assessment`	Coverage label (for example `comprehensive`)

On error, structuredContent includes:

Field	Description
`status`	`"error"`
`error_code`	Machine-readable error (see Error codes)
`error_message`	Human-readable explanation

Examples

Tool arguments

{
  "prompt": "What do we know about our current project priorities, and who is responsible for follow-up on each?",
  "session_id": "cursor-thread-k7m2p"
}

Full JSON-RPC request

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "retrieve_memory",
    "arguments": {
      "prompt": "Who are our main enterprise clients and which accounts have the highest recurring revenue?",
      "session_id": "claude-code-2026-05-29"
    }
  }
}

Successful response (abbreviated)

The content[].text field is a markdown report your agent can read directly. Document excerpts in production responses may be long; they are shortened here.

{
  "content": [
    {
      "type": "text",
      "text": "# Retrieved Company Context\n\n**Query:** Who are our main enterprise clients and which accounts have the highest recurring revenue?\n\n**Summary:** The company serves enterprise accounts across media, healthcare, and software, plus a smaller set of active platform customers. Three documented accounts drive most tracked recurring revenue; tier-1 strategic accounts include major publishers and broadcast partners.\n\n## How This Context Was Found\n**Reasoning:** The query asks for client lists and revenue-related account data, so client directories and financial reports were targeted.\n**Sections searched:** Relationships > Client Organizations, Financials > Active Accounts MRR, Strategy > Ideal Customer Profile\n\n## Relevant Facts\n\n- [97%] **Tier-1 strategic accounts include a major broadcaster and two enterprise publishers.** (source: Client Organizations)\n- [95%] **Three active accounts generate documented monthly recurring revenue in healthcare, education, and enterprise software.** (source: Active Accounts MRR)\n\n---\n*Retrieved 12 items | Avg relevance: 89% | Coverage: comprehensive*"
    }
  ],
  "structuredContent": {
    "status": "ok",
    "memory_ready": true,
    "readiness_state": "ready_rich",
    "content_text": "# Retrieved Company Context\n\n...",
    "triage": {
      "decision": "retrieve",
      "reasoning": "The query depends on company-specific client and revenue context.",
      "rewritten_query": "Who are our main enterprise clients and which accounts have the highest recurring revenue?"
    },
    "phase1": {
      "search_strategy": "moderate",
      "estimated_tokens": 42000,
      "targeted_sections": [
        {
          "tree_path": "Company Context > Relationships > Client Organizations",
          "relevance_reason": "Lists active clients and strategic tiers."
        }
      ]
    },
    "retrieval": {
      "context_summary": "Enterprise clients span media and publishing; tracked MRR is concentrated in three active accounts.",
      "facts": [
        {
          "statement": "Tier-1 strategic accounts include a major broadcaster and two enterprise publishers.",
          "relevance_score": 0.97,
          "source_path": "company_context/relationships/client_organizations.md"
        }
      ],
      "entities": [
        {
          "label": "Northwind Retail",
          "type": "organization",
          "properties": { "relationship_to_company": "client", "industry": "Retail" }
        }
      ],
      "total_items": 12,
      "avg_relevance_score": 0.89,
      "coverage_assessment": "comprehensive"
    },
    "diagnostics": {
      "request_id": "f30ee45b-06eb-4c46-9fa7-e76d29ba7131",
      "duration_ms": 48210,
      "estimated_tokens": 8400,
      "sections_searched": [
        "Company Context > Relationships > Client Organizations",
        "Company Context > Financials > Active Accounts MRR"
      ],
      "avg_relevance_score": 0.89,
      "gemini_calls_estimate": 3
    }
  },
  "isError": false
}

Large responses can take tens of seconds and thousands of tokens. Use the summary and top-ranked facts first; drill into documents only when your agent needs source-level detail.

Session ID behavior

session_id is optional. Most clients only need to pass prompt.

Scenario	Behavior
Omit `session_id`	Server uses the handshake `Mcp-Session-Id` for this call
Pass explicit `session_id`	Overrides the handshake ID for that call (useful for per-thread IDs in multi-tab agents)

For whichever session ID applies:

What it does	What it does not do
Stores last 5 prompts in Redis (30-day TTL)	Return prior turns to your agent
May feed last 3 prompts into triage only (when triage is enabled)	Inject prior retrieval results into new calls
Persists on the server-side request record	Replace your agent’s conversation memory

Your MCP client or agent is still responsible for conversation memory. Pass a stable session_id per thread only if you want separate Redis prompt history from the default MCP session — for example, multiple concurrent chats under one account.

Retrieval must complete within 120 seconds. Exceeding the limit returns retrieval_timeout.

Request history

Every counted call stores the full prompt and response for your review on Request Log in the PAM app, or via GET /v1/dev/mcp-requests.

Getting started

Reference

When to call

Parameters

Response fields

`content`

`structuredContent`

Examples

Tool arguments

Full JSON-RPC request

Successful response (abbreviated)

Session ID behavior

Request history

​When to call

​Parameters

​Response fields

​content

​structuredContent

​Examples

​Tool arguments

​Full JSON-RPC request

​Successful response (abbreviated)

​Session ID behavior

​Request history

When to call

Parameters

Response fields

`content`

`structuredContent`

Examples

Tool arguments

Full JSON-RPC request

Successful response (abbreviated)

Session ID behavior

Request history