plain-text-memory-mcp 0.1.0__tar.gz

plain_text_memory_mcp-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Plain Text Office LLC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

plain_text_memory_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,215 @@
+Metadata-Version: 2.4
+Name: plain-text-memory-mcp
+Version: 0.1.0
+Summary: Knowledge-graph memory MCP server that tags entries with date and agent
+Author: Plain Text Office LLC
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/PlainTxtOffice/plain-text-memory-mcp
+Project-URL: Issues, https://github.com/PlainTxtOffice/plain-text-memory-mcp/issues
+Keywords: mcp,model-context-protocol,memory,knowledge-graph,claude-code,codex
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: mcp<3,>=2.2
+Dynamic: license-file
+
+# plain-text-memory-mcp
+
+Knowledge-graph memory MCP server that tags every entry with the date it was
+added and the agent that added it. Memory lives in a plain JSONL file inside
+each repo, so every agent working in that repo shares it.
+
+It is a drop-in replacement for `@modelcontextprotocol/server-memory`: the
+same nine tools and input keys, and it reads files written by the original
+server. It adds `initialize_memory` and `export_taxonomy`, the `cleanup` and
+`export` prompts, and the `memory://taxonomy` resource.
+
+## Install
+
+The server runs with [uv](https://docs.astral.sh/uv/); `uvx` downloads and
+starts it on demand, so there is nothing else to install.
+
+```shell
+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, or set
+`MEMORY_FILE_PATH` if a client starts servers somewhere else.
+
+Claude Code, `.mcp.json` in the repo:
+
+```json
+{
+  "mcpServers": {
+    "plain-text-memory": {
+      "type": "stdio",
+      "command": "uvx",
+      "args": ["plain-text-memory-mcp"]
+    }
+  }
+}
+```
+
+Codex, `.codex/config.toml`:
+
+```toml
+[mcp_servers.plain-text-memory]
+command = "uvx"
+args = ["plain-text-memory-mcp"]
+```
+
+Cursor, `.cursor/mcp.json` in the repo:
+
+```json
+{
+  "mcpServers": {
+    "plain-text-memory": {
+      "command": "uvx",
+      "args": ["plain-text-memory-mcp"]
+    }
+  }
+}
+```
+
+VS Code, `.vscode/mcp.json` in the repo:
+
+```json
+{
+  "servers": {
+    "plain-text-memory": {
+      "type": "stdio",
+      "command": "uvx",
+      "args": ["plain-text-memory-mcp"]
+    }
+  }
+}
+```
+
+## Where memory is stored
+
+1. `MEMORY_FILE_PATH`, if set. A relative path resolves against the folder
+   the agent starts the server in.
+1. `<git root>/.agents/memory.local.jsonl`.
+1. `<start folder>/.agents/memory.local.jsonl` outside a git repo.
+
+Writes hold a lock on `memory.local.jsonl.lock` beside the memory file, so
+Claude Code and Codex can write to the same repo's memory at the same time
+without losing each other's changes. The file stays after the server exits;
+leave it in place.
+
+## Tags
+
+Every entity, relation, and observation carries `added_at` (local time with
+UTC offset) and `agent` (`claude-code`, `codex`, or the client's own name).
+Set `MEMORY_AGENT` to override the agent name. Entries written by the original
+server show `null` for both.
+
+## Repo guard
+
+The first write adds a header line recording which repo the memory file
+belongs to. If the file is later found in a different repo, for example after
+copying `.agents/` from a template, every tool returns an error instead of
+serving the other repo's memories. Resolve it with the `initialize_memory`
+tool:
+
+- `mode: "fresh"` renames the old file to `memory.local.jsonl.bak-<time>` and
+  starts an empty graph.
+- `mode: "adopt"` keeps the memories and points the header at this repo, for
+  a repo that was moved or renamed.
+
+Files without a header, including ones written by the original server, are
+claimed by the repo that writes to them first.
+
+## Prompts
+
+The server publishes two MCP prompts, which clients offer as commands; Claude
+Code shows them as `/mcp__plain-text-memory__cleanup` and
+`/mcp__plain-text-memory__export`.
+
+| Prompt | Use |
+| --- | --- |
+| `cleanup` | Propose deletions and merges; nothing is deleted until approved |
+| `export` | Write the repo's taxonomy and usage to `.agents/` and report it |
+
+## Guidance for agents
+
+On connect, the server sends every MCP client instructions for using memory
+well: search before planning, verify what memory says against the repo, save
+only lasting facts, and resolve the repo guard. Tool and parameter
+descriptions say what each tool does and returns, and the prompts above
+carry the cleanup and export workflows. No agent-specific setup is needed.
+
+## Taxonomy
+
+[taxonomy.json](src/plain_text_memory_mcp/taxonomy.json) lists every record
+type with its purpose and fields, every tool with its parameters and results,
+every MCP resource and prompt, and the allowed values for enum fields such
+as `agent` and `initialize_memory.mode`. 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, where the server's
+`export_taxonomy` tool reads it. MCP clients can also 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:
+
+```powershell
+.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:
+
+```powershell
+git config core.hooksPath .githooks
+```
+
+### Exporting to a repo
+
+Ask an agent to call the `export_taxonomy` tool. It writes
+`.agents/memory.local.taxonomy.jsonc` beside the repo's memory file, holding
+the versioned schema above plus this repo's usage: entry counts, the entity
+and relation types in use, and entries per agent. `//` comments explain each
+section and each record type's purpose. Use it to keep type names consistent
+within a repo. The export is local, like the memory file; ignore both with
+`.agents/*memory.local.*`.
+
+## Develop
+
+```powershell
+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:
+
+```powershell
+uv tool install -e .
+```
+
+Code changes then take effect the next time an agent starts the server.
+
+## License
+
+MIT, copyright Plain Text Office LLC. See [LICENSE](LICENSE).

plain_text_memory_mcp-0.1.0/README.md

@@ -0,0 +1,192 @@
+# plain-text-memory-mcp
+
+Knowledge-graph memory MCP server that tags every entry with the date it was
+added and the agent that added it. Memory lives in a plain JSONL file inside
+each repo, so every agent working in that repo shares it.
+
+It is a drop-in replacement for `@modelcontextprotocol/server-memory`: the
+same nine tools and input keys, and it reads files written by the original
+server. It adds `initialize_memory` and `export_taxonomy`, the `cleanup` and
+`export` prompts, and the `memory://taxonomy` resource.
+
+## Install
+
+The server runs with [uv](https://docs.astral.sh/uv/); `uvx` downloads and
+starts it on demand, so there is nothing else to install.
+
+```shell
+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, or set
+`MEMORY_FILE_PATH` if a client starts servers somewhere else.
+
+Claude Code, `.mcp.json` in the repo:
+
+```json
+{
+  "mcpServers": {
+    "plain-text-memory": {
+      "type": "stdio",
+      "command": "uvx",
+      "args": ["plain-text-memory-mcp"]
+    }
+  }
+}
+```
+
+Codex, `.codex/config.toml`:
+
+```toml
+[mcp_servers.plain-text-memory]
+command = "uvx"
+args = ["plain-text-memory-mcp"]
+```
+
+Cursor, `.cursor/mcp.json` in the repo:
+
+```json
+{
+  "mcpServers": {
+    "plain-text-memory": {
+      "command": "uvx",
+      "args": ["plain-text-memory-mcp"]
+    }
+  }
+}
+```
+
+VS Code, `.vscode/mcp.json` in the repo:
+
+```json
+{
+  "servers": {
+    "plain-text-memory": {
+      "type": "stdio",
+      "command": "uvx",
+      "args": ["plain-text-memory-mcp"]
+    }
+  }
+}
+```
+
+## Where memory is stored
+
+1. `MEMORY_FILE_PATH`, if set. A relative path resolves against the folder
+   the agent starts the server in.
+1. `<git root>/.agents/memory.local.jsonl`.
+1. `<start folder>/.agents/memory.local.jsonl` outside a git repo.
+
+Writes hold a lock on `memory.local.jsonl.lock` beside the memory file, so
+Claude Code and Codex can write to the same repo's memory at the same time
+without losing each other's changes. The file stays after the server exits;
+leave it in place.
+
+## Tags
+
+Every entity, relation, and observation carries `added_at` (local time with
+UTC offset) and `agent` (`claude-code`, `codex`, or the client's own name).
+Set `MEMORY_AGENT` to override the agent name. Entries written by the original
+server show `null` for both.
+
+## Repo guard
+
+The first write adds a header line recording which repo the memory file
+belongs to. If the file is later found in a different repo, for example after
+copying `.agents/` from a template, every tool returns an error instead of
+serving the other repo's memories. Resolve it with the `initialize_memory`
+tool:
+
+- `mode: "fresh"` renames the old file to `memory.local.jsonl.bak-<time>` and
+  starts an empty graph.
+- `mode: "adopt"` keeps the memories and points the header at this repo, for
+  a repo that was moved or renamed.
+
+Files without a header, including ones written by the original server, are
+claimed by the repo that writes to them first.
+
+## Prompts
+
+The server publishes two MCP prompts, which clients offer as commands; Claude
+Code shows them as `/mcp__plain-text-memory__cleanup` and
+`/mcp__plain-text-memory__export`.
+
+| Prompt | Use |
+| --- | --- |
+| `cleanup` | Propose deletions and merges; nothing is deleted until approved |
+| `export` | Write the repo's taxonomy and usage to `.agents/` and report it |
+
+## Guidance for agents
+
+On connect, the server sends every MCP client instructions for using memory
+well: search before planning, verify what memory says against the repo, save
+only lasting facts, and resolve the repo guard. Tool and parameter
+descriptions say what each tool does and returns, and the prompts above
+carry the cleanup and export workflows. No agent-specific setup is needed.
+
+## Taxonomy
+
+[taxonomy.json](src/plain_text_memory_mcp/taxonomy.json) lists every record
+type with its purpose and fields, every tool with its parameters and results,
+every MCP resource and prompt, and the allowed values for enum fields such
+as `agent` and `initialize_memory.mode`. 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, where the server's
+`export_taxonomy` tool reads it. MCP clients can also 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:
+
+```powershell
+.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:
+
+```powershell
+git config core.hooksPath .githooks
+```
+
+### Exporting to a repo
+
+Ask an agent to call the `export_taxonomy` tool. It writes
+`.agents/memory.local.taxonomy.jsonc` beside the repo's memory file, holding
+the versioned schema above plus this repo's usage: entry counts, the entity
+and relation types in use, and entries per agent. `//` comments explain each
+section and each record type's purpose. Use it to keep type names consistent
+within a repo. The export is local, like the memory file; ignore both with
+`.agents/*memory.local.*`.
+
+## Develop
+
+```powershell
+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:
+
+```powershell
+uv tool install -e .
+```
+
+Code changes then take effect the next time an agent starts the server.
+
+## License
+
+MIT, copyright Plain Text Office LLC. See [LICENSE](LICENSE).

plain_text_memory_mcp-0.1.0/pyproject.toml

@@ -0,0 +1,73 @@
+#:schema https://json.schemastore.org/pyproject.json
+
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "plain-text-memory-mcp"
+version = "0.1.0"
+description = "Knowledge-graph memory MCP server that tags entries with date and agent"
+readme = "README.md"
+requires-python = ">=3.12"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Plain Text Office LLC" }]
+keywords = [
+    "mcp",
+    "model-context-protocol",
+    "memory",
+    "knowledge-graph",
+    "claude-code",
+    "codex",
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development",
+]
+dependencies = ["mcp>=2.2,<3"]
+
+[project.urls]
+Homepage = "https://github.com/PlainTxtOffice/plain-text-memory-mcp"
+Issues = "https://github.com/PlainTxtOffice/plain-text-memory-mcp/issues"
+
+[project.scripts]
+plain-text-memory-mcp = "plain_text_memory_mcp.server:main"
+
+[dependency-groups]
+dev = ["pytest>=8"]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+plain_text_memory_mcp = ["taxonomy.json", "prompts/*.md"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["scripts"]
+
+
+[tool.mypy]
+exclude = ['(^|[\\/])tests([\\/]|$)']
+ignore_missing_imports = true
+[tool.ruff]
+line-length = 80
+
+[tool.rumdl]
+line-length = 80
+respect-gitignore = true
+exclude = [".venv", "build", "dist"]
+
+[tool.rumdl.MD029]
+style = "one"
+
+[tool.rumdl.MD013]
+code-blocks = false
+tables = false

plain_text_memory_mcp-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

plain_text_memory_mcp-0.1.0/src/plain_text_memory_mcp/__init__.py

@@ -0,0 +1 @@
+"""Knowledge-graph memory MCP server with date and agent tags."""

plain_text_memory_mcp-0.1.0/src/plain_text_memory_mcp/agent.py

@@ -0,0 +1,24 @@
+"""Name the agent that is calling the memory server."""
+
+UNKNOWN_AGENT = "unknown"
+
+KNOWN_AGENTS = (("claude", "claude-code"), ("codex", "codex"))
+
+
+def calc_agent_name(client_name: str | None, override: str | None) -> str:
+    """Return the agent name recorded in memory tags.
+
+    - A non-blank override, from `MEMORY_AGENT`, always wins.
+    - Client names containing "claude" or "codex" map to `claude-code` and
+      `codex`; any other name is recorded as sent.
+    - A missing or blank client name records `unknown`.
+    """
+    if override and override.strip():
+        return override.strip()
+    if not client_name or not client_name.strip():
+        return UNKNOWN_AGENT
+    lowered = client_name.lower()
+    for marker, agent_name in KNOWN_AGENTS:
+        if marker in lowered:
+            return agent_name
+    return client_name.strip()