keepm 0.2.0__tar.gz

keepm-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Beijing Tinqiao Technology Co., Ltd.
+
+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.

keepm-0.2.0/PKG-INFO

@@ -0,0 +1,15 @@
+Metadata-Version: 2.4
+Name: keepm
+Version: 0.2.0
+Summary: Local Markdown memory MCP for coding agents
+Requires-Python: >=3.11
+License-File: LICENSE
+Requires-Dist: fastmcp<4,>=3
+Requires-Dist: PyYAML<7,>=6
+Requires-Dist: questionary<3,>=2
+Requires-Dist: tomlkit<1,>=0.13
+Requires-Dist: watchfiles<2,>=1
+Provides-Extra: dev
+Requires-Dist: pytest<9,>=8; extra == "dev"
+Requires-Dist: pytest-asyncio<2,>=0.24; extra == "dev"
+Dynamic: license-file

keepm-0.2.0/README.md

@@ -0,0 +1,161 @@
+# KeepM
+
+KeepM is a local Markdown memory MCP for coding agents. It stores long-term memories in one Obsidian Vault, separates global and project-specific knowledge, and exposes bounded search, context, and WikiLink tools over MCP stdio.
+
+[中文文档](README-zh.md)
+
+Markdown is the only source of truth. A local SQLite FTS5 database is a disposable index for keyword search, checksums, project scopes, WikiLinks, and backlinks. KeepM has no embeddings, vector database, cloud service, HTTP server, or required Obsidian plugin. Obsidian may remain closed.
+
+## Requirements
+
+- Python 3.11 or newer
+- [uv](https://docs.astral.sh/uv/) for the recommended `uvx` installation flow
+- One local Obsidian Vault
+- A local filesystem path visible to KeepM
+
+WSL can use a Windows Vault directly, for example:
+
+```text
+/mnt/c/Users/alice/Documents/ObsidianVault
+```
+
+## Install and setup
+
+After KeepM is published to PyPI, the normal installation is one command:
+
+```bash
+uvx keepm setup
+```
+
+The setup wizard asks for an existing local Obsidian Vault and a `zh` or `en` memory language, creates `<Vault>/Memory/`, detects Codex and Claude Code, then registers exactly one selected Agent. The selected Agent can use either scope:
+
+Interactive setup uses a colored terminal UI: use `↑` / `↓` and Enter to select the language, one Agent, and its scope. The current pointer is bright green. Vault paths remain text input. For non-interactive automation use `--yes --agent codex|claude` and optionally `--scope user|project`; if only one Agent is installed, `--agent` may be omitted. Running interactive setup without a TTY is rejected with a clear message.
+
+| Agent | User scope | Project scope |
+|---|---|---|
+| Codex | `~/.codex/config.toml` | `<project>/.codex/config.toml` |
+| Claude Code | `~/.claude.json` | `<project>/.mcp.json` |
+
+For every successful registration, setup installs the automatic memory protocol at the same scope:
+
+| Agent | User instructions | Project instructions |
+|---|---|---|
+| Codex | `~/.codex/AGENTS.md` | `<project>/AGENTS.md` |
+| Claude Code | `~/.claude/CLAUDE.md` | `<project>/CLAUDE.md` |
+
+The protocol tells the Agent to load relevant context at task start and write only durable preferences, feedback, decisions, constraints, and reusable fixes before completion. KeepM owns only the section between `<!-- keepm:start -->` and `<!-- keepm:end -->`: rerunning setup replaces that section without duplicating it or changing surrounding instructions. Malformed or duplicate markers are reported and never forced. A KeepM block written by an older version to `<project>/.claude/CLAUDE.md` is removed from that old location and migrated to the canonical project-root `CLAUDE.md`; unrelated old-file content is preserved.
+
+The scope only decides where an Agent can start KeepM. Every registration uses the same MCP command, `uvx --from keepm keepm`, and therefore the same Vault and `Memory/` tree. The wizard never silently replaces another MCP named `keepm`: an equal configuration is kept, while a different one must be replaced explicitly, skipped, or cancelled. Use `--force` only for non-interactive deliberate replacement.
+
+KeepM's own single-Vault configuration is stored at `~/.config/keepm/config.toml`, including `language = "zh"` or `language = "en"`; SQLite indexes are stored separately at `~/.local/share/keepm/indexes/`. Neither is a Codex or Claude Code configuration file. The language controls the managed instruction block and the default prose language of new memories. Existing memories are not translated, and technical names may remain in their original language.
+
+For source development in this repository:
+
+```bash
+uv sync --extra dev
+uv run keepm setup
+```
+
+`keepm` with no subcommand always starts only the MCP stdio server. It never opens the setup wizard or writes conversational output to MCP stdout. `memory_configure` remains available for Agent-driven reconfiguration when needed.
+
+## Vault Layout
+
+```text
+<Vault>/
+└── Memory/
+    ├── global/
+    │   └── verify-before-done.md
+    ├── projects/
+    │   ├── keepm/
+    │   ├── mizupanel/
+    │   └── comet/
+    └── .trash/
+```
+
+- `global/` applies across projects.
+- `projects/<project>/` contains project-specific memories.
+- `.trash/` contains soft-deleted notes and is not indexed.
+- Nested folders inside a scope are allowed.
+- No `MEMORY.md` file is created or maintained.
+
+The project name comes from the MCP client workspace, then `.keepm.toml`, Git origin, or the workspace directory name. A repository can override it:
+
+```toml
+# <repository>/.keepm.toml
+project = "keepm-v2"
+```
+
+When a project and global memory have the same logical `name`, the project memory wins.
+
+## Memory Format
+
+```markdown
+---
+id: 01JXYZEXAMPLE
+name: storage-design
+description: KeepM local storage decision
+type: project
+scope: keepm
+tags: [storage, obsidian]
+pinned: true
+created: 2026-07-17
+updated: 2026-07-17
+---
+
+Markdown remains authoritative; SQLite is rebuilt from these files.
+
+**Why:** The user can inspect and edit every memory.
+
+**How to apply:** Write Markdown first, then update the derived index.
+
+## Relations
+
+- depends_on [[Local First]]
+- integrates_with [[Obsidian]]
+```
+
+Required types are `user`, `feedback`, `project`, and `reference`. `feedback` and `project` memories require `Why:` and `How to apply:` sections. `pinned: true` includes the compact description early in `memory_context`.
+
+## MCP Tools
+
+| Tool | Purpose |
+|---|---|
+| `memory_configure` | Store the Vault and language configuration and build the first index |
+| `memory_status` | Report configuration, project, watcher, index, and sync state |
+| `memory_context` | Return bounded pinned and query-relevant memories |
+| `memory_search` | Search global/project memories with FTS5 or escaped substring matching |
+| `memory_read` | Read one bounded memory plus its checksum by stable ID, logical name, or safe path |
+| `memory_write` | Atomically create or update Markdown and refresh SQLite |
+| `memory_delete` | Soft-delete a memory into `.trash` |
+| `memory_links` | Return forward WikiLinks and backlinks |
+| `memory_sync` | Run quick reconciliation or a full index rebuild |
+| `memory_doctor` | Diagnose Markdown/index consistency without changing memories |
+
+The setup-managed Agent protocol calls `memory_context` at task start, searches when needed, and reads only selected full memories. Before completion it writes only durable, non-sensitive knowledge. This keeps the entire Vault and routine task noise out of the model context and memory store.
+
+## Synchronization
+
+KeepM performs a metadata reconciliation at startup. Equal `mtime_ns` and size values are treated as unchanged without reading content. Suspected changes are hashed with SHA-256; only new or checksum-changed files are parsed and indexed.
+
+While the MCP is running, `watchfiles` batches Obsidian or filesystem changes and refreshes affected notes. The watcher is only a latency optimization. Startup and stale-index reconciliation repair missed Windows-to-WSL events.
+
+Writes use a flushed sibling temporary file followed by `os.replace`. `memory_read` returns the current checksum; passing it back as `expected_checksum` rejects an update if Obsidian changed the note after it was read. Deletes move Markdown to `.trash`; permanent deletion is not exposed.
+
+## Recovery
+
+1. Call `memory_status` to inspect watcher errors, the database path, and the last reconciliation.
+2. Call `memory_sync` with `full: false` after bulk external changes, watcher failure, or a suspected mismatch.
+3. Call `memory_doctor` to inspect invalid Markdown, duplicates, unresolved links, and divergence.
+4. Call `memory_sync` with `full: true` to clear and rebuild the derived index.
+
+The index is stored under `~/.local/share/keepm/indexes`, outside the Vault. Deleting it never deletes memories. A corrupt or incompatible database is preserved with a `.corrupt-<timestamp>` suffix and rebuilt from Markdown.
+
+## Development
+
+```bash
+python -m pip install -e '.[dev]'
+python -m pytest -q
+python -m keepm.server --help
+```
+
+The new MCP runtime does not import or migrate the legacy `.keepm-memory/` layout or bounded `MEMORY.md` pointer workflow automatically.

keepm-0.2.0/pyproject.toml

@@ -0,0 +1,29 @@
+[build-system]
+requires = ["setuptools>=69"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "keepm"
+version = "0.2.0"
+description = "Local Markdown memory MCP for coding agents"
+requires-python = ">=3.11"
+dependencies = [
+  "fastmcp>=3,<4",
+  "PyYAML>=6,<7",
+  "questionary>=2,<3",
+  "tomlkit>=0.13,<1",
+  "watchfiles>=1,<2",
+]
+
+[project.optional-dependencies]
+dev = ["pytest>=8,<9", "pytest-asyncio>=0.24,<2"]
+
+[project.scripts]
+keepm = "keepm.cli:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+pythonpath = ["src"]
+asyncio_mode = "auto"

keepm-0.2.0/setup.cfg

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

keepm-0.2.0/src/keepm/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.2.0"

keepm-0.2.0/src/keepm/cli.py

@@ -0,0 +1,18 @@
+from __future__ import annotations
+
+import sys
+from collections.abc import Sequence
+
+
+def main(argv: Sequence[str] | None = None) -> None:
+    """Dispatch the management CLI without contaminating MCP stdio mode."""
+    arguments = list(sys.argv[1:] if argv is None else argv)
+    if arguments[:1] == ["setup"]:
+        from keepm.setup import main as setup_main
+
+        setup_main(arguments[1:])
+        return
+
+    from keepm.server import main as server_main
+
+    server_main(arguments)

keepm-0.2.0/src/keepm/config.py

@@ -0,0 +1,97 @@
+from __future__ import annotations
+
+import json
+import os
+import tomllib
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Literal, cast
+
+
+MemoryLanguage = Literal["zh", "en"]
+
+
+def default_config_path() -> Path:
+    root = Path(os.environ.get("XDG_CONFIG_HOME", Path.home() / ".config"))
+    return root / "keepm" / "config.toml"
+
+
+def default_data_root() -> Path:
+    root = Path(os.environ.get("XDG_DATA_HOME", Path.home() / ".local" / "share"))
+    return root / "keepm"
+
+
+@dataclass(frozen=True, slots=True)
+class KeepMConfig:
+    vault_path: Path
+    memory_dir: str = "Memory"
+    stale_after_seconds: int = 30
+    language: MemoryLanguage = "en"
+
+    def __post_init__(self) -> None:
+        memory_path = Path(self.memory_dir)
+        if (
+            not self.memory_dir.strip()
+            or memory_path.is_absolute()
+            or ".." in memory_path.parts
+        ):
+            raise ValueError("memory_dir must be relative and remain inside the Vault")
+        if self.stale_after_seconds < 0:
+            raise ValueError("stale_after_seconds must be non-negative")
+        if self.language not in ("zh", "en"):
+            raise ValueError("language must be 'zh' or 'en'")
+        object.__setattr__(self, "vault_path", self.vault_path.expanduser().resolve())
+
+    @property
+    def memory_root(self) -> Path:
+        return self.vault_path / self.memory_dir
+
+    @property
+    def global_root(self) -> Path:
+        return self.memory_root / "global"
+
+    @property
+    def projects_root(self) -> Path:
+        return self.memory_root / "projects"
+
+    @property
+    def trash_root(self) -> Path:
+        return self.memory_root / ".trash"
+
+
+class ConfigStore:
+    def __init__(self, path: Path | None = None) -> None:
+        self.path = path or default_config_path()
+
+    def load(self) -> KeepMConfig:
+        if not self.path.is_file():
+            raise FileNotFoundError(f"KeepM is not configured: {self.path}")
+        data = tomllib.loads(self.path.read_text(encoding="utf-8"))
+        return KeepMConfig(
+            vault_path=Path(data["vault_path"]),
+            memory_dir=str(data.get("memory_dir", "Memory")),
+            stale_after_seconds=int(data.get("stale_after_seconds", 30)),
+            language=cast(MemoryLanguage, str(data.get("language", "en"))),
+        )
+
+    def load_optional(self) -> KeepMConfig | None:
+        try:
+            return self.load()
+        except FileNotFoundError:
+            return None
+
+    def save(self, config: KeepMConfig) -> KeepMConfig:
+        config.vault_path.mkdir(parents=True, exist_ok=True)
+        for path in (config.global_root, config.projects_root, config.trash_root):
+            path.mkdir(parents=True, exist_ok=True)
+        self.path.parent.mkdir(parents=True, exist_ok=True)
+        content = (
+            f"vault_path = {json.dumps(str(config.vault_path))}\n"
+            f"memory_dir = {json.dumps(config.memory_dir)}\n"
+            f"stale_after_seconds = {config.stale_after_seconds}\n"
+            f"language = {json.dumps(config.language)}\n"
+        )
+        temporary = self.path.with_suffix(".tmp")
+        temporary.write_text(content, encoding="utf-8", newline="\n")
+        os.replace(temporary, self.path)
+        return config