keepm 0.2.0__py3-none-any.whl

keepm/storage.py

@@ -0,0 +1,66 @@
+from __future__ import annotations
+
+import os
+import time
+from pathlib import Path
+
+from keepm.config import KeepMConfig
+
+
+class MemoryStorage:
+    def __init__(self, config: KeepMConfig) -> None:
+        self.config = config
+
+    def require_safe_path(self, path: Path) -> Path:
+        resolved = path.expanduser().resolve()
+        root = self.config.memory_root.resolve()
+        if resolved == root or not resolved.is_relative_to(root):
+            raise ValueError(f"path is outside Memory root: {path}")
+        return resolved
+
+    def path_for(self, *, scope: str, filename: str) -> Path:
+        if Path(filename).name != filename or not filename.endswith(".md"):
+            raise ValueError("filename must be a Markdown basename")
+        root = (
+            self.config.global_root
+            if scope == "global"
+            else self.config.projects_root / scope
+        )
+        root.mkdir(parents=True, exist_ok=True)
+        return self.require_safe_path(root / filename)
+
+    def discover(self) -> tuple[Path, ...]:
+        if not self.config.memory_root.exists():
+            return ()
+        paths: set[Path] = set()
+        for path in self.config.memory_root.rglob("*.md"):
+            relative = path.relative_to(self.config.memory_root)
+            if any(part.startswith(".") for part in relative.parts):
+                continue
+            try:
+                paths.add(self.require_safe_path(path))
+            except ValueError:
+                continue
+        return tuple(sorted(paths))
+
+    def atomic_write(self, path: Path, content: str) -> Path:
+        target = self.require_safe_path(path)
+        target.parent.mkdir(parents=True, exist_ok=True)
+        temporary = target.with_name(f".{target.name}.{os.getpid()}.tmp")
+        try:
+            with temporary.open("w", encoding="utf-8", newline="\n") as handle:
+                handle.write(content)
+                handle.flush()
+                os.fsync(handle.fileno())
+            os.replace(temporary, target)
+        finally:
+            temporary.unlink(missing_ok=True)
+        return target
+
+    def soft_delete(self, path: Path) -> Path:
+        source = self.require_safe_path(path)
+        stamp = time.strftime("%Y%m%d-%H%M%S")
+        destination = self.config.trash_root / f"{stamp}-{time.time_ns()}-{source.name}"
+        destination.parent.mkdir(parents=True, exist_ok=True)
+        os.replace(source, destination)
+        return destination

keepm/sync.py

