plain-text-memory-mcp
MCP server that gathers a repo's Markdown memory files into one searchable, stamped knowledge graph.
Install · Configure · Search · User manual · PyPI
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 package requires Python 3.12 or later. The server runs with
uv; uvx downloads and starts it on demand, so
there is nothing else to install.
uvx plain-text-memory-mcp
Started by hand, it waits for an MCP client on stdin; press Ctrl+C to stop.
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": {
"type": "stdio",
"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, node_modules, and
__pycache__. 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, the client's own name, orunknownwhen the client sends no name; setMEMORY_AGENTto override it), and - a short hash of the text, so a reworded line is stamped again.
A newly struck line gets its retirement time. Struck lines retired 90 days
or more 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), or - link 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. Past 5,000 lines it is trimmed to the newest opens. 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.py
The 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 .githooks
Develop
py -3.13 -m venv .venv
.venv/Scripts/python.exe -m pip install -e . --group dev
.venv/Scripts/python.exe -m pytest
To 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.
Feedback
Report a bug or request a feature in GitHub Issues, or use the contact form.
User Manual
The User Manual covers installation, client configuration, tools, settings, and troubleshooting.
License
MIT, copyright Plain Text Office LLC. See LICENSE.
Metadata
Release files for plain-text-memory-mcp 0.4.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| plain_text_memory_mcp-0.4.1.tar.gz | 72.0 kB | With provenance | Details for plain_text_memory_mcp-0.4.1.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| plain_text_memory_mcp-0.4.1-py3-none-any.whl | Python 3 | none | any | Details for plain_text_memory_mcp-0.4.1-py3-none-any.whl |
Total release size: 125.0 kB
Release files / plain_text_memory_mcp-0.4.1.tar.gz
| Download URL | plain_text_memory_mcp-0.4.1.tar.gz |
|---|---|
| Size | 72.0 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
c762f80d92e19f64d9f46cba90a6dbd7a75b6c09ae8fbc4c450302fae624ae03
|
|
BLAKE2b-256 checksum How to use checksums |
f0afcf4cd88b611eef1aa03cb6955da8c8bb7c9530f5fdc17e5a07da9522ba27
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 19, 2026.
Transparency logRelease files / plain_text_memory_mcp-0.4.1-py3-none-any.whl
| Download URL | plain_text_memory_mcp-0.4.1-py3-none-any.whl |
|---|---|
| Size | 53.0 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
5f7024b47f0b4bf1288a52561b2d0b1b1f2c2c7f6a656fbb80d89b785c1478f9
|
|
BLAKE2b-256 checksum How to use checksums |
831d2742c680ad6c017eb7d1557396fadfed202bf9c32be855573b0fd8949338
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 19, 2026.
Transparency logSecurity for plain-text-memory-mcp 0.4.1
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for plain_text_memory_mcp-0.4.1.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 19, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.