scoped_memory
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@scoped_memoryremember we chose SQLite for local storage and why"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Scoped Memory
做项目时,真正麻烦的往往不是忘了一句聊天内容,而是忘了当时为什么这样决定、哪些办法已经试过、下一步该从哪里接着做。
Scoped Memory 是一个可供 Codex 和 DeepSeek Harness 使用的本地工程记忆工具。它把值得长期保留的内容按照“使用者、项目、当前任务”分开放置,并用脚本把工程转换成紧凑的结构化事实。换一个会话或代理继续工作时,可以直接读取已有结论和工程关系,不必重新翻完整聊天记录,也不必先把代码改写成自然语言摘要。
为什么不让大模型每次重新读工程
一般的工作方式是:大模型打开很多文件,把代码、日志和测试重新解释成一段自然语言,然后再依靠这段解释继续工作。项目一大,这个过程会反复消耗上下文;压缩以后还可能丢失文件路径、符号名称、依赖方向和证据位置。
Scoped Memory 把工作分成两层:
工程脚本负责整理事实。 脚本直接扫描文件树,读取语言结构和项目清单,记录文件指纹、顶层符号、导入关系、测试位置、依赖名称和 Git 状态。这个过程可重复、可比较,不需要调用大模型。
大模型负责判断和工作。 Codex 或 DeepSeek Harness 先查询一小段与当前任务有关的工程事实,再按需打开少数源码文件。它不用先把整个工程翻译成文章,最后向人交付结果时才组织自然语言。
实际流程是:
代码、测试、配置和 Git 状态
↓
确定性工程扫描脚本
↓
按项目隔离的 EIR/1 工程索引
↓
按问题和长度预算选出相关事实
↓
Codex / DeepSeek Harness 继续分析、修改和验证
↓
最终结果才转换成人类自然语言例如,模型不需要先阅读一段“认证模块依赖数据库模块”的说明。它可以直接得到:认证文件包含哪些符号、导入了哪个模块、对应测试在哪里、这些文件当前是否发生变化。需要确认实现细节时,它再打开准确的文件,而不是重新遍历整个仓库。
这样做带来的变化:
减少重复读取和重复总结,给实际推理、编码和测试留下更多上下文。
文件、符号、依赖和版本都有稳定标识,不依赖某次聊天的措辞。
Codex 与 DeepSeek Harness 可以读取同一份工程地图,不需要分别建立两套自然语言摘要。
工程发生变化后重新运行脚本,就能用文件指纹和 Git 状态识别新旧差异。
索引只是导航和记忆,不替代源码、测试或运行结果;需要下结论时仍以真实工程证据为准。
第一版有意保持简单和可检查。它能提取 Python、JavaScript、TypeScript 等常见源码的顶层符号与导入关系,也能识别测试和常见依赖清单;它不会假装已经理解所有业务含义,也不会凭索引自动证明调用链正确。更深的语义分析、增量差异和语言服务器接入可以在后续版本继续扩展。
Related MCP server: ITHZ MCP
它适合记住什么
长期有效的工作习惯,例如代码风格和交付偏好。
只属于当前项目的架构决定、限制条件和已经验证的事实。
当前任务做到哪里、还有什么没完成、哪些方法已经失败。
它不应该保存密码、密钥、个人资料、完整聊天记录或大段命令输出。这里保存的是帮助继续工作的摘要,不是另一个聊天档案库。
不同项目不会混在一起
每个项目都有独立身份。默认情况下,一个项目看不到另一个项目的记忆。只有使用者明确指定要继承哪个项目时,跨项目内容才会被读取。
同一个 Git 仓库的工作树共享项目身份,因此在不同工作树之间切换不会失忆。普通复制或重新克隆的仓库不会自动继承原项目记忆,避免把不相关的工程误认成同一个项目。
记忆怎样保存
所有内容默认留在本机,不需要云端服务,也不需要额外密钥。记录先进入 SQLite 数据库,同时生成一份便于检查和迁移的 JSONL 审计日志。
旧记录不会被偷偷改写。更新一条结论时,系统会追加一条新记录并注明它取代了哪一条;忘记某项内容时,也会追加一条删除标记。这样可以追溯发生过什么,也可以检查日志是否完整。
在 Codex 中怎样工作
插件会在任务开始、恢复以及上下文压缩后,自动取回当前项目最相关的一小段记忆。内容有严格的长度限制,不会把整个历史重新塞回会话。
也可以通过命令行或 MCP 工具主动保存决定、建立任务检查点、查找记录或忘记某个主题。读取类工具不会改动数据;写入和忘记操作有明确的权限标记。
工程中间层 EIR/1
memory_ingest_project 使用确定性脚本扫描工程,生成 EIR/1:文件指纹、语言、符号、导入关系、测试角色、依赖清单和 Git 状态。它不调用大模型,不保存源码正文,并跳过密钥、环境变量文件、二进制文件和超大文件。
memory_engineering_context 再按查询和 token 预算返回一小段紧凑 JSON。大模型直接消费这些符号和关系;只有最终交付给人时才需要整理成自然语言。
scripts/scoped-memory --home /tmp/scoped-memory-demo ingest .
scripts/scoped-memory --home /tmp/scoped-memory-demo engineering-context . --query memory --token-budget 1200DeepSeek Harness
DeepSeek Harness 原生支持本地 stdio MCP,因此可以直接使用同一个服务:
先使用隔离环境安装命令行服务:pipx install git+https://github.com/lixuanfan567-png/scoped-memory.git。
- insert:
- id: mcp-scoped-memory
name: '@deepseek-ai/dsh-mcp-client'
config:
serverName: scoped_memory
transport: stdio
command: scoped-memory-mcp
cwd: !!js process.cwd()
env:
SCOPED_MEMORY_HOME: /absolute/path/to/scoped-memory-data连接后,Harness 会看到 mcp__scoped_memory__memory_ingest_project、mcp__scoped_memory__memory_engineering_context 以及原有记忆工具。Codex 与 DeepSeek Harness 可以共享同一个本地记忆库,同时继续遵守项目隔离规则。
本地开发
需要 Python 3.10 或更高版本。运行测试:
python3 -m unittest discover -s tests -v构建安装包:
python3 -m pip wheel . --no-deps初始化一个项目并查看状态:
scripts/scoped-memory --home /tmp/scoped-memory-demo init .
scripts/scoped-memory --home /tmp/scoped-memory-demo status .测试覆盖项目隔离、任务隔离、显式继承、Git 工作树、独立克隆、并发写入、更新与忘记、中文长度预算、EIR 工程提取、敏感文件排除、启动注入、MCP 调用和审计恢复。
当前状态
项目目前处于早期版本。核心存储、隔离规则、Codex 启动注入和 MCP 调用已经通过自动化测试及真实运行验证,但在稳定版发布前仍可能调整接口。
参与方式见 CONTRIBUTING.md,安全边界和漏洞报告方式见 SECURITY.md。
本项目使用 MIT 许可证,详见 LICENSE。
Available Tools
8 toolsmemory_checkpointC
Store a structured task checkpoint for later continuation. Use concise model-readable facts, not conversation prose.
| Name | Required | Description | Default |
|---|---|---|---|
| summary | Yes | ||
| evidence | No | ||
| decisions | No | ||
| next_steps | No | ||
| session_id | Yes | ||
| constraints | No | ||
| project_root | Yes |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate a write operation (readOnlyHint=false), and the description confirms this with 'Store'. It adds the advice to use 'concise model-readable facts, not conversation prose', which is useful content guidance. However, it does not disclose persistence behavior, whether it overwrites existing checkpoints, or any side effects on other memory tools. 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?
The description is two sentences, front-loaded with the core purpose and followed by a concise content guideline. No wasted words, though the second sentence could be integrated more structurally.
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 (3 required), no output schema, and minimal behavioral context, the description is inadequate. It lacks parameter semantics, usage guidance, and any explanation of how the checkpoint integrates with the broader memory system. An agent would struggle to call this correctly without external knowledge.
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%. The description mentions 'structured task checkpoint' but does not explain any of the 7 parameters (summary, evidence, decisions, next_steps, session_id, constraints, project_root). The required fields are entirely undocumented, forcing the agent to guess their semantics from names 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?
The description clearly states the verb 'store' and the resource 'structured task checkpoint' with a purpose ('for later continuation'). It distinguishes the concept from siblings like memory_remember by implying a checkpoint is a snapshot of progress, but it does not explicitly name alternatives or differentiate beyond that.
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 like memory_remember or memory_recall. The description implies a use case (continuation) but gives no exclusions or explicit conditions. An agent must infer when a checkpoint is appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
memory_engineering_contextBRead-onlyIdempotent
Read a bounded EIR/1 engineering packet. Returns machine-readable facts without natural-language translation.
| Name | Required | Description | Default |
|---|---|---|---|
| query | No | ||
| project_root | Yes | ||
| token_budget | No |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, and the description's 'Read' wording aligns with that safety profile. It adds some behavioral context by noting the packet is 'bounded' and that output is machine-readable facts without NL translation, but it does not explain limits, errors, or what happens when the token budget is exceeded.
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 short sentences with no filler. The core action is front-loaded, and the additional return-format detail earns its place. Despite the unexplained acronym, the description is appropriately sized.
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?
With no output schema and three parameters at 0% schema coverage, the description needs to explain how to call the tool and what to expect. It only covers the general return style, leaving query semantics, token budget behavior, and the meaning of project_root largely to inference.
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%, so the description must compensate for the undocumented parameters. It does not explain project_root, query, or token_budget explicitly; 'bounded' hints at token_budget and 'engineering packet' hints at project_root, but these are too indirect to guide correct invocation.
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 a clear verb and resource: 'Read a bounded EIR/1 engineering packet.' It also adds a distinguishing output trait, 'machine-readable facts without natural-language translation,' which helps separate it from natural-language-oriented memory tools. However, 'EIR/1' is unexplained and sibling differentiation is implicit rather than explicit.
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 given about when to use this tool instead of siblings like memory_recall or memory_status. The phrase 'engineering packet' weakly implies context, but there is no stated selection criterion, prerequisite, or exclusion.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
memory_forgetBDestructiveIdempotent
Append a tombstone for a topic; prior history remains auditable.
| Name | Required | Description | Default |
|---|---|---|---|
| scope | Yes | ||
| topic | Yes | ||
| session_id | No | ||
| project_root | No |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description meaningfully refines the annotations: destructiveHint=true could imply irrecoverable deletion, but the description clarifies the operation is a tombstone append where prior history remains auditable — a genuinely non-obvious behavioral fact beyond what readOnlyHint=false/idempotentHint=true/destructiveHint=true convey. It stops short of explaining the effect on future recalls, but the core safety-and-mechanism profile is well covered.
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?
A single 10-word sentence with zero filler; the mechanism ('Append a tombstone') is front-loaded and the key behavioral property ('prior history remains auditable') follows immediately. Every phrase 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?
The mechanism and auditability guarantee are covered, but the tool mutates state with no output schema and the agent is left without knowledge of return shape, the effect on subsequent memory_recall calls, or how the optional session_id/project_root parameters combine with the required scope/topic. For a 4-parameter mutation this is workable but has clear operational 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?
Schema description coverage is 0%, so the description bore the full burden of explaining scope (enum user/project/session), topic, session_id, and project_root — and it only touches 'topic' implicitly via 'for a topic'. The interplay of scope, session_id, and project_root is entirely undocumented, and the description fails to compensate for the schema's lack of param descriptions.
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 a specific mechanism — 'Append a tombstone for a topic' — with a clear verb (append) and resource (tombstone for a topic), and the auditability clause distinguishes this from a hard delete, which meaningfully clarifies what 'forget' does. However, 'tombstone' is jargon that isn't unpacked, and it doesn't explicitly differentiate from siblings like memory_remember or memory_recall.
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 given on when to use memory_forget versus any of its seven siblings, when forgetting is appropriate, or what prerequisites apply (e.g., whether the topic must exist, how scope selection affects behavior). An agent must infer usage entirely from the tool name and the one-line mechanism.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
memory_ingest_projectAIdempotent
Scan a project deterministically into compact EIR/1 facts and dependency edges; no model summary is used.
| Name | Required | Description | Default |
|---|---|---|---|
| max_files | No | ||
| project_root | Yes | ||
| max_file_bytes | No |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already carry idempotentHint=true, destructiveHint=false, and readOnlyHint=false, which cover the safety profile. The description adds deterministic behavior and the output format, but it does not disclose side effects such as writing to memory, whether existing facts are overwritten, or any operational requirements. It adds some context without contradicting 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 a single compact sentence with no filler. It front-loads the main action and includes only meaningful qualifiers ('deterministically', 'compact', 'no model summary'), making it efficient and easy to parse.
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 that is not read-only (readOnlyHint=false), with no output schema and two parameters whose semantics are unexplained, the description is incomplete. It doesn't explain where the EIR/1 facts are stored, how results are returned, what the size/file limits control, or how idempotency manifests. An agent would need to guess key operational details.
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%, so the description must compensate by explaining parameter meaning. It only implies that 'project' maps to project_root and says nothing about max_files or max_file_bytes, leaving the agent to guess what these limits do. This is minimal compensation and insufficient for two of the three 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 clearly states a specific action (deterministically scanning a project) and output (EIR/1 facts and dependency edges). It also distinguishes itself from model-based siblings like memory_remember by explicitly stating no model summary is used, so an agent can tell what this tool does relative to the family.
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 usage for deterministic project scanning by contrasting with model summaries, but it never explicitly names when to use this tool versus siblings like memory_remember or memory_engineering_context, nor does it mention when not to use it. This is implied guidance, not explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
memory_init_projectAIdempotent
Create or reuse a stable project identity in .scoped-memory/project.json.
| Name | Required | Description | Default |
|---|---|---|---|
| name | No | ||
| project_root | Yes |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide idempotentHint=true and destructiveHint=false, and the description adds the important behavioral nuance of 'reuse', implying existing state is not destroyed. It also discloses the specific file affected, which is useful beyond the raw annotation values.
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 a single front-loaded sentence with no filler. Every word contributes to identifying the action, the object, and the location, which is appropriately concise for a simple two-parameter 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?
For a low-complexity tool with supportive annotations, the core behavior is communicated adequately. However, there is no mention of what happens when the file already exists beyond 'reuse', no description of the optional name parameter, and no indication of what the tool returns or confirms.
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%, so the description carries the burden, but it only indirectly hints that project_root is the location containing .scoped-memory. The optional 'name' parameter is not explained at all, leaving its purpose and format ambiguous.
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 a specific verb ('Create or reuse'), a clear resource ('stable project identity'), and the exact location ('.scoped-memory/project.json'). This clearly distinguishes it from siblings like memory_ingest_project or memory_status.
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 given about when to call this tool versus alternatives, such as before ingesting a project or when a project identity is missing. The sibling tools are listed in context, but the description does not reference them or state the conditions that select this one.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
memory_recallCRead-onlyIdempotent
Build a deterministic token-budgeted context packet. Other projects are excluded unless their IDs are explicitly inherited.
| Name | Required | Description | Default |
|---|---|---|---|
| query | No | ||
| scopes | No | ||
| session_id | No | ||
| project_root | No | ||
| token_budget | No | ||
| inherit_project_ids | No |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds useful behavioral context: output is deterministic, token-budgeted, and project-scoped unless inheritance is explicit. This is modest value beyond annotations, with 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?
The description is two short sentences with no filler; the primary action is front-loaded and the second sentence adds a relevant scoping constraint. Every word earns its place, and the structure is easy to scan.
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 6-parameter tool with no output schema, this description is too sparse for an agent to invoke it correctly. It omits what 'context packet' means, what query and scopes do, which fields are needed, and what the tool returns. The project-exclusion note is a small fragment of the needed 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?
Schema description coverage is 0%, so the description needed to compensate by explaining the six parameters. It only hints at token budgeting and inherited project IDs; query, scopes, session_id, and project_root are left entirely unexplained. This is far below what a 0%-coverage tool requires.
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 identifies a concrete action and output ('Build a deterministic token-budgeted context packet') and adds a project-scoping rule, so a basic purpose is present. However, 'context packet' is vague jargon and the recall/retrieval nature is only implied by the tool name. It does not distinguish this from sibling tools such as memory_engineering_context.
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?
There is no guidance on when to call this tool versus siblings like memory_engineering_context, memory_remember, or memory_status. The only additional statement—that other projects are excluded unless inherited—describes a behavioral constraint, not a usage condition or alternative selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
memory_rememberB
Append a user, project, or session memory. Reusing a topic supersedes it without rewriting history.
| Name | Required | Description | Default |
|---|---|---|---|
| tags | No | ||
| scope | Yes | ||
| topic | Yes | ||
| content | Yes | ||
| metadata | No | ||
| importance | No | ||
| session_id | No | ||
| project_root | No |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses a non-obvious behavior: 'Reusing a topic supersedes it without rewriting history,' which adds meaningful context beyond the sparse annotations. Since readOnlyHint, idempotentHint, and destructiveHint are all false, this explanation helps clarify the actual write semantics without contradicting them.
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, with the purpose front-loaded and the behavioral caveat in the second sentence. It is appropriately compact, though the phrase 'supersedes it without rewriting history' is somewhat ambiguous.
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?
With 8 parameters, no output schema, and no parameter descriptions, the description leaves too much unspecified: meaning of required fields, effect of optional fields like metadata and importance, return value, and how the 'history' mechanism works. It is not complete enough for reliable 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 description coverage is 0%, and the description names no parameters directly. It indirectly mentions 'topic' and scope values, but does not explain content, metadata, tags, importance, session_id, or project_root, so it does not compensate for the lack of parameter descriptions in 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 uses the specific verb 'Append' and identifies the resource as user/project/session memory, which is clear. It adds a behavioral nuance about topic reuse, but it does not explicitly differentiate from sibling tools like memory_ingest_project or memory_engineering_context, so it lacks full sibling differentiation.
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?
There is no guidance on when to use this tool versus memory_recall, memory_forget, memory_ingest_project, or memory_engineering_context. The description implies use when appending memory, but provides no selection criteria, prerequisites, or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
memory_statusBRead-onlyIdempotent
Show store paths, counts, current project identity, and append-log integrity.
| Name | Required | Description | Default |
|---|---|---|---|
| project_root | No |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, and the 'Show' wording is consistent with them. The description does not add meaningful behavioral detail beyond those annotations, such as whether it reads from disk or whether it can affect the append log, but it also does not contradict them.
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 a single dense sentence that front-loads the verb and immediately lists the four kinds of information returned. There is no filler, repetition, or unnecessary explanation.
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 tool is relatively simple, has only one optional parameter and no output schema, and its safety profile is fully covered by annotations. However, the missing parameter semantics and the lack of guidance relative to memory_checkpoint make the description incomplete enough to be only minimally viable.
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?
The single parameter, project_root, has 0% schema description coverage, and the tool description never mentions it. Because the schema provides only a type with no explanation, the description should compensate but instead leaves the agent guessing how project_root affects the output.
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 uses a specific verb, 'Show', and enumerates precise resource categories: 'store paths, counts, current project identity, and append-log integrity.' This clearly differentiates it from mutating or memory-writing siblings like memory_forget and memory_ingest_project.
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 usage context is provided, and there is no statement about when to use this tool versus alternatives such as memory_checkpoint. The agent must infer entirely from the tool name that this is a read-only status/health inspection tool, so practical guidance is essentially absent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
8 tool updates
v0.3.0- First observed
memory_checkpoint - First observed
memory_engineering_context - First observed
memory_forget - First observed
memory_ingest_project - First observed
memory_init_project - First observed
memory_recall - First observed
memory_remember - First observed
memory_status
TDQS
Scored across 8 tools
Each tool has a distinct responsibility: ingestion, recall, forgetting, status, checkpointing, and project init. However, memory_recall and memory_engineering_context both produce context packets, and memory_remember overlaps somewhat with memory_ingest_project and memory_checkpoint, requiring careful reading of descriptions.
All tools share the memory_ prefix, but the pattern after the prefix is inconsistent: verb_noun forms like memory_ingest_project and memory_init_project, bare verbs like memory_forget and memory_remember, and nouns like memory_engineering_context, memory_status, and memory_checkpoint. This is readable but not a single predictable convention.
Eight tools is well-scoped for a memory server covering project initialization, ingestion, remembering, checkpointing, recall, forgetting, and status. Each tool has a clear place in the workflow, and none feels redundant.
The memory lifecycle is largely covered: init, ingest, remember, checkpoint, recall, forget, and status. Minor gaps include no direct single-memory retrieval or search operation, and the relationship between memory_engineering_context and memory_recall is not fully clarified.
Maintenance
Related MCP Connectors
Project memory for coding agents: requirements, decisions, code graph and delivery telemetry.
Project memory, semantic code search, and grounded agent context.
Persistent memory layer that saves and recalls your project context and preferences.
Shared project memory that keeps teammates and AI agents aligned across sessions.
Related MCP Servers
- AlicenseNot gradedqualityBmaintenanceProvides durable project context for coding agents, including project maps, session history, and explicit memories, all stored locally.46 npm7MIT
- FlicenseNot gradedqualityCmaintenanceLocal-first deterministic project memory for AI coding agents, with context packs, decisions, gates, risks, scoped claims and explicit checkpoints in project-owned files.-
- AlicenseNot gradedqualityAmaintenanceProvides AI agents with persistent, local, and shareable project memory by storing decisions and code context in a searchable SQLite index, supporting keyword and semantic search via MCP.39 PyPI3MIT
- AlicenseNot gradedqualityAmaintenanceProvides persistent project memory for AI coding agents, enabling context retention across sessions via event logging, briefing generation, and querying.MIT