@@ -0,0 +1,230 @@
+from __future__ import annotations
+
+import datetime as dt
+import hashlib
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from keepm.database import FileState, MemoryDatabase
+from keepm.markdown import parse_memory
+from keepm.models import MemoryDocument, SyncReport
+from keepm.storage import MemoryStorage
+
+
+def sha256_file(path: Path) -> str:
+    digest = hashlib.sha256()
+    with path.open("rb") as handle:
+        for chunk in iter(lambda: handle.read(1024 * 1024), b""):
+            digest.update(chunk)
+    return digest.hexdigest()
+
+
+def file_metadata(path: Path) -> tuple[int, int]:
+    stat = path.stat()
+    return stat.st_mtime_ns, stat.st_size
+
+
+@dataclass(slots=True)
+class _Counts:
+    new: int = 0
+    modified: int = 0
+    deleted: int = 0
+    moved: int = 0
+    unchanged: int = 0
+    errors: list[str] = field(default_factory=list)
+
+    def report(self) -> SyncReport:
+        return SyncReport(
+            new=self.new,
+            modified=self.modified,
+            deleted=self.deleted,
+            moved=self.moved,
+            unchanged=self.unchanged,
+            errors=tuple(self.errors),
+        )
+
+
+class SyncEngine:
+    def __init__(self, storage: MemoryStorage, database: MemoryDatabase) -> None:
+        self.storage = storage
+        self.database = database
+
+    @property
+    def memory_root(self) -> Path:
+        return self.storage.config.memory_root.resolve()
+
+    def _expected_scope(self, path: Path) -> str:
+        relative = path.resolve().relative_to(self.memory_root)
+        if len(relative.parts) >= 2 and relative.parts[0] == "global":
+            return "global"
+        if len(relative.parts) >= 3 and relative.parts[0] == "projects":
+            return relative.parts[1]
+        raise ValueError(f"{path}: Markdown file is outside a global/project scope")
+
+    def _parse(self, path: Path) -> MemoryDocument:
+        document = parse_memory(path, path.read_text(encoding="utf-8"))
+        expected_scope = self._expected_scope(path)
+        if document.scope != expected_scope:
+            raise ValueError(
+                f"{path}: scope {document.scope!r} does not match directory "
+                f"scope {expected_scope!r}"
+            )
+        return document
+
+    def _record_error(
+        self,
+        path: Path,
+        error: Exception,
+        *,
+        mtime_ns: int,
+        size: int,
+        counts: _Counts,
+    ) -> None:
+        message = str(error)
+        self.database.mark_error(path, message, mtime_ns=mtime_ns, size=size)
+        counts.errors.append(message)
+
+    def _reconcile_existing(
+        self,
+        path: Path,
+        *,
+        state: FileState | None,
+        states_by_id: dict[str, FileState],
+        known_files: set[Path],
+        error_state: tuple[int, int] | None,
+        counts: _Counts,
+        moved_from: set[Path],
+    ) -> None:
+        try:
+            mtime_ns, size = file_metadata(path)
+        except OSError as error:
+            counts.errors.append(f"{path}: {error}")
+            return
+
+        if state and (state.mtime_ns, state.size) == (mtime_ns, size):
+            counts.unchanged += 1
+            return
+        if error_state == (mtime_ns, size):
+            counts.unchanged += 1
+            return
+
+        try:
+            checksum = sha256_file(path)
+        except OSError as error:
+            self._record_error(
+                path, error, mtime_ns=mtime_ns, size=size, counts=counts
+            )
+            return
+
+        if state and state.checksum == checksum:
+            self.database.update_file_metadata(path, mtime_ns=mtime_ns, size=size)
+            counts.unchanged += 1
+            return
+
+        try:
+            document = self._parse(path)
+            prior = states_by_id.get(document.id)
+            if prior and prior.path != path:
+                if prior.path in known_files or prior.path.exists():
+                    raise ValueError(
+                        f"{path}: duplicate memory id {document.id!r} also exists at "
+                        f"{prior.path}"
+                    )
+                moved_from.add(prior.path)
+                classification = "moved"
+            elif state:
+                classification = "modified"
+            else:
+                classification = "new"
+            self.database.upsert(
+                document,
+                mtime_ns=mtime_ns,
+                size=size,
+                checksum=checksum,
+            )
+        except Exception as error:
+            self._record_error(
+                path, error, mtime_ns=mtime_ns, size=size, counts=counts
+            )
+            return
+
+        if classification == "moved":
+            counts.moved += 1
+        elif classification == "modified":
+            counts.modified += 1
+        else:
+            counts.new += 1
+
+    def _finish(self, counts: _Counts) -> SyncReport:
+        self.database.set_state(
+            "last_reconcile", dt.datetime.now(dt.timezone.utc).isoformat()
+        )
+        return counts.report()
+
+    def quick_reconcile(self) -> SyncReport:
+        paths = set(self.storage.discover())
+        states = self.database.file_states()
+        states_by_id = {state.id: state for state in states.values()}
+        error_states = self.database.index_error_states()
+        counts = _Counts()
+        moved_from: set[Path] = set()
+
+        for path in sorted(paths):
+            self._reconcile_existing(
+                path,
+                state=states.get(path),
+                states_by_id=states_by_id,
+                known_files=paths,
+                error_state=error_states.get(path),
+                counts=counts,
+                moved_from=moved_from,
+            )
+
+        indexed_or_error_paths = set(states) | set(error_states)
+        for missing in sorted(indexed_or_error_paths - paths - moved_from):
+            self.database.delete_path(missing)
+            counts.deleted += 1
+        return self._finish(counts)
+
+    def reconcile_paths(self, paths: tuple[Path, ...] | list[Path]) -> SyncReport:
+        eligible: set[Path] = set()
+        counts = _Counts()
+        for candidate in paths:
+            try:
+                path = self.storage.require_safe_path(Path(candidate))
+                relative = path.relative_to(self.memory_root)
+            except (OSError, ValueError) as error:
+                counts.errors.append(str(error))
+                continue
+            if (
+                path.suffix.lower() != ".md"
+                or any(part.startswith(".") for part in relative.parts)
+                or path.name.startswith(".")
+                or path.name.endswith((".tmp", "~"))
+            ):
+                continue
+            eligible.add(path)
+
+        states = self.database.file_states()
+        states_by_id = {state.id: state for state in states.values()}
+        error_states = self.database.index_error_states()
+        existing = {path for path in eligible if path.is_file()}
+        moved_from: set[Path] = set()
+        for path in sorted(existing):
+            self._reconcile_existing(
+                path,
+                state=states.get(path),
+                states_by_id=states_by_id,
+                known_files=existing,
+                error_state=error_states.get(path),
+                counts=counts,
+                moved_from=moved_from,
+            )
+        for missing in sorted(eligible - existing - moved_from):
+            if self.database.delete_path(missing) or missing in error_states:
+                counts.deleted += 1
+        return self._finish(counts)
+
+    def full_rebuild(self) -> SyncReport:
+        self.database.clear()
+        return self.quick_reconcile()

