sessionmem is a local MCP server for persistent, searchable project memory across AI coding sessions.
Retrieve memories semantically with ranking by relevance, recency, and importance.
Store individual or batch memories (decisions, facts, warnings, preferences, summaries).
Ingest raw session events for later summarization and token-savings analytics.
Summarize sessions into durable memories and run session-end retention pruning.
List, fetch, delete memories, and reset access-pattern counters.
Get project memory/event counts and inject startup context for hosts lacking prompts.
Project memory between sessions, stored on your machine. Startup context used 85.6% fewer tokens than full session history in the included benchmark.
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 stores decisions, warnings, and project context across sessions. Claude Code hooks capture supported tool events and load relevant memories automatically. Other hosts use its MCP tools and installed instructions; session automation depends on the host. It works with Claude Code, Cursor, Cline, Codex, Windsurf, and other MCP hosts.
By default, everything stays on your machine. You don't need an account or a cloud service. Data only leaves your computer if you enable sharing or cloud summarization.
You need a terminal (Command Prompt, Terminal, or PowerShell) and Node.js, version 20.19+ on the Node 20 line, or 22.13+. Node 22 LTS is recommended. No programming experience is required.
npm install -g sessionmemRun this in your project folder after configuring your AI tool (Claude Code, Cursor, etc.):
sessionmem install
# From a plain terminal, choose the host explicitly when needed:
sessionmem install --adapter claude-code
# Other names: cursor, cline, codex, windsurf, antigravity, qcoder, genericThis initializes the database and, for supported adapters:
Registers sessionmem with your AI tool's MCP host so the host can start it automatically.
Creates ~/.sessionmem/config.json with secret redaction enabled and a 90-day retention window, if the file doesn't already exist.
Adds instructions to the selected host's guidance file, such as ~/.claude/CLAUDE.md for Claude Code or ~/.codex/AGENTS.md for Codex. You can re-run the command without duplicating those instructions.
Restart your editor or agent so it loads the MCP registration. Your host starts
sessionmem run automatically; running it directly starts a stdio server that
waits for MCP messages, so it can appear to hang in a terminal. For an unknown
host (generic), install writes a project-local .mcp.json; if your host uses
another format or location, copy its server entry into that host’s MCP config.
After restarting:
In Claude Code, the installed PostToolUse, SessionEnd, and SessionStart hooks capture supported tool events, summarize them, and load prior memories automatically.
Other MCP hosts use sessionmem's tools and installed instructions. Automatic capture and session lifecycle calls depend on the host or agent. MCP registration alone does not install Claude Code hooks there.
Check that the local database is accessible:
sessionmem pingRelated MCP server: codemem
Most AI coding assistants rely on the current conversation for context. Start a new session and you may need to explain the project's setup, libraries, fixed bugs, and design decisions again.
sessionmem keeps short notes between sessions:
While you work, it captures session events.
At session end, it summarizes decisions, warnings, and useful facts into stored memories.
At the next session start, it loads the most relevant memories within a small token budget.
Claude Code runs these steps through the installed hooks. Other hosts need their agent to call the MCP memory and lifecycle tools; the installed guidance explains how to do that.
Compared with projects such as claude-mem and other cloud or Claude-only memory tools, sessionmem focuses on local storage and support for multiple MCP hosts:
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 | 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 (see benchmarks below) | Varies, often unbounded |
Old/stale memory cleanup | Built-in retention policy automatically prunes old memories (configurable, on by default) | Often no automatic cleanup ("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. Works with no network connection by default. | Usually requires network access to the memory service |
The SQLite file is easy to inspect, back up, or delete, and you can use it across AI tools from different vendors.
These numbers come from npm run benchmark (scripts/benchmark.mjs). It runs the production retrieval and injection code against fixed, synthetic test data without network calls. See docs/benchmark.md for the full report and reproduction steps.
~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 this benchmark, about 1,600 tokens of session history become roughly 230 tokens of decisions, warnings, and facts for the next session.
100% hit-rate: all 10 test queries retrieved the expected memory.
Metric | Result |
Hit-rate (10 curated queries) | 100.0% |
Recall | 100.0% |
Precision | 33.3% |
Each query returns 3 candidate memories, with one scored as the expected match. That gives 33.3% precision even when the expected memory is found every time. The other two candidates may provide context, but are not scored as matches. These results apply to the 10 curated queries; see the report for the embedding model's limits.
The benchmark is deterministic and reproducible:
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 connect each AI tool to sessionmem. Supporting another tool doesn't require changing the memory engine.
The core engine stores memories, ranks their relevance, and selects what fits in the next session's context budget. Every adapter uses the same engine.
The database is a local file. You can back it up, move it, inspect it, or delete it.
See docs/architecture.md for the technical overview.
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 the local version and database reachability. |
| Search memories by semantic query (limit 1–100, default 10). |
| List up to 200 recent memories for the current project; warns when truncated. |
| Show memory details (content capped at 2000 characters; use export for full content). |
| Delete a memory by ID. |
| Export all current-project memories to JSON (default |
| Import up to 1000 valid records from UTF-8 JSON into the current project. Existing IDs are preserved, including with |
| 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. |
| List projects or preview up to 50 recent memories from one project. |
| Preview duplicate memories; |
| Refresh memories with stale embedding versions. |
| Print prior context as Claude Code SessionStart hook JSON. |
| Read a Claude Code PostToolUse JSON payload from stdin and capture supported tool events. |
| Summarize ingested events and apply retention pruning; reads the hook session ID from stdin. |
Use sessionmem --help or sessionmem <command> --help for options, and
sessionmem --version for the installed version. Destructive commands require
--force, --apply, or --purge as shown above. team disable preserves
teammate memories unless --remove-team-memories is passed.
The default database is ~/.sessionmem/memories.db. Set SESSIONMEM_DB_PATH
to use another file; its parent directories are created automatically and the
default directory is not created by database commands. Server logs are written
to logs/mcp.log beside the selected database (disabled for :memory:). Config remains at
~/.sessionmem/config.json. uninstall --purge deletes the selected database.
Quote paths containing spaces (for example "C:\Users\Ada Lovelace\memory.db"
on Windows). In JSON config files, use forward slashes or escaped backslashes
for Windows paths. Imports accept CRLF and a UTF-8 BOM; convert other encodings to UTF-8.
SESSIONMEM_PROJECT_ID pins the project bucket (useful when moving a repository);
otherwise it is derived from the repository root or working directory.
SESSIONMEM_ADAPTER selects the install/uninstall host unless --adapter is set.
SESSIONMEM_DEBUG=1 enables ingest-hook diagnostics on stderr.
Storage, retrieval, and summarization run locally by default. There is no account, telemetry, or hosted memory service. Settings live in ~/.sessionmem/config.json.
Before saving memory content, sessionmem replaces common secret patterns 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=...)
Redaction is on by default. To scan and clean up older memories:
sessionmem redact-scan # see what would be redacted
sessionmem redact-scan --apply # actually redact in placeFull details: docs/privacy-and-retention.md.
Old decisions and duplicate facts can accumulate in a memory store, causing the assistant to use outdated information. This is sometimes called "memory rot."
sessionmem handles it through retention, ranking, and sync rules:
Retention pruning: memories older than a configurable window (90 days by default) are eligible for deletion. A lightweight check runs at session end. You can also run it manually:
sessionmem retention prune # dry run - shows what *would* be deleted
sessionmem retention prune --force # actually deletesImportance-weighted ranking: retrieval ranks memories by semantic relevance, recency, and importance. Older, less important notes rank lower even before they are pruned.
Token-budgeted injection: only the highest-ranked memories are loaded, trimmed to a small token budget (see benchmarks). The context stays within that budget as the store grows.
Conflict resolution in team mode: merging teammate memories uses last-write-wins by id to avoid stale duplicates and keeps the higher importance score so a warning isn't downgraded.
The benchmark above found every expected memory across its 10 queries (100% hit-rate and recall) with ranking and trimming enabled.
Export your memories before pruning if you want to keep a copy:
sessionmem exportTo share decisions and warnings across your team's AI assistants, point sessionmem at a folder everyone can read and write, such as a network drive or synced directory:
sessionmem team enable <shared-path>
sessionmem syncTeam mode is off by default. Nothing is shared until you enable it.
Memories are shared as files in that folder; no server is needed.
Teammate memories appear with an author: prefix identifying their source.
Redaction runs on every pulled memory using your redaction policy.
Full details, including the trust model: docs/team-mode.md.
By default, session summaries are created locally, with no API calls.
To use Claude's API for higher-quality summaries, set allowCloudSummarization=true and provide an ANTHROPIC_API_KEY. If cloud summarization fails after retries, sessionmem uses local summarization. Failures are recorded for diagnosis; see the configuration guide below.
Details: docs/cloud-summarization.md.
sessionmem works with any MCP-compatible host, including:
Claude Code
Cursor
Codex
Cline
Windsurf
Antigravity
QCoder
Other tools that implement the Model Context Protocol can connect too.
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.
For install failures, adapter issues, missing session data, or better-sqlite3 native-build problems, see docs/troubleshooting.md.
To refresh the installation and check for stored session data:
sessionmem install # idempotent; Claude Code also installs 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.
To check database access and memory counts:
sessionmem ping # can the local database be opened?
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. Use --adapter cursor, --adapter cline, or --adapter windsurf when auto-detection cannot identify your host.
How do I give Claude Code persistent memory?
Use the same install steps above. sessionmem also ships as a Claude Code plugin (the .claude-plugin directory in the repo) for Claude Code's native plugin system.
Is there a local MCP memory server that works offline with no API key?
Yes. sessionmem stores memories in a single SQLite file at ~/.sessionmem/memories.db and works offline by default. Sharing and cloud summarization are optional and off by default.
How is sessionmem different from claude-mem? sessionmem works with Claude Code, Cursor, Cline, Codex, Windsurf, Antigravity, QCoder, and other MCP hosts. It redacts secrets (API keys, tokens, JWTs) by default, prunes old memories automatically, and includes reproducible benchmarks.
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.
See the security policy for supported versions, private vulnerability reporting through GitHub security advisories, and response expectations.
Issues and pull requests are welcome. The codebase is TypeScript, tested with Vitest, and linted with ESLint:
npm ci
npm run build
npm run typecheck
npm test
npm run lintMCP config for local development: Clone the repository, build it, copy
.mcp.json.example to .mcp.json, and replace the example path with the absolute
path to your checkout’s dist/cli/index.js. This runs your local build.
sessionmem install registers the sessionmem executable on PATH instead. 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.
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.0forgetMemorygetMemorylistMemoriesretrieveMemoriesstatsstoreMemoryScored across 13 tools
retrieveMemories, fetch_memories, and startup_inject_memories all perform relevance-based context loading with only host-capability differences, which can cause misselection. summarizeSessionToMemory also overlaps somewhat with handleSessionEnd, though the core CRUD tools are otherwise clearly distinct.
Most core tools follow a consistent verb_noun camelCase pattern like retrieveMemories, storeMemory, and forgetMemory. However, fetch_memories and startup_inject_memories switch to snake_case, and stats is a bare noun, making the overall convention mixed but still readable.
13 tools is a reasonable size for a memory-management server covering basic CRUD, batch operations, statistics, and session-end processing. The count is slightly higher than necessary due to fallback retrieval/injection tools that duplicate or approximate existing functionality.
The core memory lifecycle is well covered: create, retrieve, search, list, get, delete, batch store, stats, and session summarization. Minor gaps remain, such as no general updateMemory tool and a reference to importMemories that is not actually present in the tool set, but these are workable via delete-and-recreate or existing batch storage.
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.
Give your AI agent persistent, governed memory for every project. At task start it recalls the approved decisions, conventions, risks and architecture (semantic search, ranked by importance); at close it proposes what was learned as typed memories that you review and approve — governance, not a notes dump. Agents propose, humans govern: edits go back to pending and deletion is human-only by design. Connect Claude Code, Cursor, Claude Desktop or any MCP client in two minutes with just your API key — hosted (nothing to install) or locally via `uvx solucortex-mcp`. Built by SoluAI and dogfooded daily: SoluCortex is developed using its own living memory.
Persistent memory and cross-session learning for AI coding assistants (hosted remote MCP).
