The sessionmem server provides a local-first, persistent memory layer for AI coding assistants, storing everything in a SQLite file. It allows you to store, retrieve, and manage project-specific knowledge across sessions.
retrieveMemories: Search for the most relevant memories using a semantic query, ranked by relevance, recency, and importance. Supports configurable result limits (1–100), retrieval modes (auto or on-demand), and search depth (default or deep).
storeMemory: Save a new memory (decision, fact, summary, or warning) with metadata such as session ID, source adapter, kind, content, importance score (1–10), and optional secret redaction.
listMemories: Retrieve a full list of all memories stored for the current project.
getMemory: Fetch the full details of a specific memory by its unique ID.
forgetMemory: Permanently delete a specific memory by its ID.
stats: View a summary of total memories stored and session event counts for the current project.
85.6% fewer tokens. Every session starts knowing your codebase. Stored entirely on your machine.
New session. Claude starts fresh.
WITHOUT sessionmem:
You explain the stack. The JWT bug from last week.
The Stripe migration that's halfway done. The billing code to stay away from.
Same questions. Different day.
WITH sessionmem:
[warning] JWT blacklist must be checked before issuing new tokens. Fixed PR #47.
[decision] Stripe migration ~50% done. Do NOT use /lib/billing-v1.
[fact] Stack: TypeScript, Next.js, Postgres.
Claude: "Looks like you're mid-Stripe migration. Where do you want to pick up?"sessionmem is an MCP server that watches your coding sessions and stores what actually mattered -- decisions, warnings, things that would bite you if Claude forgot them. At the start of each new session it injects the relevant bits automatically. Works with Claude Code, Cursor, Cline, Codex, Windsurf, and anything that speaks MCP.
Everything stays on your machine. No account, no cloud, no data leaving your computer unless you explicitly turn that on.
No programming experience needed. You just need a terminal (Command Prompt, Terminal, or PowerShell) and Node.js installed.
npm install -g sessionmemRun this inside the project folder you're working on, with your AI tool (Claude Code, Cursor, etc.) configured:
sessionmem installThis does three things:
Tells your AI tool's MCP host about sessionmem so it can be launched automatically.
Creates a config file at ~/.sessionmem/config.json with safe, privacy-respecting defaults, but only if one doesn't already exist.
Injects instructions into ~/.claude/CLAUDE.md so Claude Code knows about sessionmem's tools and uses them proactively (idempotent, so safe to re-run).
sessionmem run(Most of the time you won't run this yourself. Your AI tool's host starts it automatically once it's registered.)
That's it. From here:
sessionmem watches your sessions in the background.
At the end of each session, it writes down a short summary of what mattered.
At the start of your next session, it quietly reminds your assistant of the relevant bits.
You can verify everything is working with:
sessionmem pingRelated MCP server: codemem
If you've used an AI coding assistant for more than a day, you've probably hit this:
You spend twenty minutes explaining your project's setup, the libraries you use, a tricky bug you already fixed, and a decision you made about how authentication should work. The assistant nods along, helps you out... and then in your next session, it has forgotten all of it. You explain everything again.
This happens because most AI assistants only "know" what's inside the current conversation. Once that conversation ends, the context is gone.
sessionmem fixes this by sitting quietly between your assistant and your project:
While you work, it captures what happens in the session.
When the session ends, it summarizes the important parts (decisions made, warnings, useful facts) into short, durable notes.
The next time you start a session, it reminds the assistant of the most relevant notes, automatically, in a small amount of text.
You don't run any of these steps yourself. Once installed, it just works in the background.
There are other "memory for Claude" projects out there (for example, tools like claude-mem and similar community projects). Here's what sets sessionmem apart:
sessionmem | Typical cloud/Claude-only memory tools | |
Where is data stored? | A single SQLite file on your computer ( | Often a hosted service, a cloud vector database, or a separate server process you have to run |
Account / sign-up required? | No, never | Sometimes |
Which AI tools does it work with? | Claude Code, Cursor, Codex, Cline, Windsurf, Antigravity, QCoder, and any other MCP-compatible host | Usually just one specific tool (commonly Claude Code only) |
Secret redaction | Built in, on by default. API keys, tokens, passwords, and private keys are scrubbed before anything is saved. | Often not handled, or left to the user |
Token budget control | Injected memories are trimmed to a small, fixed token budget so they don't bloat every conversation (see benchmarks below) | Varies, often unbounded |
Old/stale memory cleanup | Built-in retention policy automatically prunes old memories (configurable, on by default) | Often grows forever ("memory rot") |
Team sharing | Optional, via a shared folder you already control (network drive, synced directory). No server needed. | Usually requires a shared hosted backend |
Offline-capable | Yes, fully. Works with no network connection by default. | Usually requires network access to the memory service |
In short: sessionmem is the boring, local, "just a SQLite file" option: easy to inspect, back up, and delete, with no lock-in to any one vendor's AI tool.
These numbers come from npm run benchmark (scripts/benchmark.mjs), which runs the real production retrieval and injection code over a fixed, synthetic set of test data with no network calls. The results are fully reproducible. See docs/benchmark.md for the full report and how to regenerate it.
~85.6% reduction in tokens compared to carrying full session history.
Tokens | |
Full session history (baseline) | 1,587 |
What sessionmem injects at the start of your next session | 228 |
In practice: instead of re-reading (or re-explaining) about 1,600 tokens of past context every session, the assistant gets a 230-token summary of just the things that matter: decisions, warnings, and key facts.
100% hit-rate: every one of the 10 test queries successfully retrieved the memory it was supposed to.
Metric | Result |
Hit-rate (10 curated queries) | 100.0% |
Recall | 100.0% |
Precision | 33.3% |
Precision of 33.3% is expected here: each query retrieves the top 3 candidate memories, and only one of those three is the "expected" match for a given test query. The other two are still relevant context for the agent, just not the one being scored. The important number is recall/hit-rate: the right memory is never missed.
These benchmarks are deterministic and reproducible. Run them yourself:
npm run build # benchmark imports the compiled code from dist/
npm run benchmark # regenerates docs/benchmark.md ┌──────────────────────────────────────────────┐
│ Your AI tool │
│ (Claude Code, Cursor, Codex, Cline, ...) │
└───────────────────────┬──────────────────────┘
│
┌───────────▼───────────┐ ┌──────────────┐
│ sessionmem adapter │ │ sessionmem │
│ (translates for your │ │ CLI │
│ specific AI tool) │ │ (you type │
└───────────┬───────────┘ │ commands) │
│ └──────┬───────┘
▼ │
┌──────────────────────────────────────────────┐
│ sessionmem core engine │
│ watches sessions · writes summaries · │
│ finds relevant memories · trims to fit │
└───────────────────────┬──────────────────────┘
│
▼
┌──────────────────────────────────────────────┐
│ One SQLite file on your computer │
│ ~/.sessionmem/memories.db │
└──────────────────────────────────────────────┘Adapters are small pieces that know how to talk to each specific AI tool. This is why sessionmem can support many tools: adding a new one doesn't change how memory itself works.
The core engine is the same no matter which tool you use. It decides what's worth remembering, how relevant it is later, and how much of it fits in a small "reminder" at the start of your next session.
The database is just a file. You can back it up, move it, inspect it, or delete it like any other file on your computer.
For a deeper technical dive, see docs/architecture.md.
Command | What it does |
| Register sessionmem with the current MCP host and write default config. |
| Remove sessionmem from the host. |
| Start the MCP server. |
| Check server connectivity. |
| Search memories by semantic query. |
| List all memories for the current project. |
| Show full details of a memory. |
| Delete a memory by ID. |
| Export memories to a JSON file. |
| Import memories from a JSON file. |
| Show memory statistics for the current project. |
| Show token savings from compression and injection, with percentage. |
| Scan stored memories for secrets; |
| Prune old memories (dry-run by default). |
| Read and write policy config. |
| Manage shared-path team memory mode. |
| Push local memories and pull teammate memories via the shared path. |
Everything stays on your machine by default. No account, no telemetry, no hosted memory service. Storage, retrieval, and summarization all run locally, governed by ~/.sessionmem/config.json.
Before anything is saved, sessionmem automatically removes common secret patterns and replaces them with REDACTED:
Email addresses
API keys (sk-..., AWS AKIA..., GitHub ghp_.../gho_..., etc.)
Bearer tokens and JWTs
Private key blocks (-----BEGIN ... PRIVATE KEY-----)
Connection-string style secrets (password=..., secret=...)
This is on by default. You can scan and clean up older memories at any time:
sessionmem redact-scan # see what would be redacted
sessionmem redact-scan --apply # actually redact in placeFull details: docs/privacy-and-retention.md.
"Memory rot" is what happens when a memory system keeps accumulating notes forever. Eventually it fills up with outdated decisions, duplicate facts, and noise, and the assistant starts surfacing stale information instead of helpful information.
sessionmem is designed to avoid this in a few ways:
Retention pruning: memories older than a configurable window (default 90 days) are automatically eligible for cleanup. This runs as a light check at the end of every session, and can also be run manually:
sessionmem retention prune # dry run - shows what *would* be deleted
sessionmem retention prune --force # actually deletesImportance-weighted ranking: when memories are retrieved, they're ranked by a blend of semantic relevance, recency, and importance. Old, low-importance notes naturally sink to the bottom and stop being surfaced even before they're pruned.
Token-budgeted injection: only the top-ranked, most relevant memories are injected (trimmed to a small token budget, see benchmarks), so even a large memory store doesn't produce bloated, noisy context.
Conflict resolution in team mode: when memories are merged from teammates, the system uses last-write-wins by id (so stale duplicates don't pile up) while preserving the higher importance score (so a critical warning doesn't get silently downgraded).
The retrieval benchmark above (100% hit-rate / 100% recall) demonstrates that even with the ranking and trimming in place, the right memory still surfaces. Accuracy is not traded away for compactness.
You're always in control: export everything first if you want a permanent record before pruning:
sessionmem exportWant your whole team's AI assistants to share decisions and warnings? Point sessionmem at a shared folder (a network drive, a synced directory, or any location everyone can read and write):
sessionmem team enable <shared-path>
sessionmem syncOff by default: nothing is shared until you turn it on.
No server needed. It's just files in a folder you already control.
Teammates' memories show up with an author: prefix so you know where they came from.
Secrets are re-redacted on every pulled memory, so a teammate's snapshot can't reintroduce something your redaction policy would have stripped.
Full details, including the trust model: docs/team-mode.md.
By default, summarization (turning a session into a short memory) happens entirely locally, with no API calls.
If you explicitly opt in (allowCloudSummarization=true) and provide an ANTHROPIC_API_KEY, summarization can use Claude's API for higher-quality summaries. If that ever fails, it automatically falls back to local summarization. Your sessions are never left unsummarized.
Details: docs/cloud-summarization.md.
sessionmem works with any MCP-compatible host, including:
Claude Code
Cursor
Codex
Cline
Windsurf
Antigravity
QCoder
...and any other tool that implements the Model Context Protocol.
Architecture: how the core engine, adapters, CLI, and SQLite storage fit together.
Benchmark: full token-reduction and retrieval-accuracy report, and how to reproduce it.
Privacy and retention: secret redaction, retention pruning, and config.
Team mode: shared-path team memory.
Cloud summarization: the opt-in cloud summarization path.
Migration: the SQLite migration system and version-upgrade policy.
Troubleshooting: install failures, adapter issues, and better-sqlite3 native-build problems.
Run into trouble installing or running sessionmem? Start with docs/troubleshooting.md. It covers install failures, adapter-specific issues, missing session data, and native module (better-sqlite3) build problems on different platforms.
Two quick checks that resolve most reports:
sessionmem install # idempotent — re-registers the MCP server and all three hooks
sessionmem stats # memories, sessions, and session_events for the current projectIf stats shows sessions: 0 after real work, see “0 sessions” / no session data recorded. Memories are keyed to the repository root, so every directory inside one repo shares a bucket; outside a repo the working directory itself is the key.
Quick checks:
sessionmem ping # is the server reachable?
sessionmem stats # is data being stored?How do I give Cursor, Cline, or Windsurf memory between sessions?
Install sessionmem (npm i -g sessionmem), then run sessionmem install in your project. It registers as an MCP server with any supported host automatically.
How do I give Claude Code persistent memory?
Same install. sessionmem also ships as a Claude Code plugin (the .claude-plugin file in the repo), so it works with Claude Code's native plugin system too.
Is there a local MCP memory server that works offline with no API key?
Yes. sessionmem stores everything in a single SQLite file at ~/.sessionmem/memories.db and works fully offline by default. Nothing leaves your machine unless you explicitly enable the optional cloud summarization path.
How is sessionmem different from claude-mem? sessionmem is not Claude-only. It works with Cursor, Cline, Codex, Windsurf, Antigravity, QCoder, and any other MCP host, not just Claude Code. It also redacts secrets (API keys, tokens, JWTs) by default, prunes stale memory automatically, and ships reproducible benchmarks you can run yourself.
Does sessionmem send my code to the cloud? No. Nothing leaves your machine by default. The optional cloud summarization path is opt-in and off by default.
How do I see how many tokens sessionmem saved me?
Run sessionmem savings to see a breakdown of storage compression (raw session tokens vs memory tokens) and injection efficiency. Add --json for machine-readable output.
Issues and pull requests are welcome. The codebase is TypeScript, tested with Vitest, and linted with ESLint:
npm install
npm run build
npm test
npm run lintMCP config for local development: Copy .mcp.json.example to .mcp.json for local dev, or use sessionmem install to auto-configure. The .mcp.json file is gitignored because it contains machine-specific paths.
Persist multiple memory units in a single atomic SQLite transaction. Significantly faster than calling storeMemory repeatedly for session-end writes of 10-20 memories.
WHEN TO CALL: At session end or whenever you have multiple memories to store at once. Reduces overhead from per-insert fsync by wrapping all writes in one transaction.
WHEN NOT TO CALL: For a single memory — use storeMemory instead. For imports from external files — use importMemories.
Each item in the memories array follows the same schema as storeMemory (memoryId, sessionId, sourceAdapter, kind, content, importance). Invalid items are reported individually; valid items are still stored atomically.
NOTE: the per-item memory echoed back in the response has its content truncated to 2000 characters (a batch can return many rows). The full body is still persisted — fetch it with getMemory if you need the complete text. (Single-record storeMemory echoes the full content.)
| Name | Required | Description | Default |
|---|---|---|---|
| memories | Yes | Array of memory objects to store. Each must include: memoryId (unique UUID), sessionId, sourceAdapter, kind, content (self-contained text), importance (1-10). Minimum 1 item, maximum 100. Per-item results may include `warningCodes` (e.g. 'session_write_limit_warning', 'redaction_partial_failure') — advisory signals, not failures. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Description adds atomicity, per-item error handling, and response truncation behavior beyond annotations. Annotations only provide nondestructive and non-idempotent hints, but description fills gaps with important behavioral details.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with clear sections. Every sentence adds value, front-loading the core atomic write benefit. No fluff or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given full schema coverage, no output schema, and minimal annotations, the description provides sufficient context: atomicity, performance, when to use, and response truncation details. No gaps for correct tool invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema already describes parameters. Description adds context about array behavior and per-item validation, but does not significantly extend meaning beyond schema. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool persists multiple memory units atomically in SQLite, which is faster than repeated calls to storeMemory. It distinguishes from sibling tools storeMemory (single) and importMemories (external imports).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit WHEN TO CALL (session end or multiple memories) and WHEN NOT TO CALL (single memory → storeMemory, external imports → importMemories) sections provide clear guidance on appropriate use cases.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fallback memory retrieval for hosts that do not support MCP resources. Call this instead of accessing the sessionmem:// resource URI directly when the host lacks resource support. Semantically equivalent to retrieveMemories — returns stored memories ranked by relevance to the query. Read-only; no side effects.
WHEN TO CALL: At session start and mid-session when you need to retrieve context and the host does not support MCP resources. Do not call if the host supports MCP resources — use the sessionmem:// resource URI or retrieveMemories tool instead.
Parameter query: natural-language description of what context you need to recall (e.g. 'API design decisions', 'database schema choices').
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | Natural-language description of what context you need to recall. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses it is read-only with no side effects, and returns memories ranked by relevance. No annotations provided, so description fully informs agent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three concise paragraphs, front-loaded with purpose, then usage, then parameter detail. No unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given one parameter, no output schema, and moderate complexity, description fully covers purpose, usage, and parameter meaning.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers parameter with description, and description adds examples of query values. Since schema coverage is 100%, baseline is 3; the added examples justify a 4.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states it is a fallback memory retrieval for hosts without MCP resource support, returns memories ranked by relevance, and distinguishes from siblings like retrieveMemories and the resource URI.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly specifies when to call (session start, mid-session when host lacks resource support) and when not to call (host supports resources, instead use URI or retrieveMemories).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Permanently delete a single memory by ID. The record is removed from the local SQLite store immediately and CANNOT be recovered. Destructive and irreversible.
WHEN TO CALL: Only when a memory is known to be incorrect, dangerously outdated, or a duplicate that would mislead future sessions.
WHEN NOT TO CALL: If there is any doubt. A memory that is merely old or low-relevance does not need deletion — retrieval ranking deprioritizes it automatically.
| Name | Required | Description | Default |
|---|---|---|---|
| memoryId | Yes | Exact UUID of the memory to permanently delete. Obtain from a prior listMemories or retrieveMemories call. Deletion is immediate and irreversible. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond annotations (destructiveHint=true), description adds details: deletion from local SQLite store, immediate, irreversible, and unrecoverable, providing full behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Concise with a main sentence plus structured WHEN TO CALL/WHEN NOT TO CALL sections. Every sentence adds value; no waste.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given one required parameter, no output schema, and simple functionality, the description covers purpose, usage guidelines, and behavioral transparency completely.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema already describes memoryId in detail (UUID, obtain from prior calls, immediate deletion). Description adds no new parameter info beyond the schema, so baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (permanently delete) and the resource (a single memory by ID), distinguishing it from siblings like batchStoreMemory or storeMemory. The 'WHEN TO CALL' and 'WHEN NOT TO CALL' sections further clarify scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly provides when (memory incorrect/dangerously outdated/duplicate) and when not to call (doubt, merely old/low-relevance), with clear alternatives implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch a single memory record by its exact ID. Returns the full record: content, kind, importance, timestamps, and session metadata. Read-only; no side effects.
WHEN TO CALL: When you already have a specific memoryId from a prior retrieveMemories or listMemories result and need its full detail.
WHEN NOT TO CALL: For topic-based search — use retrieveMemories for that. This tool requires an exact ID and does not search by content.
| Name | Required | Description | Default |
|---|---|---|---|
| memoryId | Yes | Exact UUID of the memory to fetch. Obtain from a prior retrieveMemories or listMemories result. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and idempotentHint=true. The description adds 'Read-only; no side effects' and details the return fields (content, kind, importance, etc.), which is helpful but does not discuss error handling or missing ID behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured: first paragraph states the core purpose and return, followed by clear when-to/when-not-to sections. Every sentence adds value with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with one required parameter, full annotations, and no output schema, the description covers purpose, usage, parameter origin, and return content. It is sufficiently complete for an agent to use correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with a description for memoryId. The description adds value by specifying the ID is an 'Exact UUID' and where to obtain it (prior retrieveMemories or listMemories result), beyond the schema's minimal description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Fetch') and the resource ('single memory record by its exact ID'), and distinguishes it from sibling tools by specifying it requires an exact ID and does not search by content.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit 'WHEN TO CALL' and 'WHEN NOT TO CALL' sections, including an alternative tool (retrieveMemories) for topic-based search. This gives clear guidance on appropriate usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Run the full session-end pipeline: auto-summarize the session's ingested events into a durable memory (when enough events exist) and apply a light retention prune of stale memories. Idempotent on the summary memory (upsert by sessionId).
WHEN TO CALL: Once, at the very end of a session, after ingesting session events via ingestSessionEvents. Lets sessionmem generate and store the session summary for you.
WHEN NOT TO CALL: Mid-session, or when you have already written your own summary (use summarizeSessionToMemory instead). On Claude Code this also runs automatically via the installed SessionEnd hook, so calling it explicitly is usually unnecessary there.
Provide sessionId and sourceAdapter. memoryId (optional) pins the summary's id; omit to derive ${sessionId}-summary. config (optional) tunes autoSummarize / minimumEventThreshold / cloud summarization; omit for sensible local-only defaults.
RESPONSE status is one of: 'stored', 'skipped_threshold' (too few events), 'skipped_disabled', 'failed'. warningCodes may carry cloud/local fallback signals.
| Name | Required | Description | Default |
|---|---|---|---|
| config | No | ||
| memoryId | No | ||
| sessionId | Yes | ||
| sourceAdapter | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate idempotent and non-destructive. The description adds detail: idempotent via upsert by sessionId, response statuses ('stored', 'skipped_threshold', etc.), and mentions a 'light retention prune of stale memories'. No contradictions with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with sections for purpose, when to call/not call, parameter guidance, and response format. Each sentence adds value; no redundancy. Entire description fits a few paragraphs without being verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (nested config, multiple response statuses, idempotency, pruning), the description covers the main aspects. It explains the response structure and what triggers skipping. However, it doesn't elaborate on the retention prune mechanism or how events are ingested. Still, it provides sufficient context for an agent to invoke correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema has no property descriptions (0% coverage), but the tool description compensates by explaining the required parameters (sessionId, sourceAdapter) and optional ones (memoryId pins summary id, config tunes behavior). It provides default values and high-level guidance, though some config sub-properties (e.g., anthropicApiKey, redactionEnabled) are not mentioned.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: to run the full session-end pipeline including auto-summarization and retention pruning. It uses specific verbs ('run', 'auto-summarize', 'apply') and identifies the resource ('session's ingested events', 'durable memory'). It also distinguishes itself from the sibling tool 'summarizeSessionToMemory' by mentioning when to use that instead.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly provides 'WHEN TO CALL' (once at session end after ingestSessionEvents) and 'WHEN NOT TO CALL' (mid-session, or if summary already written; on Claude Code it runs automatically). This gives clear context for when to use this tool vs. alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Push raw session events (tool calls, decisions, file edits, user turns) to sessionmem so they can be summarized at session end and counted toward token-savings analytics. Writes immediately, in a single transaction. Re-ingesting the same (sessionId, eventIndex) is a no-op, so retries are safe.
WHEN TO CALL: Periodically during a session (e.g. at task boundaries) to record what happened, OR in one batch shortly before the session ends. This is what powers automatic session-end summarization and sessionmem savings.
WHEN NOT TO CALL: For durable, individually-important facts/decisions — use storeMemory for those. Session events are transient raw material for summarization, not first-class memories.
Each event needs: id (unique), eventIndex (monotonic 0-based order within the session), eventType (e.g. 'tool_use', 'user_message'), payloadJson (a JSON string of the event body).
LIMITS: at most 500 events per call. For more than 500 events, call this tool multiple times in chunks — re-ingestion of already-stored events is safe (idempotent via the (project, session, eventIndex) UNIQUE index), so overlapping chunks never double-count.
| Name | Required | Description | Default |
|---|---|---|---|
| events | Yes | ||
| sessionId | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Despite annotations already indicating idempotency and non-destructiveness, the description adds critical behavioral details: writes immediately in a single transaction, re-ingestion of same (sessionId, eventIndex) is a no-op, and safe retries. This goes beyond annotations and provides full transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with clear sections, uses bullet points effectively, and each sentence adds value. It is concise for the amount of information provided, but slightly lengthy due to detailed guidelines.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description fails to mention return values or error handling. It covers input, behavior, use cases, and limits well, but the lack of output/response information leaves the agent uncertain about success confirmation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema coverage, the description compensates by explaining each event field: id (unique), eventIndex (monotonic 0-based), eventType with examples, payloadJson as JSON string. However, it omits details about 'createdAt' and maxLength constraints, leaving some semantic gaps.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly uses a specific verb 'Push' and resource 'raw session events' to sessionmem, and explains its purpose for summarization and analytics. It distinguishes itself from sibling tools like storeMemory by clarifying that these events are transient raw material, not first-class memories.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to call (periodically during session or batch before end) and when not to call (for durable facts, use storeMemory). Also provides limits (max 500 events per call) and retry safety, guiding the agent on proper usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return every memory stored for the current project, unfiltered and without ranking. Read-only; no side effects.
WHEN TO CALL: When you need a complete inventory of stored memories — to audit what has been saved, detect duplicates, or build a full summary of all known context.
WHEN NOT TO CALL: For normal context loading at session start — use retrieveMemories instead, which ranks by relevance. listMemories returns the entire store unfiltered and can be very large.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and idempotentHint=true; description confirms read-only with no side effects and warns the output can be very large, adding value beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise with a clear main sentence followed by structured usage guidelines (WHEN TO CALL, WHEN NOT TO CALL), front-loading essential information with no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a list tool without output schema, the description covers purpose, usage, and behavioral traits well. Minor gap: does not describe the return format, but given the simplicity and annotations, it is nearly complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description does not explain the 'limit' parameter or its effect, despite the parameter having constraints in the schema. The description should compensate for low schema coverage but fails to do so.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool returns every memory unfiltered, and contrasts with retrieveMemories which ranks by relevance, making the purpose specific and distinguishable from siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly provides WHEN TO CALL (audit, detect duplicates, build full summary) and WHEN NOT TO CALL (session start; suggests retrieveMemories instead), with clear alternative named.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Reset access-pattern counters for all memories in the current project. Sets access_count to 0 and clears last_accessed timestamps without deleting any memories. Useful after large refactors when old access patterns no longer reflect current relevance.
WHEN TO CALL: After major codebase restructuring, project pivots, or when access-boosted rankings no longer reflect current relevance.
WHEN NOT TO CALL: During normal operation — access patterns self-correct as usage shifts.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide destructiveHint=false and idempotentHint=true. The description adds context by detailing the exact state changes (setting counters to 0, clearing timestamps) and affirming no deletions. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Description is clear and well-structured with separate sections for purpose and usage guidelines. Slightly verbose but efficient; could be trimmed without losing meaning.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (no params, no output schema), the description fully covers purpose, behavior, usage contexts, and side effects. Leaves no relevant gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With zero parameters and 100% schema coverage (empty schema), baseline is 4. The description compensates by explaining the action and its effects, adding value beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool resets access-pattern counters for all memories in the current project, specifying it sets access_count to 0 and clears timestamps without deletion. It distinguishes from siblings like forgetMemory or listMemories by focusing on counters rather than storage or retrieval.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly provides 'WHEN TO CALL' and 'WHEN NOT TO CALL' sections, advising use after major refactors and against use during normal operation where self-correction occurs. This gives clear context and alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Semantically search stored memories and return the top matches ranked by a weighted combination of relevance, recency, and importance. Read-only; no side effects.
WHEN TO CALL: (1) At the start of every session — pass the current task or file as the query to pre-load relevant context. (2) Mid-session whenever a new topic, file, or decision area arises that may have prior context. Do NOT call on every user turn.
WHEN NOT TO CALL: If you already retrieved memories for this topic this session. Use getMemory if you have a specific memoryId. Use listMemories only to audit the full store, not for context loading.
Returns up to limit results (default 20). mode='auto' is the standard startup path; mode='on-demand' signals an explicit mid-session lookup. depth='deep' runs a broader semantic sweep at higher latency — use when the topic is unfamiliar. Phrase query as what you need to recall, not what you are about to do.
NOTE: this tool updates access-pattern counters on the memories it returns (used to boost frequently-recalled memories in future ranking), so it is NOT side-effect-free despite being a lookup.
| Name | Required | Description | Default |
|---|---|---|---|
| mode | No | 'auto' for the standard startup context-load path. 'on-demand' for an explicit mid-session retrieval triggered by a specific task or question. | auto |
| depth | No | 'default' for standard semantic search. 'deep' for a broader sweep that surfaces less-similar memories — use when the topic is new or unfamiliar. | default |
| limit | No | Maximum number of memories to return. Integer 1-100, default 20. Increase for broad topic sweeps; keep at default for focused lookups. | |
| query | Yes | Natural-language description of what you need to recall. Phrase as a topic or question (e.g. 'database connection settings', 'auth flow decisions') — not an action ('store info about...'). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses that the tool updates access-pattern counters, going beyond the annotation readOnlyHint: false. However, the initial statement 'Read-only; no side effects' contradicts this later disclosure, slightly undermining transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with sections and front-loaded with the main purpose. It is not overly long, but the initial misleading 'Read-only' statement adds unnecessary confusion.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite lacking an output schema, the description explains that results are ranked by relevance, recency, and importance, and specifies the default limit and constraints. It adequately prepares the agent for what to expect, though explicit output details would be beneficial.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, yet the description adds significant value by explaining when to use each mode ('auto' vs 'on-demand'), depth ('default' vs 'deep'), and how to phrase the query. This guidance is crucial for proper tool usage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it semantically searches memories and returns ranked results. It distinguishes itself from siblings like getMemory and listMemories. However, it initially claims 'Read-only; no side effects' which is contradicted by the note stating it updates access-pattern counters, causing confusion about the tool's exact purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit WHEN TO CALL and WHEN NOT TO CALL sections, including specific use cases like session start and mid-session lookups. Clearly excludes itself from scenarios where getMemory or listMemories are more appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fallback startup-injection for hosts that do not support MCP prompts. Call this once at the very start of a session instead of relying on the automatic sessionmem startup prompt when the host lacks prompt support. Injects the top relevant memories for the current project into the working context. No parameters required.
WHEN TO CALL: Once per session start, before any user task work begins, when the host does not surface MCP prompts automatically. Do not call if the host already surfaces the sessionmem startup prompt — calling both duplicates injected context.
Note: access counts are incremented on retrieval.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. Discloses that access counts are incremented on retrieval and that it is a fallback. However, does not detail criteria for 'top relevant memories' or side effects if called multiple times.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise paragraphs with clear structure, including a 'WHEN TO CALL' note. No redundant sentences.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema and no annotations, description covers purpose, usage, and a behavioral note. Could mention behavior when no relevant memories exist or if called multiple times, but overall adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters, so baseline 4. Description adds context about the injection purpose but no need for parameter details.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states it's a fallback to inject memories when host doesn't support MCP prompts. It specifies the action (injects top relevant memories for current project) and distinguishes from siblings like 'retrieveMemories' or 'fetch_memories' by explaining it's a session start injection.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to call (once per session start, when host lacks prompt support) and when not to call (if host already surfaces sessionmem startup prompt). Provides alternative guidance (rely on automatic prompt) to avoid duplication.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return aggregate statistics for the current project: total stored memory count and total ingested session event count. Read-only; no side effects.
WHEN TO CALL: For diagnostic or monitoring purposes — to confirm memories were stored after a session, check store health, or report usage numbers.
WHEN NOT TO CALL: As part of normal context loading. stats returns counts only, not content; use retrieveMemories to load actual context.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint and idempotentHint. Description adds the specific statistics returned and reaffirms no side effects. Valuable context but not essential beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three well-structured sentences: purpose, when to call, when not to call. No redundancy, every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Complete for a simple parameterless tool with no output schema. Covers purpose, usage guidelines, and differentiates from siblings.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters exist, so description adds no param info. Baseline is 4; description is clear about what the tool does without needing to reference parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description specifies the exact resource and action: returning aggregate statistics (total stored memory count and total ingested session event count) for the current project. It clearly distinguishes from sibling tools like retrieveMemories.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to call (diagnostic/monitoring) and when not to call (not for normal context loading), with an alternative tool suggested.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Persist a single memory unit to the local SQLite store. Accepts decisions, facts, architectural choices, warnings, and session summaries. NOT idempotent — each call creates a new record even with identical content. Writes to disk immediately.
WHEN TO CALL: After any significant decision, discovery, or conclusion that should be available in a future session. Good candidates: technology choices, non-obvious constraints, bug root-causes, architectural decisions, key facts about the codebase.
WHEN NOT TO CALL: For trivial observations, transient state, or content that duplicates what was just retrieved. Do not store entire files or full conversation transcripts.
kind categories: 'decision', 'fact', 'summary', 'warning', 'preference'. Write content to be self-contained — it must be useful without any surrounding conversation context. importance 1-10 (10 = most critical); directly affects retrieval ranking in future sessions.
RESPONSE may include warningCodes: 'session_write_limit_warning' (this session has stored many memories — stop storing trivia and prefer batchStoreMemory) and 'redaction_partial_failure' (a redaction rule errored; the write still succeeded). Treat them as advisory signals, not errors.
| Name | Required | Description | Default |
|---|---|---|---|
| kind | No | Category of this memory. One of: 'decision', 'fact', 'warning', 'preference', 'summary'. These are the only recognized kinds — others are rejected. | |
| content | Yes | The memory text. Must be self-contained and specific — written so it is useful without surrounding conversation context. Avoid vague phrases like 'the user decided to...'. | |
| memoryId | Yes | Caller-supplied unique UUID for this memory (e.g. crypto.randomUUID()). Used for deduplication and for later retrieval by ID via getMemory. | |
| sessionId | Yes | Identifier for the current session. Used to group memories by session for diagnostics. Use a consistent ID within a single session. | |
| importance | Yes | Integer 1-10 indicating criticality (10 = most important). Directly affects ranking in future retrieveMemories calls. Use 8-10 for decisions that must not be forgotten; 3-5 for useful but non-critical facts. | |
| sourceAdapter | Yes | Name of the adapter or host creating this memory (e.g. 'claude-code', 'cursor', 'generic'). Used for provenance tracking. | |
| redactionEnabled | No | If true, PII is stripped from content before storage. Omit to use the project-level redaction setting from config.json. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate non-idempotent and non-destructive behavior. The description adds context: 'NOT idempotent — each call creates a new record even with identical content. Writes to disk immediately.' It also mentions possible warning codes in the response, enhancing transparency beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with sections like 'WHEN TO CALL' and 'WHEN NOT TO CALL'. It is front-loaded with the core purpose, and every sentence provides useful information without redundancy. It is appropriately detailed for a tool with 7 parameters.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers all necessary aspects: purpose, usage guidelines, parameter semantics, behavioral traits, and response warnings. With no output schema, it adequately explains what the response may contain (warning codes). It is complete for an agent to use this tool effectively.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, but the description adds significant value beyond the schema: guidance on writing self-contained content, importance ranking, memory ID generation, session ID consistency, source adapter naming, and redaction behavior. This helps the agent use parameters correctly.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Persist a single memory unit to the local SQLite store.' It specifies what types of content (decisions, facts, etc.) are appropriate, and distinguishes from sibling tools like batchStoreMemory by emphasizing 'single' memory unit.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description includes explicit 'WHEN TO CALL' and 'WHEN NOT TO CALL' sections, providing clear guidance on appropriate usage scenarios and alternatives (e.g., 'stop storing trivia and prefer batchStoreMemory'). It also advises against storing entire files or transcripts.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Store an agent-authored session summary as a durable 'summary' memory in one call. Upserts on memoryId, so calling it again with the same memoryId replaces the prior summary rather than duplicating it.
WHEN TO CALL: At session end when you have already written a concise summary of what was accomplished and want to persist it directly (the simpler alternative to handleSessionEnd's automatic summarization).
WHEN NOT TO CALL: When you want sessionmem to generate the summary from ingested session events — use handleSessionEnd for that. For non-summary facts/decisions use storeMemory.
Provide: memoryId (stable id for this session's summary), sessionId, sourceAdapter, summary (the text), importance (1-10; 7 is typical for summaries).
| Name | Required | Description | Default |
|---|---|---|---|
| summary | Yes | ||
| memoryId | Yes | ||
| sessionId | Yes | ||
| importance | Yes | ||
| sourceAdapter | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare idempotentHint: true and destructiveHint: false. Description adds the crucial upsert behavior (replacing prior summary on same memoryId) and notes it's a simpler alternative, but does not mention authentication or rate limits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with clear sections and headers. Slightly verbose but every sentence adds value. Could be trimmed slightly without losing meaning.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers purpose and parameters well, but does not describe the return value or confirmation. Since there is no output schema, the description should mention what the tool returns (e.g., success/error).
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description explains all five parameters: memoryId (stable id), sessionId, sourceAdapter, summary (the text), importance (1-10, 7 typical). Provides context beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the tool stores an agent-authored session summary as a durable 'summary' memory in one call. Distinguishes from sibling tools like storeMemory and handleSessionEnd by specifying it's for summaries and upserts.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly provides 'WHEN TO CALL' and 'WHEN NOT TO CALL' sections, naming alternatives like handleSessionEnd and storeMemory, giving clear decision criteria.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.
v1.1.2batchStoreMemory10 fields changedInput schema / properties / memories / descriptionPrevious value: -"Array of memory objects to store. Each must include: memoryId (unique UUID), sessionId, sourceAdapter, kind, content (self-contained text), importance (1-10). Minimum 1 item."New value: +"Array of memory objects to store. Each must include: memoryId (unique UUID), sessionId, sourceAdapter, kind, content (self-contained text), importance (1-10). Minimum 1 item, maximum 100.\n\nPer-item results may include `warningCodes` (e.g. 'session_write_limit_warning', 'redaction_partial_failure') — advisory signals, not failures."Input schema / properties / memories / items / properties / content / maxLengthAdded value: +10000Input schema / properties / memories / items / properties / kind / enumAdded value: +[
+ "decision",
+ "fact",
+ "warning",
+ "preference",
+ "summary"
+]Input schema / properties / memories / items / properties / kind / minLengthRemoved value: -1Input schema / properties / memories / items / properties / memoryId / maxLengthAdded value: +200Input schema / properties / memories / items / properties / sessionId / maxLengthAdded value: +200Input schema / properties / memories / items / properties / sourceAdapter / maxLengthAdded value: +100Input schema / properties / memories / items / properties / sourceAdapter / patternAdded value: +"^[^\\n\\r\\x00-\\x08\\x0e-\\x1f\\x7f]*$"Input schema / properties / memories / items / requiredPrevious value: -[
- "memoryId",
- "sessionId",
- "sourceAdapter",
- "kind",
- "content",
- "importance"
-]New value: +[
+ "memoryId",
+ "sessionId",
+ "sourceAdapter",
+ "content",
+ "importance"
+]Input schema / properties / memories / maxItemsAdded value: +100fetch_memoriesforgetMemory1 field changedInput schema / properties / memoryId / maxLengthAdded value: +200getMemory1 field changedInput schema / properties / memoryId / maxLengthAdded value: +200handleSessionEndingestSessionEventslistMemories1 field changedInput schema / properties / limitAdded value: +{
+ "exclusiveMinimum": 0,
+ "maximum": 1000,
+ "type": "integer"
+}retrieveMemories1 field changedInput schema / properties / query / maxLengthAdded value: +1000startup_inject_memoriesstoreMemory9 fields changedInput schema / properties / content / maxLengthAdded value: +10000Input schema / properties / kind / descriptionPrevious value: -"Category of this memory. Recommended values: 'decision', 'fact', 'summary', 'warning', 'architecture'. Any non-empty string is valid."New value: +"Category of this memory. One of: 'decision', 'fact', 'warning', 'preference', 'summary'. These are the only recognized kinds — others are rejected."Input schema / properties / kind / enumAdded value: +[
+ "decision",
+ "fact",
+ "warning",
+ "preference",
+ "summary"
+]Input schema / properties / kind / minLengthRemoved value: -1Input schema / properties / memoryId / maxLengthAdded value: +200Input schema / properties / sessionId / maxLengthAdded value: +200Input schema / properties / sourceAdapter / maxLengthAdded value: +100Input schema / properties / sourceAdapter / patternAdded value: +"^[^\\n\\r\\x00-\\x08\\x0e-\\x1f\\x7f]*$"Input schema / requiredPrevious value: -[
- "memoryId",
- "sessionId",
- "sourceAdapter",
- "kind",
- "content",
- "importance"
-]New value: +[
+ "memoryId",
+ "sessionId",
+ "sourceAdapter",
+ "content",
+ "importance"
+]summarizeSessionToMemoryv1.0.6batchStoreMemoryforgetMemory1 field changedInput schema / properties / memoryId / descriptionAdded value: +"Exact UUID of the memory to permanently delete. Obtain from a prior listMemories or retrieveMemories call. Deletion is immediate and irreversible."getMemory1 field changedInput schema / properties / memoryId / descriptionAdded value: +"Exact UUID of the memory to fetch. Obtain from a prior retrieveMemories or listMemories result."resetAccessCountsretrieveMemories4 fields changedInput schema / properties / depth / descriptionAdded value: +"'default' for standard semantic search. 'deep' for a broader sweep that surfaces less-similar memories — use when the topic is new or unfamiliar."Input schema / properties / limit / descriptionAdded value: +"Maximum number of memories to return. Integer 1-100, default 20. Increase for broad topic sweeps; keep at default for focused lookups."Input schema / properties / mode / descriptionAdded value: +"'auto' for the standard startup context-load path. 'on-demand' for an explicit mid-session retrieval triggered by a specific task or question."Input schema / properties / query / descriptionAdded value: +"Natural-language description of what you need to recall. Phrase as a topic or question (e.g. 'database connection settings', 'auth flow decisions') — not an action ('store info about...')."storeMemory7 fields changedInput schema / properties / content / descriptionAdded value: +"The memory text. Must be self-contained and specific — written so it is useful without surrounding conversation context. Avoid vague phrases like 'the user decided to...'."Input schema / properties / importance / descriptionAdded value: +"Integer 1-10 indicating criticality (10 = most important). Directly affects ranking in future retrieveMemories calls. Use 8-10 for decisions that must not be forgotten; 3-5 for useful but non-critical facts."Input schema / properties / kind / descriptionAdded value: +"Category of this memory. Recommended values: 'decision', 'fact', 'summary', 'warning', 'architecture'. Any non-empty string is valid."Input schema / properties / memoryId / descriptionAdded value: +"Caller-supplied unique UUID for this memory (e.g. crypto.randomUUID()). Used for deduplication and for later retrieval by ID via getMemory."Input schema / properties / redactionEnabled / descriptionAdded value: +"If true, PII is stripped from content before storage. Omit to use the project-level redaction setting from config.json."Input schema / properties / sessionId / descriptionAdded value: +"Identifier for the current session. Used to group memories by session for diagnostics. Use a consistent ID within a single session."Input schema / properties / sourceAdapter / descriptionAdded value: +"Name of the adapter or host creating this memory (e.g. 'claude-code', 'cursor', 'generic'). Used for provenance tracking."v1.0.0forgetMemorygetMemorylistMemoriesretrieveMemoriesstatsstoreMemoryEach tool has a distinct purpose: single/batch store, retrieval by ID/semantic/all, deletion, reset access counts, and stats. No overlap or ambiguity.
All tool names follow a consistent camelCase verb-noun pattern (e.g., storeMemory, retrieveMemories, resetAccessCounts), with no mixing of conventions.
8 tools is well-scoped for a memory management server, covering CRUD operations plus utilities without being too few or excessive.
The tool surface covers create, read (single/semantic/all), delete, and utility functions, but notably lacks an update/modify memory tool, which is a gap for memory correction.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
Portable memory for AI agents: capture once, recall across Claude, Cursor, and any MCP client.
Hosted MCP memory: save sessions/decisions once, search from Claude, Cursor, ChatGPT. EU-hosted FTS.
Persistent memory for AI assistants. Save once; recall from Claude, ChatGPT, or any MCP client.
Persistent memory and cross-session learning for AI coding assistants (hosted remote MCP).
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/catfish-1234/sessionmem'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