keepm/watcher.py

@@ -0,0 +1,113 @@
+from __future__ import annotations
+
+import asyncio
+import contextlib
+from collections.abc import AsyncIterator, Callable, Iterable
+from pathlib import Path
+from typing import Any
+
+from keepm.config import KeepMConfig
+from keepm.sync import SyncEngine
+
+try:
+    from watchfiles import awatch as _awatch
+except ImportError:  # Covered by runtime diagnostics when dependencies are absent.
+    _awatch = None
+
+
+def filter_watch_paths(root: Path, paths: Iterable[Path]) -> tuple[Path, ...]:
+    resolved_root = root.expanduser().resolve()
+    accepted: set[Path] = set()
+    for candidate in paths:
+        resolved = Path(candidate).expanduser().resolve()
+        if resolved == resolved_root or not resolved.is_relative_to(resolved_root):
+            continue
+        relative = resolved.relative_to(resolved_root)
+        if any(part.startswith(".") for part in relative.parts):
+            continue
+        if resolved.suffix.lower() != ".md":
+            continue
+        if resolved.name.endswith(("~", ".tmp", ".swp", ".swx")):
+            continue
+        accepted.add(resolved)
+    return tuple(sorted(accepted))
+
+
+ChangeSource = Callable[..., AsyncIterator[set[tuple[Any, str]]]]
+
+
+class WatcherService:
+    def __init__(
+        self,
+        config: KeepMConfig,
+        sync_engine: SyncEngine,
+        *,
+        change_source: ChangeSource | None = None,
+    ) -> None:
+        self.config = config
+        self.sync_engine = sync_engine
+        self._change_source = change_source
+        self._stop_event = asyncio.Event()
+        self._task: asyncio.Task[None] | None = None
+        self.last_error: str | None = None
+
+    @property
+    def running(self) -> bool:
+        return self._task is not None and not self._task.done()
+
+    async def _changes(self) -> AsyncIterator[set[tuple[Any, str]]]:
+        if self._change_source is not None:
+            async for changes in self._change_source(
+                self.config.memory_root,
+                debounce=250,
+                step=50,
+                stop_event=self._stop_event,
+            ):
+                yield changes
+            return
+        if _awatch is None:
+            raise RuntimeError(
+                "watchfiles is not installed; reconciliation remains available"
+            )
+        async for changes in _awatch(
+            self.config.memory_root,
+            debounce=250,
+            step=50,
+            stop_event=self._stop_event,
+        ):
+            yield changes
+
+    async def _run(self) -> None:
+        try:
+            async for changes in self._changes():
+                paths = filter_watch_paths(
+                    self.config.memory_root,
+                    (Path(raw_path) for _, raw_path in changes),
+                )
+                if paths:
+                    self.sync_engine.reconcile_paths(paths)
+        except asyncio.CancelledError:
+            raise
+        except Exception as error:
+            self.last_error = str(error)
+
+    async def start(self) -> None:
+        if self.running:
+            return
+        self.last_error = None
+        self._stop_event = asyncio.Event()
+        self._task = asyncio.create_task(self._run(), name="keepm-watcher")
+
+    async def stop(self) -> None:
+        task = self._task
+        if task is None:
+            return
+        self._stop_event.set()
+        try:
+            await asyncio.wait_for(asyncio.shield(task), timeout=2.0)
+        except TimeoutError:
+            task.cancel()
+            with contextlib.suppress(asyncio.CancelledError):
+                await task
+        finally:
+            self._task = None

