> ## Documentation Index
> Fetch the complete documentation index at: https://praison.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# MCP Memory Tools
> Call PraisonAI's memory from any MCP client โ add, search, show, and clear from Claude Desktop or Cursor
Every `praisonai-mcp` host exposes four memory tools your MCP client can call directly โ no PraisonAI code required on the client side.
```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph LR
Client[๐ MCP Client
Claude Desktop / Cursor] --> Host[โ๏ธ praisonai-mcp
Host]
Host --> Tools[๐ง 4 Memory Tools
show ยท add ยท search ยท clear]
Tools --> Core[๐ง praisonaiagents.memory
Memory]
classDef client fill:#6366F1,stroke:#7C90A0,color:#fff
classDef host fill:#8B0000,stroke:#7C90A0,color:#fff
classDef tools fill:#189AB4,stroke:#7C90A0,color:#fff
classDef core fill:#10B981,stroke:#7C90A0,color:#fff
class Client client
class Host host
class Tools tools
class Core core
```
## Quick Start
Start the host over STDIO and point your MCP client at it.
```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
praisonai-mcp serve --transport stdio
```
The host registers the four memory tools at startup โ see the [praisonai-mcp Package](/docs/features/praisonai-mcp-package) guide.
Store a fact from your MCP client with a JSON args payload.
```json theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
{ "content": "User prefers concise answers" }
```
Retrieve it later by meaning, not exact text.
```json theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
{ "query": "user preferences", "limit": 5 }
```
***
## How It Works
Each tool call spins up a `Memory()` instance, runs one core method, and returns a string result.
```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
sequenceDiagram
participant Client as MCP Client
participant Server as praisonai-mcp
participant Adapter as Memory Adapter
participant Core as Memory
Client->>Server: call praisonai.memory.add
Server->>Adapter: memory_add(content, metadata)
Adapter->>Core: store_short_term(content, metadata)
Core-->>Adapter: stored
Adapter-->>Server: "Memory added successfully"
Server-->>Client: tool result
```
Memory is process-local and shared across all four tools โ each call constructs a single `Memory()` instance against the same store.
***
## Tools Reference
Four tools, mapped one-to-one onto the core `Memory` API.
| Tool | Arguments | Returns | Core method |
| ------------------------- | ------------------------------------------------------ | ----------------------------------------------------------------- | --------------------------------------- |
| `praisonai.memory.show` | `user_id: str = None` | All stored memories as a string, filtered by `user_id` when given | `get_all_memories()` |
| `praisonai.memory.add` | `content: str`, `metadata: str = None` (JSON string) | `"Memory added successfully"` | `store_short_term(content, metadata=โฆ)` |
| `praisonai.memory.search` | `query: str`, `limit: int = 10`, `user_id: str = None` | Matching memories as a string | `search(query, user_id=โฆ, limit=โฆ)` |
| `praisonai.memory.clear` | *(none)* | `"All memory cleared"` | `reset_all()` |
Every tool imports `praisonaiagents.memory.Memory` lazily and returns `"Error: Memory module not available"` when the core package is missing, or `"Error: "` on any other failure.
***
## user\_id Filtering
Pass `user_id` to keep each person's memories separate; omit it for a shared global store.
`add` stashes `user_id` inside the JSON `metadata`, while `search` and `show` read it back through the metadata filter.
```json theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
// add for a specific user
{ "content": "Alice ships on Fridays", "metadata": "{\"user_id\": \"alice\"}" }
```
```json theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
// search only Alice's memories
{ "query": "ship schedule", "user_id": "alice" }
```
```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph TB
Q{Per-user memory?}
Q -->|Yes| Pass[๐ Pass user_id]
Q -->|No| Omit[๐ Omit user_id]
classDef decision fill:#F59E0B,stroke:#7C90A0,color:#fff
classDef pass fill:#6366F1,stroke:#7C90A0,color:#fff
classDef omit fill:#10B981,stroke:#7C90A0,color:#fff
class Q decision
class Pass pass
class Omit omit
```
***
## Common Patterns
Three workflows, shown as the JSON args your MCP client sends.
**Persist a preference across chats** โ save once, recall in any later session.
```json theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
// praisonai.memory.add
{ "content": "User prefers concise answers" }
```
```json theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
// praisonai.memory.search
{ "query": "answer style", "limit": 3 }
```
**Per-user isolation** โ tag on write, filter on read.
```json theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
// praisonai.memory.add
{ "content": "Bob works in Pacific time", "metadata": "{\"user_id\": \"bob\"}" }
```
```json theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
// praisonai.memory.search
{ "query": "timezone", "user_id": "bob" }
```
**Wipe memory between demos** โ reset the whole store in one call.
```json theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
// praisonai.memory.clear
{}
```
`clear` is irreversible and resets **both** short-term and long-term memory (`Memory.reset_all()`). Reserve it for demo resets, not per-session cleanup.
***
## Migration (Breaking Rename)
[PraisonAI PR #3531](https://github.com/MervinPraison/praisonai/pull/3531) rebound the adapter to the real core API, renaming the tools your MCP client sees.
| Before PR #3531 | After PR #3531 |
| ---------------------------------------------------------------- | ----------------------------------------------------------- |
| `praisonai.memory.get_all` | **`praisonai.memory.show`** (also accepts `user_id`) |
| `praisonai.memory.clear_all` | **`praisonai.memory.clear`** |
| `praisonai.memory.add` | `praisonai.memory.add` (now takes optional `metadata` JSON) |
| `praisonai.memory.get_session`, `clear_session`, `list_sessions` | **Removed** โ no `session_id` concept in the new adapter |
| *(none)* | **`praisonai.memory.search`** โ new |
The old tool names were always broken โ they bound to methods that never existed on core, so every call returned an `"Error: โฆ"` string. The rename fixes them rather than removing working surface.
***
## Best Practices
Without it, `show` and `search` see everyone's memories. Pass `user_id` on both `add` (inside `metadata`) and `search`/`show` to keep people isolated.
The `add` tool signature takes `metadata: str` โ a JSON string, not an object. Encode it with `JSON.stringify` on the client side before sending.
`clear` calls `Memory.reset_all()`, wiping both stores. Reserve it for demo resets, not per-session cleanup.
Every tool returns `"Error: โฆ"` on failure, so your MCP client sees a normal tool-result envelope. Check the string prefix โ don't rely on an exception.
***
## Related
The host that serves these tools.
Expose agents over MCP alongside memory.
Give agents persistent memory across sessions.
Client vs light server vs heavy host.