Plain Text Memory MCP
Plain Text Memory MCP turns a repo's Markdown memory files into a knowledge graph of entities and relations that agents read and edit over MCP.
Create entities with a type and a list of observations, skipping names that already exist.
Create directed, typed relations between existing entities (skipping ones with missing ends).
Add observations to existing entities, skipping text already present.
Edit an observation in place, keeping its original author/date and recording
edited_at/edited_by.Rename an entity and repoint every relation that names it.
Merge one entity into another, moving observations and relations and deleting the source.
Delete entities (with all touching relations), exact-text observations, or relations.
Read the whole graph, optionally filtered by
since,before, oragent.Search by words across entity names, types, and observations, with
"quoted phrases"kept whole; a blank query returns everything.Open entities by exact name along with their relations.
Initialize or adopt a memory file when its header names another repo (
freshbacks up and starts empty;adoptre-claims it).Export a JSONC taxonomy file with the versioned schema and this repo's usage counts.
Note: the README's
stamp_notesandrecalltools are not present in this schema.
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., "@Plain Text Memory MCP search memory for how the auth flow works"
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.
plain-text-memory-mcp
MCP server that gathers a repo's Markdown memory files into one searchable, stamped knowledge graph.
Agents keep memory in MEMORY.ptm.md files, one per folder that needs it,
and edit them with their normal file tools. The server reads every such file,
plus each AGENTS.md, and serves them as one graph: search returns only the
facts that match, ranked and scoped to the folder in question, instead of an
agent reading whole files on every task. After an agent edits a file, the
server stamps each new line with the date and the agent that wrote it.
It grew out of @modelcontextprotocol/server-memory, but stores nothing of
its own: the Markdown files are the memory, and they belong in git.
Install
The server runs with uv; uvx downloads and
starts it on demand, so there is nothing else to install.
uvx plain-text-memory-mcpStarted by hand, it waits for an MCP client on stdin; press Ctrl+C to stop.
Related MCP server: dejaview-mcp
Configure
Add the server to each agent's MCP config. The server finds the repo from the folder the agent starts it in, so register it per project.
Claude Code, .mcp.json in the repo:
{
"mcpServers": {
"plain-text-memory": {
"type": "stdio",
"command": "uvx",
"args": ["plain-text-memory-mcp"]
}
}
}Codex, .codex/config.toml:
[mcp_servers.plain-text-memory]
command = "uvx"
args = ["plain-text-memory-mcp"]Cursor, .cursor/mcp.json in the repo:
{
"mcpServers": {
"plain-text-memory": {
"command": "uvx",
"args": ["plain-text-memory-mcp"]
}
}
}VS Code, .vscode/mcp.json in the repo:
{
"servers": {
"plain-text-memory": {
"type": "stdio",
"command": "uvx",
"args": ["plain-text-memory-mcp"]
}
}
}Memory files
A MEMORY.ptm.md file holds facts about the folder it sits in and every
folder below it. The one at the repo root holds repo-wide facts.
# search
Ranks notes with BM25 plus spreading activation.
## bm25.py
- Tokenizes with a lowercase word regex and does no stemming. <!-- 2026-10-09T14:02-04:00 claude-code #9f2ce -->
- uses [[ranking.py]] <!-- 2026-10-09T14:02-04:00 claude-code #41b0e -->
- Ranking uses BM25 over TF-IDF, because TF-IDF ranked long notes too high. <!-- 2026-10-09T14:05-04:00 codex #c3d4e -->
- ~~Ranking uses TF-IDF.~~ <!-- 2026-10-01T09:15-04:00 codex #a1b2e retired 2026-10-09T14:05-04:00 --># namenames the folder. Without it, the folder's own name is used.## namestarts an entity, such as a module; bullets after it belong to it.Each
-bullet is one fact on one line. The facts worth saving are the ones the code cannot show: decisions and why they were made, options tried and dropped, and limits found the hard way.A bullet that is only a short verb and a
[[link]]is a relation to another entity, in any memory file.A fact that stops being true is struck through with
~~and nested under the fact that replaced it, which says why, so its history stays in the file.
The server finds the files with git ls-files, so .gitignore decides
which are skipped; outside git, it skips dot folders. It reads AGENTS.md
files too, as read-only notes grouped by heading. Edits show up in the next
search without a restart.
Stamps
Agents never write the <!-- --> comments. After editing, an agent calls
stamp_notes with the files it changed, and the server adds a stamp to each
new or reworded line:
the time (local, to the minute, with UTC offset),
the agent (
claude-code,codex, or the client's own name; setMEMORY_AGENTto override it), anda short hash of the text, so a reworded line is stamped again.
A newly struck line gets its retirement time. Struck lines retired more than
90 days ago move to MEMORY.ptm.archive.md in the same folder, so live
files stay short. Only the named files change. Lines nobody has stamped,
and all AGENTS.md text, show null for the date and agent.
stamp_notes also returns warnings for lines that:
reword a fact already saved (
near_duplicate, word-shingle resemblance; Broder, 1997),read as instructions to an agent (
instruction_like),look like a secret, such as an API key or private key (
secret),state a fact with no word such as "because" or "so" that gives its reason (
no_reason), orlink to an entity no memory file names (
broken_link);
and for any named file longer than 200 lines (long_file).
Search
search_nodes ranks with BM25 (Robertson & Zaragoza, 2009): words match
whole, ignoring case and plain plurals, a "quoted phrase" must appear
whole, and rare words count more than common ones. Each note is scored on
its own and returned under hits with its entity name, rank, and the path
of the file it came from, alongside the matching entities. Scores get a
small boost from ACT-R base-level activation (Anderson et al., 2004), which
counts when a line was stamped and when agents opened its entity; with no
opens, this is power-law recency (Anderson & Schooler, 1991).
limitcaps the entities and hits returned.since,before, andagentfilter by stamp.expandspreads scores along relations with personalized PageRank (HippoRAG, Gutiérrez et al., 2024), so linked entities can join the results.Struck facts are hidden unless
include_supersededis set.Both lists put the strongest results at the start and end and the weakest in the middle, because models read the middle of a long context worst (Liu et al., 2024).
recall searches in numbered steps, after the
sequentialthinking
server. Each step gives a reason, runs up to three queries, and can open
entities. A step returns at most eight hits, and never one that an earlier
step of the same session returned, plus the linked entities not yet opened.
Given a path, notes from memory files in folders covering it rank higher.
The last step records a conclusion and the notes it rests on.
open_nodes returns entities by exact name.
Local files
The server keeps a few local files in <repo root>/.agents/ptm/; ignore
them with the .gitignore line .agents/ptm/.
stamp.lockserializes stamping, so Claude Code and Codex can stamp the same repo at the same time.access.jsonllogs each opened entity; search uses it to rank often-opened entities higher. Deleting it only resets that ranking.
Guidance for agents
On connect, the server sends every MCP client instructions for using memory
well: recall in steps before planning, verify what memory says against the
repo, save only lasting facts in the narrowest folder, and call
stamp_notes after editing. Tool and parameter descriptions say what each
tool does and returns. No agent-specific setup is needed.
Taxonomy
taxonomy.json lists every record
type with its purpose and fields, every tool with its parameters and results,
every MCP resource, and the allowed values for enum fields such as agent.
It is generated from the code; do not edit it by hand. Record type purposes
live in RECORD_PURPOSES in records.py. The file ships inside the
package, and MCP clients can read it as the resource memory://taxonomy.
taxonomy_version follows semantic versioning and bumps itself: a removed
item, section, or changed type is major, an added item is minor, and a
description, purpose, title, or package version change is patch. Each bump
adds a changelog entry listing what changed.
Regenerate it with:
.venv/Scripts/python.exe scripts/build_taxonomy.pyThe pre-commit hook runs this and stops the commit when the file changes, so the new version is reviewed and staged. A test also fails when the committed file is stale. Enable the hook once per clone:
git config core.hooksPath .githooksDevelop
py -3.13 -m venv .venv
.venv/Scripts/python.exe -m pip install -e . --group dev
.venv/Scripts/python.exe -m pytestTo have agents run your working copy instead of the published package,
install it as an editable tool and use plain-text-memory-mcp as the
config's command, with no args:
uv tool install -e .Code changes then take effect the next time an agent starts the server.
Set MEMORY_RECALL_LOG=1 in the server's environment to append every
recall step, search_nodes call, and open_nodes call to
.agents/ptm/recall.jsonl: what was searched, why, the hits, and
the conclusion. The log is for developing the server; it is off by default
and never read back.
License
MIT, copyright Plain Text Office LLC. See LICENSE.
Available Tools
4 toolsopen_nodesOpen entitiesARead-onlyIdempotent
Open entities by exact name.
Returns the named entities and every relation that touches them; a relation's other end may be outside the results. Names that do not exist are ignored. Struck-through facts are hidden unless include_superseded is set. Each open is logged, so search ranks often-opened entities higher. To find entities by keyword, see search_nodes.
Inputs: names (required), include_superseded. Returns: Entities and the relations between them, as tools return them.
recallRecall memory in stepsARead-only
Search memory in steps, recording why each search was made.
Each step runs its queries and opens named entities, returning only hits not already returned in this session, plus linked entities not yet opened. Small matching entities are returned whole. With path, notes from MEMORY.ptm.md files in folders covering it rank higher. The last step records a conclusion and the facts it rests on. An unknown session starts a new one. For a single lookup, see search_nodes.
Inputs: step (required), thought (required), total_steps (required), next_step_needed (required), +7 more. Returns: One recall step: new hits, opened entities, and what to open next.
search_nodesSearch memoryARead-onlyIdempotent
Search entities and notes, ranked by BM25 relevance.
Words match whole, ignoring case and plain plurals; rare words count more than common ones. Recent and often-opened memories rank a little higher. Returns "hits", the matching notes with their entity names and ranks; and the matching entities with every relation that touches them, whose other end may be outside the results. Both lists put the strongest results at the start and end and the weakest in the middle. A query with no words returns every entity and no hits. With since, before, or agent, searches only entries whose tags match; any of them leaves out untagged entries. Each note's path names the memory file it came from. To fetch entities by exact name, see open_nodes. For a multi-step search before planning a task, see recall.
Inputs: query (required), agent, limit, since, +3 more. Returns: Matched entities, the relations touching them, and the top hits.
stamp_notesStamp notesAIdempotent
Stamp new and changed notes in memory files, then screen them.
Each bullet with no stamp, or whose text changed since it was stamped, gets a stamp naming the caller and the current time; a newly struck bullet gets its retirement time. Struck notes retired over 90 days ago move to MEMORY.ptm.archive.md beside the file. Only the named files change. Returns per-file counts, and warnings about new or changed notes: near-duplicates, instruction-like text, secrets, facts that give no reason, and [[links]] to entities no memory file names; and about files over 200 lines.
Inputs: paths (required). Returns: Per-file stamp counts, and warnings about new or changed notes.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 4 tools
The tools have mostly distinct roles: recall is a multi-step session search, search_nodes is a single BM25 query, open_nodes fetches by exact name, and stamp_notes handles maintenance. recall and search_nodes both perform searching, but their descriptions explicitly cross-reference each other and clarify when to use which.
Three tools follow a clear verb_noun pattern: stamp_notes, search_nodes, open_nodes. recall is a bare verb rather than verb_noun, which is a minor deviation but still readable and consistent with the verb-first style.
Four tools is a tight, well-scoped set for a plain-text memory server. Each tool covers a distinct retrieval or maintenance operation, and none feels redundant or excessive.
The surface covers retrieval (recall, search_nodes, open_nodes) and note maintenance (stamp_notes), but there is no explicit tool for creating, updating, or deleting notes/entities/relations. Agents must rely on external file editing or stamping existing notes, which is a notable gap for a memory server.
Maintenance
Related MCP Connectors
Shared long-term memory for AI agents: save and recall context as a searchable knowledge graph.
Shared memory for coding agents. Stop re-explaining your codebase every session.
Persistent knowledge graph for AI-augmented teams. Store decisions, findings, and standing rules across agent sessions with semantic search and typed connections. Includes cross-session memory, audit trail, workspace isolation, and secret detection. Built for teams running agents that need to remember. Free until launch with team tier as default, anon trial available.
Long-term memory for your AI as a private knowledge graph: facts, people, links, sources.
Related MCP Servers
FlicenseNot gradedqualityDmaintenanceProvides persistent long-term memory for AI coding agents by storing entities, relations, and observations across different sessions. It enables users to manage and query structured knowledge like coding preferences, project patterns, and technical solutions via a graph-based storage system.1-- AlicenseNot gradedqualityDmaintenanceProvides persistent knowledge graph memory for AI agents, enabling them to store, recall, and query facts about people, projects, and relationships across sessions.MIT
- AlicenseNot gradedqualityCmaintenanceEnables AI assistants to store, query, and update persistent project knowledge as a local, Git-friendly knowledge graph, providing structured memory across sessions.9Apache 2.0
- AlicenseNot gradedqualityCmaintenanceGives AI coding agents persistent, branch-aware memory and a dependency-tracked task graph by storing decisions, lessons, and tasks as plain JSON and Markdown committed directly into the repository. Agents can record and fuzzy-search past decisions, dump instant project context, and create, claim, complete, and query tasks whose completion automatically unblocks downstream work.MIT