keepm-0.2.0.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,22 @@
+keepm/__init__.py,sha256=Zn1KFblwuFHiDRdRAiRnDBRkbPttWh44jKa5zG2ov0E,22
+keepm/cli.py,sha256=50lCYJkHHauP9qVXx83bezwDeox7jckg2W4eB8A0YPs,490
+keepm/config.py,sha256=N-1WjdZ6XJ4seJWiQjMBpjKl7vxCJTPgt4eQUvFWdAA,3268
+keepm/database.py,sha256=hwUezvajqc_ZIetsGM6EjRtlhy3uLwVw9uHiqNiv4ns,21529
+keepm/doctor.py,sha256=s7gqcN0aVEhu7HwFbCiM8uG8ofNGKPC8cYzAotS5QcA,4631
+keepm/instructions.py,sha256=VEk_5gMiSjvS7pig0b7y9MmaI2xEXq6vWg7avKPx-JY,10124
+keepm/integrations.py,sha256=QKAaAnAogW2sp6WGBx9I1xk8ZiJ5M1ZcbRvcSqmxLgg,10341
+keepm/markdown.py,sha256=ZeBAETPoT1z3EtsZ-cG2-6qshU_7DrLriO3YpH1vP1Q,5177
+keepm/models.py,sha256=UAAstgvHyruvF8WYx9qbyW7u93v_iUbhjj1Ry8394nE,911
+keepm/projects.py,sha256=vJtehpw5ri-f0AMcCCS7c9r0aV1A0Ufv00crbM7RTxk,1858
+keepm/server.py,sha256=A5aEjObKxl9mewmURSLj_t0cCZWi-ZAz1FJd8f9knQA,16320
+keepm/service.py,sha256=qLJTlnv6Ams-1YA6l27dCIRvpyEQ2sHLL0HTozH0Gt8,11109
+keepm/setup.py,sha256=9J6CTCpXx66_cUTYgQkn2nyMrYMbHZxJ19TnSLb1ooE,14910
+keepm/storage.py,sha256=KZWotca2dE7iZJHJucm1Pio7s0Mvn6u4SA9upmVZnq8,2455
+keepm/sync.py,sha256=JXgooFx6Sv1Z35t5iK02T1uSew8YO_OJ63LgMmFkX-8,7664
+keepm/watcher.py,sha256=soGdL-FHCAqlR1QQPRtsChbBjgc9GF0Ak_K7gWdexzY,3597
+keepm-0.2.0.dist-info/licenses/LICENSE,sha256=vmAY006NBQjCY34U3ZOt5kdawMHzWV2_pORX6iT1sRc,1093
+keepm-0.2.0.dist-info/METADATA,sha256=bmG8sF2nw9xqScsQ5EUKxQad8G7hRKe8mJGpUTeDIwg,443
+keepm-0.2.0.dist-info/WHEEL,sha256=K260EYznzXsJYBQGqmI8VTxEdiZYNvDZwW9cBh9-_MA,91
+keepm-0.2.0.dist-info/entry_points.txt,sha256=zwJJeT9R8SlRRrNTj5Bla0osXjSw9ssQksITc4idbRs,41
+keepm-0.2.0.dist-info/top_level.txt,sha256=aPACTlmnIV7jjD0wNea34jEJCdT6WDHMPeHgSTfVmGc,6
+keepm-0.2.0.dist-info/RECORD,,

keepm-0.2.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (83.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

keepm-0.2.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+keepm = keepm.cli:main

keepm-0.2.0.dist-info/licenses/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.dist-info/top_level.txt

@@ -0,0 +1 @@
+keepm