---
title: PersonaKit MCP tools reference
description: Parameters and results of personakit_read and personakit_propose in release 0.1.
status: pre-release
audience: people who run PersonaKit locally, contributors, and AI assistants
last_verified: 2026-11-12
---

# MCP tools reference

All examples are fictional.

## `personakit_read`

![What happens on a personakit_read call: your decisions are applied, memories are ranked by word overlap, approved ones fill up to three places, and quotes are masked](../assets/read-flow.svg)

| Parameter | Type | Meaning |
|---|---|---|
| `question` | string | What the assistant is trying to answer |
| `limit` | integer | Most memories to return; default 7, clamped to 1-20 |

Result:

```json
{
  "memories": [
    {
      "id": "m_0123456789ab",
      "text": "Prefers direct, practical feedback",
      "category": "preferences",
      "confirmed": false,
      "evidence": ["give me blunt feedback, skip the padding"]
    }
  ],
  "withheld": 1,
  "note": "Unconfirmed: extracted from the owner's conversations but not yet reviewed by them."
}
```

| Field | Meaning |
|---|---|
| `confirmed` | `true` only for `approved` memories |
| `category` | One of `communication`, `work-style`, `tools`, `preferences`, `background`, `constraints`, `other` |
| `evidence` | Up to two supporting quotes, each shortened to 240 characters with email addresses masked |
| `withheld` | Count of matching restricted memories; their content is never returned |
| `note` | Reminder that unconfirmed memories are unreviewed |

`note` is present only when at least one returned memory is unconfirmed.

When fewer than three memories match the question, approved memories fill the remaining places, so a
result can include approved memories that share no words with the question.

Empty result: `memories` is an empty list. That means nothing matched and nothing is approved, not that nothing exists.

## `personakit_propose`

| Parameter | Type | Meaning |
|---|---|---|
| `text` | string | The memory, one short statement |
| `quote` | string | The person's own words that support it |
| `category` | string | One of the known categories; anything else becomes `other` |

Result: `{"stored": true, "id": "...", "new": true, "state": "unconfirmed"}`, or
`{"stored": false, "reason": "..."}`. `reason` is one of `empty_text`, `too_long` (over 300 characters),
`credential_shape`, or `empty_quote`. `new` is `false` when the same memory already existed; its state is left as it was.