Persistent memory for Claude Code. Automatically indexes every conversation and provides production-grade hybrid search (BM25 + vectors + reranker) via MCP tools. 100% local, zero config, zero API keys, zero invoice.
Claude Code forgets everything between sessions - and knows nothing about your other projects. Melchizedek fixes both.
It runs silently in the background - indexing your conversations as you work - then gives Claude the ability to search across your entire history, across all projects: past debugging sessions, architectural decisions, error solutions, code patterns.
No cloud. No API keys. No config. Plug and ask.
Related MCP server: SharedMemory MCP Server
~/.claude/projects/**/*.jsonl (your conversation transcripts - read-only)
|
v
SessionEnd hook (auto-triggers after each session)
|
v
+-----------------+
| Indexer | Parse JSONL -> chunk pairs -> SHA-256 dedup
| (better-sqlite3)| FTS5 tokenize -> vector embed (optional)
+-----------------+
|
v
~/.melchizedek/memory.db (single SQLite file, WAL mode)
|
v
+-----------------+
| MCP Server | 16 search & management tools
| (stdio) | Hybrid: BM25 + vectors + RRF + reranker
+-----------------+
|
v
Claude Code (searches your history via MCP)Every layer is optional. The plugin works with BM25 alone and gets better as more components are available.
Level | Component | What it adds | Dependency |
1 | BM25 (FTS5) | Keyword search with stemming | None (always active) |
2 | Dual vectors (sqlite-vec) | Semantic search - text (MiniLM 384d) + code (Jina 768d) |
|
3 | RRF fusion | Merges BM25 + text vectors + code vectors via Reciprocal Rank Fusion | Vectors enabled |
4 | Reranker | Cross-encoder re-scoring of top results | Transformers.js or node-llama-cpp (optional) |
Measured with npm run bench - 100 sessions, 1 000 chunks, on a single SQLite file.
Metric | Result | Target |
Indexation (100 sessions) | ~80 ms | < 10 s |
BM25 search (mean) | ~0.2 ms | < 50 ms |
DB size (100 sessions) | ~1.4 MB | < 30 MB |
Tokens per search | ~125 | < 2 000 |
npm install -g melchizedekAdd the MCP server to Claude Code:
claude mcp add --scope user melchizedek -- melchizedek-serverclaude mcp add --scope user melchizedek -- npx melchizedek-servergit clone https://github.com/louis49/melchizedek.git
cd melchizedek && npm install && npm run build
claude --mcp-config .mcp.jsonPlugin review pending. In the meantime, use npm or npx install above.
claude plugin install melchizedek # not yet availableThe MCP server provides search tools, but hooks trigger automatic indexing. Without hooks, you'd need to manually index sessions.
For marketplace installs, hooks are configured automatically. For npm/npx/source installs, add hooks to ~/.claude/settings.json.
See docs/installation.md for the full JSON configuration, hook reference, and troubleshooting.
After setup, restart Claude Code. Indexing starts automatically.
Tool | Description |
| Search indexed conversations. Returns compact snippets. Current project boosted. Supports |
| Get a chunk with surrounding context (adjacent chunks in the same session). |
| Retrieve full content of chunks by IDs. |
Progressive retrieval pattern - search returns ~50 tokens/result, context ~200-300, full ~500-1000. Start with m9k_search, drill down only when needed. 4x token savings vs loading everything.
Context-aware ranking - results from your current project (×1.5) and current session (×1.2) are automatically promoted. Cross-project results remain visible.
Tool | Description |
| Find past conversations that touched a specific file. |
| Find past solutions for an error message. |
| Find past approaches to similar tasks. Prioritizes rich metadata. |
Tool | Description |
| Manually save a memory note for future recall. |
| List all indexed sessions, optionally filtered by project. |
| Show memory index info: corpus size, search pipeline, embedding worker, usage metrics. |
| View or update plugin configuration. |
| Permanently remove a chunk from the index. |
| Delete a session from the index. |
| Exclude a project from indexing. Future sessions won't be indexed, existing ones optionally purged. |
| Re-enable indexing for a previously ignored project. Purged data is not restored. |
| Restart the MCP server to load fresh code after |
Tool | Description |
| Phantom tool. Its description teaches Claude the retrieval pattern and available tools. |
Zero config by default. Everything is tunable via m9k_config or environment variables.
Setting | Default | Env var |
Database path |
|
|
Daemon mode | enabled |
|
Log level |
|
|
Embeddings enabled |
|
|
Reranker enabled |
|
|
See docs/configuration.md for the full settings reference (20+ options, env vars, config file examples).
Melchizedek works out of the box with BM25 keyword search. Text embeddings (MiniLM) download automatically on first use for semantic search.
For GPU-accelerated code embeddings (Ollama), cross-encoder reranking (GGUF models), platform-specific setup guides, and the full model reference, see Enhanced Search Setup.
Melchizedek | |||||
|
|
|
| ||
Philosophy | Search engine - indexes everything, you search | Search engine - scans JSONL on demand | Notebook - AI compresses & saves | Search engine | Notebook - AI decides what to store |
Indexes raw conversations | Yes (JSONL transcripts) | Yes (direct JSONL read, no persistent index) | Compressed summaries | Yes (JSONL) | No (manual |
Retroactive on install | Yes (backfills all history) | Yes (reads existing files) | No | Yes | No (empty at start) |
Search | BM25 + vectors + RRF + reranker | TF-IDF + fuzzy matching | FTS5 + ChromaDB | Vectors only | BM25 + vectors |
Progressive retrieval | 3 layers (search/context/full) | No | No | No | No |
100% offline | Yes | Yes | No (needs API for compression) | Yes | Yes |
Single-file storage | SQLite | None (reads raw JSONL) | SQLite + ChromaDB | SQLite | SQLite-vec |
Zero config | Yes | Yes | Yes | Yes | Yes |
MCP tools | 16 | 10 | 4 | 2 | 12 |
License | MIT | MIT | AGPL-3.0 | MIT | Apache-2.0 |
Dual embedding (text + code) | Yes (MiniLM + Jina Code) | No | No | No | No |
Configurable models | Yes (Transformers.js or Ollama) | No | No (Chroma internal) | No (hardcoded) | Yes (ONNX, Ollama, OpenAI, Cloudflare) |
Reranker | Cross-encoder (ONNX, GGUF, or HTTP) | No | No | No | Quality scorer (not search reranker) |
Privacy | All local, | All local | Sends data to Anthropic API | All local | All local |
Multi-instance | Singleton daemon - N Claude windows share 1 process (Unix socket / Windows named pipe, local fallback) | N separate processes | Shared HTTP worker (:37777) | N separate processes | Shared HTTP server |
This project stands on the shoulders of others. Key ideas borrowed from:
Project | What we took | |
RRF hybrid fusion, SHA-256 dedup, auto-fuzzy fallback | ||
Specialized MCP tools (file_history, error_solutions) |
| |
PreCompact hook (archive before |
Session boost inactive - Claude Code currently sends an empty session_id in the SessionStart hook stdin payload, preventing the ×1.2 session boost from working. The ×1.5 project boost is unaffected and provides the primary context-aware ranking. Related upstream issues: #13668 (empty transcript_path), #9188 (stale session_id). Melchizedek's session boost code is tested and ready, and will activate automatically when the upstream fix lands.
Zero telemetry. No tracking, no analytics, no network calls (except optional lazy model download).
Read-only on transcripts. Never writes to ~/.claude/projects/. All data in ~/.melchizedek/.
<private> tag support. Content between <private>...</private> is replaced with [REDACTED] before indexing.
Local-only. Your conversations never leave your machine.
Node.js >= 20
Claude Code >= 2.0
macOS, Linux, or Windows
MIT
"Without father, without mother, without genealogy, having neither beginning of days nor end of life."
Hebrews 7:3
Built by @louis49
View or update plugin configuration. Changes are saved to ~/.melchizedek/config.json and take effect on next server restart. Without arguments, returns current config.
| Name | Required | Description | Default |
|---|---|---|---|
| key | No | Config key to update (e.g. 'rerankerEnabled') | |
| value | No | New value (JSON-encoded: 'false', '15', '"node-llama-cpp"') |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond annotations, the description reveals that changes are saved to a persistent file and only take effect after a restart. This provides critical behavioral context that annotations (like destructiveHint=false) do not cover, fully informing the agent of side effects.
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 efficient sentences: the first states the action, the second details the persistence. No unnecessary words, and the most important information is front-loaded.
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 core functionality and persistence but omits details like error handling or validation (e.g., invalid keys). For a tool with only two optional parameters, this is adequate but not exhaustive.
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 100% schema coverage, the schema already describes parameters. The description adds value by clarifying that values are JSON-encoded (e.g., 'false', '15'), which is not evident from the schema alone, slightly aiding correct 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 the tool's dual purpose: viewing or updating plugin configuration. It specifies the exact file path and effect timing, distinguishing it from sibling tools that handle other aspects like context or sessions.
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 explicitly says 'Without arguments, returns current config,' guiding the agent on when to read vs. write. However, it does not mention alternatives or when not to use this tool, leaving room for ambiguity with sibling config-related tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a chunk with surrounding context (adjacent chunks in the same session). Use after m9k_search to understand the conversation flow.
| Name | Required | Description | Default |
|---|---|---|---|
| chunkId | Yes | The chunk ID to get context for | |
| window | No | Number of chunks before/after to include |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate read-only, non-destructive, and idempotent behavior. Description adds useful context about returning adjacent chunks in the same session, which clarifies the tool's scope 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?
Two sentences with zero waste: first sentence states purpose, second gives usage context. Every word is necessary.
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 read tool with two parameters and explicit annotations, the description adequately defines purpose and usage. Minor gap: doesn't describe return structure, but acceptable given no output schema.
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 100% (both chunkId and window have descriptions). The description does not add extra parameter details beyond the schema, meeting the baseline of 3.
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 the verb 'Get' and the resource 'a chunk with surrounding context (adjacent chunks in the same session)', distinguishing it from sibling tools like m9k_search and m9k_full.
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 suggests using after m9k_search to understand conversation flow, providing clear context but no explicit when-not-to-use or alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete a session from the index. Removes all chunks and search data. Does NOT delete the source JSONL file.
| Name | Required | Description | Default |
|---|---|---|---|
| sessionId | Yes | The session ID to delete |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark destructiveHint=true and idempotentHint=true. The description adds specific behavioral context: removes chunks and search data, preserves the JSONL file. This provides value beyond annotations, though it could mention side effects like cascade deletions.
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-sentence description that is efficient and front-loaded. First sentence states main action, second adds critical exception. 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?
For a simple delete operation with one required parameter and no output schema, the description covers the action, what is removed, and what is not removed. Lacks information about return value or error conditions, but acceptable given context.
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?
Only one parameter (sessionId) with schema description 'The session ID to delete'. Schema coverage is 100%, and the description adds no additional meaning beyond the schema. 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?
States it deletes a session from the index, removing chunks and search data, and explicitly notes it does not delete the source file. Verb 'delete' clearly indicates the action, and resource 'session' is specific. Distinguishes from siblings by clarifying the scope of deletion and what is preserved.
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 implies when to use (to remove session data while keeping the source file) but does not explicitly compare with alternative tools like m9k_forget or m9k_restart. No guidance on when not to use or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Find past solutions for an error message. Returns error context + how it was resolved.
| Name | Required | Description | Default |
|---|---|---|---|
| errorMessage | Yes | The error message or keywords from the error | |
| limit | No | Max results | |
| source | No | Filter by source type. Default: all sources. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true. The description adds that the tool returns 'error context + how it was resolved', which is consistent but does not disclose additional behavioral traits like pagination or rate limits. 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?
Single sentence, zero wasted words, and front-loaded with the core purpose. Every word earns its place.
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 has 3 parameters, no output schema, and rich annotations, the description covers the main purpose and return types. The schema handles parameter details. It could mention source options but is adequate for a simple lookup tool.
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 100%, so baseline is 3. The description does not add any meaning beyond the schema; it does not elaborate on parameter usage or format. Schema already defines all parameters with descriptions and defaults.
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 finds past solutions for an error message and returns error context plus how it was resolved. This is a specific verb-resource combination that distinguishes it from sibling tools like m9k_search or m9k_similar_work.
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?
No guidance on when to use this tool versus alternatives (e.g., m9k_search, m9k_context). The description only implies usage when an error message is present but doesn't provide exclusions or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Find past conversations that touched a specific file. Searches metadata (tool_use file_path) and text content.
| Name | Required | Description | Default |
|---|---|---|---|
| filePath | Yes | File path to search for (e.g. "src/server.ts") | |
| limit | No | Max results | |
| source | No | Filter by source type. Default: all sources. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate read-only, non-destructive, and idempotent behavior. The description adds that searches cover metadata (tool_use file_path) and text content, providing some behavioral context. No contradictions noted.
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 two sentences long with no redundant information. It effectively communicates the core functionality without unnecessary detail.
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?
While annotations and schema are rich, the description lacks detail about output format, pagination, or expected results. For a tool without output schema, more contextual information 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?
Input schema has 100% description coverage for all parameters. The description does not add parameter-specific meaning beyond what the schema already provides, 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 that the tool finds past conversations referencing a specific file by searching metadata and text content. It specifies the resource (file) and action (find), but does not explicitly distinguish it from sibling tools like m9k_search.
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?
No guidance is provided on when to use this tool versus alternatives such as m9k_search or m9k_context. The description does not mention context, prerequisites, or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Permanently remove a specific chunk from the memory index. Does NOT delete the source JSONL. Use m9k_search() first to find the chunk ID to forget.
| Name | Required | Description | Default |
|---|---|---|---|
| chunkId | Yes | Chunk ID to permanently delete from the index |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already set destructiveHint=true, so the description adds value by clarifying the deletion is permanent and that the source JSONL remains. 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?
Two sentences: first states core action, second provides caveat and preparatory step. No extraneous information, efficiently front-loaded.
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 (1 param, no output schema), the description covers the essential actions, constraints, and preparatory step. Could optionally mention return value or confirmation, but not required.
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 has one parameter with a complete description. The description does not add significant semantics beyond 'chunk ID to permanently delete,' but the context of using m9k_search is helpful. Baseline 3 since schema coverage is 100%.
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 states 'Permanently remove a specific chunk from the memory index' which clearly identifies the action (remove) and resource (chunk). It distinguishes from sibling tool m9k_search by implying the chunk ID is obtained via search.
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 use (after m9k_search) and a key exclusion: does NOT delete the source JSONL. This provides clear guidance on when to use vs. not use, with direct reference to an alternative sibling.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retrieve full content of chunks by IDs. Use after m9k_search to get complete context.
| Name | Required | Description | Default |
|---|---|---|---|
| chunkIds | Yes | Chunk IDs to retrieve in full |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover read-only, non-destructive, idempotent behavior. Description adds 'get complete context' but no new behavioral insights. No contradictions.
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 sentences with no wasted words. Front-loaded with the core action, followed by usage hint. Highly efficient.
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?
Adequate for a simple read tool with one parameter and no output schema. Missing return format details, but not critical given simplicity and annotations.
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 100% and describes chunkIds as 'Chunk IDs to retrieve in full'. Tool description adds no extra parameter meaning 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 action ('Retrieve full content') and the resource ('chunks by IDs'), and distinguishes from sibling tool m9k_search by specifying usage after search.
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 says 'Use after m9k_search to get complete context', providing clear context for when to use. Does not explicitly exclude alternatives, but the guidance is sufficient.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Exclude a project from indexing. Future sessions won't be indexed. Optionally purge existing indexed sessions for this project.
| Name | Required | Description | Default |
|---|---|---|---|
| project | Yes | Project path to ignore (e.g. /Users/foo/my-secret-repo) | |
| purge | No | Also delete already-indexed sessions for this project |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses destructiveHint=true with explanation of persistent effect (future sessions not indexed) and optional purge deleting existing sessions. 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?
Two sentences, no wasted words, front-loaded with primary action, then optional behavior.
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?
Completely describes tool's purpose, persistent effect, and optional deletion. No output schema needed for this simple configuration tool.
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 parameters fully; description adds practical example (project path) and clarifies the purge option's effect, enhancing usability beyond schema alone.
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 'exclude a project from indexing' with verb and resource. Distinguishes from sibling m9k_unignore_project by opposite 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?
Implies usage for ignoring a project but does not explicitly state when to use vs alternatives. However, sibling name suggests opposite usage, so context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Show memory index information: corpus size, search pipeline status, usage metrics, embedding worker state.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate read-only, non-destructive, idempotent behavior. The description adds specific metrics (corpus size, pipeline status, usage metrics, worker state) beyond annotations, providing useful context about what the tool reveals.
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?
Single sentence, front-loaded with key info, 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 parameterless info tool, the description adequately specifies the output content. Lacks details on output format or interpretability, but sufficient for basic understanding.
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 is 4. The description doesn't need to add parameter info. It correctly clarifies that no input is needed.
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 shows memory index information and lists specific components (corpus size, search pipeline status, usage metrics, embedding worker state). Distinguishes itself from sibling tools like m9k_context or m9k_errors.
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?
Does not provide explicit guidance on when to use this tool vs alternatives like m9k_config or m9k_errors. Usage is implied for informational queries, but lacks when-not-to-use or comparative context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Restart the MCP server. Use after npm run build to load fresh code. The server disconnects; next MCP call auto-reconnects with the new build.
| Name | Required | Description | Default |
|---|---|---|---|
| force | No | Use SIGKILL instead of SIGTERM (for stuck processes) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds behavioral info beyond annotations: server disconnects and auto-reconnects. Annotations already cover safety (idempotent, non-destructive). No contradiction.
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 sentences, front-loaded with purpose, no wasted words. Every sentence provides essential information.
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 optional parameter and no output schema, the description covers the restart process, disconnection, and reconnection. No missing information.
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% for the single optional parameter 'force', which is already described in the schema. The tool description adds no extra parameter info, so baseline 3.
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 'Restart the MCP server' with specific verb and resource. It further specifies the context ('after npm run build') and behavior, differentiating it 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?
The description explicitly states when to use: 'Use after npm run build to load fresh code.' It implies the timing but does not explicitly exclude other uses or mention alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Manually save a memory note for future recall. Use for important decisions, patterns, or context.
| Name | Required | Description | Default |
|---|---|---|---|
| content | Yes | The memory content to save | |
| tags | No | Optional tags for categorization |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide idempotentHint=true and destructiveHint=false, so the description adds marginal behavioral context. It correctly conveys a write operation but does not elaborate on effects beyond what annotations provide.
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 two concise sentences with zero wasted words. First sentence states the action and purpose, second provides usage guidance. Ideal length.
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 save tool with two parameters (one required) and no output schema, the description covers the essentials: what it does and when to use it. It is sufficiently complete given the tool's simplicity and sibling context.
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 100% description coverage for both parameters. The description adds no extra semantic details about parameters beyond stating the tool saves memory notes, which aligns with the 'content' parameter.
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 ('Manually save'), the resource ('memory note'), and the usage context ('for future recall', 'important decisions, patterns, or context'). It is specific and distinguishes this tool from siblings like m9k_forget or m9k_search.
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 provides when to use ('Use for important decisions, patterns, or context') but does not mention when not to use or explicitly name alternative tools. Guidance is implied but lacks explicit exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search indexed past conversations. Returns compact results with snippets. Results from the current project and session are boosted by default. Use m9k_context or m9k_full to drill down.
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | Search query (keywords or natural language) | |
| project | No | Filter by project path. Omit for cross-project search. | |
| limit | No | Max results | |
| since | No | ISO-8601 date. Only results after this date. | |
| until | No | ISO-8601 date. Only results before this date (exclusive). | |
| order | No | Sort order: score (relevance), date_asc (oldest first), date_desc (newest first) | score |
| source | No | Filter by source type. Default: all sources. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Description adds value beyond annotations by revealing result format (compact snippets) and boosting behavior. Consistent with readOnlyHint=true 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 sentences with clear front-loading of purpose, 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?
Given 7 parameters, no output schema, and strong annotations, the description provides sufficient context for appropriate tool selection and 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 parameters are already well-defined. Description adds no parameter-level detail beyond the boosting context, so baseline 3 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?
Clearly states it searches indexed past conversations and returns compact results with snippets. Differentiates from siblings by mentioning drilling down with m9k_context or m9k_full.
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 guidance: boosting of current project/session, and alternatives for deeper investigation (m9k_context, m9k_full).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all indexed sessions, optionally filtered by project.
| Name | Required | Description | Default |
|---|---|---|---|
| project | No | Filter by project path | |
| limit | No | Max sessions | |
| source | No | Filter by source type. Default: all sources. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly, destructive, idempotent hints. Description adds 'optionally filtered by project' which is redundant with schema. No additional behavioral traits disclosed 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?
One sentence, 8 words, no fluff. Perfectly concise for a simple list tool.
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, the description covers the core purpose and optional filters. Could mention limit and source, but those are already in schema. Lacks mention of return format or pagination, but not critical.
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 100%, so each parameter is already described. The tool description adds nothing beyond the schema, meeting the baseline but not exceeding it.
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 the action (list) and resource (indexed sessions) with optional filter by project. It differentiates from siblings like m9k_delete_session and m9k_search, but does not explicitly contrast them.
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?
No guidance on when to use this tool versus siblings like m9k_search or m9k_save. The description implies a simple list operation but does not provide context for selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Find past work similar to what you're about to do. Use at the start of a complex task to see previous approaches. Unlike m9k_search, this prioritizes chunks with rich metadata (multiple tools used, multiple files touched).
| Name | Required | Description | Default |
|---|---|---|---|
| description | Yes | Description of the current task | |
| limit | No | ||
| source | No | Filter by source type. Default: all sources. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare the tool as read-only, idempotent, and non-destructive. The description adds valuable behavioral context: it prioritizes chunks with rich metadata (multiple tools used, multiple files touched). No contradictions.
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 tightly constructed sentences, each earning its place: purpose, usage timing, and sibling differentiation. No redundant or extraneous content.
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 tool with 3 parameters and no output schema, the description covers purpose, usage, and differentiation. It is slightly lacking in specifying return format or behavior, but overall sufficiently complete for effective use.
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 67% (2 of 3 parameters described). The tool description does not add any additional parameter semantics beyond what the schema provides. It is adequate but not enhanced.
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 function: 'Find past work similar to what you're about to do.' It uses a specific verb ('find') and resource ('past work'), and distinguishes itself from the sibling m9k_search by noting it prioritizes chunks with rich metadata.
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 guidance: 'Use at the start of a complex task to see previous approaches.' It also contrasts with m9k_search, clarifying when not to use the alternative.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Remove a project from the ignore list. Future sessions will be indexed again. Previously purged sessions are NOT restored (requires backfill re-indexation).
| Name | Required | Description | Default |
|---|---|---|---|
| project | Yes | Project path to unignore |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate idempotent and non-destructive nature, but the description adds key behavioral context: the effect on future sessions versus previously purged sessions. This goes beyond what annotations provide.
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 sentences deliver the core purpose, the action, and a critical limitation without any fluff. Every sentence is necessary and front-loaded.
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 and no output schema, the description covers purpose, effect, and limitation. It is complete and leaves no ambiguity about what the tool does or its boundaries.
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% and the single parameter 'project' is clearly described as 'Project path to unignore'. The description does not add new meaning beyond the schema, earning a baseline score of 3.
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 verb 'Remove' and the resource 'ignore list', directly distinguishing it from the sibling tool 'm9k_ignore_project' which performs the opposite action.
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 provides clear usage context (unignoring a project) and an important caveat that previously purged sessions are not restored. While it does not explicitly name alternatives, the purpose alone differentiates it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
melchizedek v1.0.2 — Persistent memory for Claude Code with hybrid search (BM25 + dual embeddings) + reranking.
Corpus: empty (no sessions indexed yet).
Available tools (16):
m9k_search: Find past conversations (BM25 + text vectors + code vectors, fused via RRF)
m9k_context: Get a chunk with surrounding conversation context
m9k_full: Get complete chunk content by IDs
m9k_sessions: Browse indexed sessions
m9k_file_history: Find conversations that touched a specific file
m9k_errors: Find past solutions for error messages
m9k_save: Store important notes for future recall
m9k_similar_work: Find past approaches to similar tasks (bonus for complex work)
m9k_forget: Permanently remove a chunk from memory
m9k_info: Memory index information, corpus size, search pipeline status, usage metrics, embedding worker state
m9k_config: View or update plugin configuration
m9k_delete_session: Remove a session from the index
m9k_ignore_project: Exclude a project from indexing (optionally purge existing data)
m9k_unignore_project: Re-enable indexing for a previously ignored project
m9k_restart: Restart the MCP server to load fresh code after rebuild
RETRIEVAL PATTERN (use this order):
m9k_search(query) → compact results, current project and session boosted (use order="date_asc" to find first occurrence)
m9k_context(chunkId) → surrounding conversation
m9k_full([chunkIds]) → complete content if needed
SPECIALIZED SEARCH:
m9k_file_history(filePath) → before modifying any file
m9k_errors(errorMessage) → when you hit an error
m9k_similar_work(description) → at the start of a complex task
MANAGE:
m9k_info() → check corpus size, search pipeline, usage metrics
m9k_config() → view or change plugin configuration
m9k_delete_session(sessionId) → remove a session from the index
m9k_ignore_project(project) → exclude a project from indexing
m9k_unignore_project(project) → re-enable indexing for a project
m9k_restart() → restart server after npm run build
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations (readOnlyHint, idempotentHint, non-destructive) provide basic safety info, but the description does not explain what the tool actually does when called (e.g., returns a text guide). Without an output schema, the description should clarify the behavioral outcome, but it focuses on system capabilities instead.
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 excessively long, including version info, corpus status, and full listings of sibling tools. While this might be useful as a reference, it is not concise for a tool definition. Key information about the tool itself is buried in a wall of text.
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 has no parameters, no output schema, and is a guide, the description should clearly state what invoking it returns or achieves. It omits this critical information, instead presenting a system overview. The description is incomplete for an agent to understand the tool's purpose.
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 the description has no need to add parameter semantics. The input schema fully covers this. Baseline for zero parameters is 4, and the description does not mislead or omit any needed param info.
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 tool name '__USAGE_GUIDE' suggests it provides guidance, but the description reads as a system overview rather than explicitly stating what this tool does when invoked. It lacks a clear verb+resource statement like 'Returns a usage guide for the melchizedek memory system.' The description is more about the system than the tool itself.
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?
No guidance on when to use this tool versus alternatives. It does not explain scenarios where invoking the usage guide is appropriate, nor does it contrast with sibling tools. The description lists sibling tools but provides no selection criteria or context for using this specific tool.
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.
v0.1.1__USAGE_GUIDEm9k_configm9k_contextm9k_delete_sessionm9k_errorsm9k_file_historym9k_forgetm9k_fullm9k_ignore_projectm9k_infom9k_restartm9k_savem9k_searchm9k_sessionsm9k_similar_workm9k_unignore_projectEach tool has a clearly distinct purpose: search, context retrieval, session management, configuration, etc. Even overlapping functions like m9k_search and m9k_similar_work are differentiated by description and use case. No two tools are easily confused.
Most tools follow the consistent m9k_verb_noun pattern (e.g., m9k_search, m9k_save). However, the tool __USAGE_GUIDE breaks this pattern with double underscores and all caps, which is a minor deviation from an otherwise uniform naming convention.
With 16 tools, the server is well-scoped for its purpose as a persistent memory system. Each tool covers a distinct function (search, context, save, delete, config, etc.) without being overwhelming or too sparse.
The tool surface covers the main CRUD-like operations (save, retrieve, forget, session delete) and specialized search (file history, errors, similar work). Minor gaps include no way to update existing chunks or list all chunk IDs for a session, but these are not critical for the domain.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
Private persistent memory for Claude, ChatGPT & Gemini via MCP - semantic search, zero-code setup.
Persistent memory for Claude Code and Cursor. Stop re-explaining your project every session.
Persistent memory for AI assistants. Save once; recall from Claude, ChatGPT, or any MCP client.
Persistent AI memory shared across Claude, ChatGPT, coding agents, and compatible MCP clients.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/louis49/melchizedek'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
