memory: README does not say that unreadable lines are skipped, kept on every write, and fixable only by hand

Open Beginner friendly
#5,609 1 comment 0 reactions 0 assignees View on GitHub

Maintainers usually reply within 1 day

Nobody has claimed this yet.

Assessment

Difficulty
1/5
Estimated time
Under an hour
Newbie friendliness
90/100
Issue type
Documentation
Clarity
Clearly specified
Activity status
Active
Tech stack
typescript
Domain
documentation

Research direction

Read src/memory/README.md alongside loadGraphWithUnreadable and saveGraph in src/memory/index.ts to confirm the documented behavior. Add a short passage near storage or troubleshooting covering skipped and logged lines, preservation on writes and byte limits, tool limitations, and manual repair. Done when the README explains the stated behavior and recovery steps.

Written by the indexing model from the issue text.

Description

documentation server-memory v2
Which server?

memory (@modelcontextprotocol/server-memory), src/memory/README.md.

The problem

The README does not say what the server does with a line of the memory file it cannot read, or how to fix one. The only mention is in passing, under the write limits ("MEMORY_MAX_FILE_BYTES counts the bytes of the file as it would be saved, unreadable lines included").

What the server does today (loadGraphWithUnreadable and saveGraph in src/memory/index.ts, from #4885):

  • A line that is not JSON, is not an object, has an unknown type, or fails the entity or relation schema (an entity with no entityType, an observation that is not a string, a relation with no relationType) is left out of the graph. Each skipped line is logged to stderr ("Skipping invalid entity in memory file: …").
  • Every save writes those lines back unchanged, after the graph's own lines, so a write never drops data it could not read.
  • No tool can then remove or repair such a line. read_graph, search_nodes and open_nodes do not show it; delete_entities and delete_observations report its name as not found; add_observations and create_relations fail with "Entity with name … not found"; create_entities under the same name stores a second record beside the invalid line; an invalid relation matches no delete_relations call and stays after the entities it names are deleted. #5541 pins this in src/memory/__tests__/invalid-record-removal.test.ts.

So the only remedy is to edit the file by hand, and a user who sees the stderr line, or a Not found for an entity they can see in the file, has nowhere to read that.

Expected

A short passage in the README (near the storage or troubleshooting sections) stating: which lines are skipped, that they are logged to stderr, that they are kept in the file on every write and count toward MEMORY_MAX_FILE_BYTES, that no tool reaches them, and that the fix is to stop the clients using the file and correct or delete the line in a text editor.

Scope

Documentation only. Whether a remediation tool should exist is a separate question this issue does not ask.

Found while verifying #5541.

Dominant language
TypeScript
Stars
92k
Forks
12k
Avg merge
3h 46m
Merged PRs (30d)
206

Getting set up

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from modelcontextprotocol/servers

All issues in modelcontextprotocol/servers

Similar issues

More TypeScript issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.