OpenMyMemo — agent guide

A local-first, open-source AI memory folder with an approval panel. docs/product-design.md is the product definition; if an implementation would contradict it, update the design doc first (§12 and §13 record where v0.1 and v0.2 differ from earlier plans).

Non-negotiables

• Local only: no cloud storage, sync, accounts or telemetry, except the optional OpenMyMemo Cloud connector (product-design.md §16), which does nothing until the person signs in and never holds memory in readable form at rest unless the person also turns on MyMemo Memory sync (product-design.md §20): a separate consent, shown with what MyMemo stores, who can read it and how to delete it. Sync never sends a private topic the person didn't pick, and when the folder and MyMemo disagree, the folder wins. The server listens on 127.0.0.1 only. Memory text leaves the computer only when the person turns the OpenMyMemo Assistant on with a remote model, and only to that model (product-design.md §17), or turns on MyMemo Memory sync, and only to MyMemo (§20); a model on this computer keeps everything on the computer, and private topics never go to a remote model.
• All user data is plain text: memories/*.md is the source of truth for memory content; metadata, history, activity, proposals and settings under .openmymemo/ are plain text too. Don't introduce a database.
• Every AI write goes through a proposal (proposals.py) and never edits files directly. A change that applies without the user (the default, or a connector set to auto) must stay undoable, must never write into a private topic, and must never silently change a memory the user wrote last (last_actor); the table in product-design.md §5.5 is normative. MyMemo Memory sync (product-design.md §20) follows the same rule: what MyMemo's AI features and web apps propose arrives as proposals from cloud-* connectors and is decided here; only the person's own edits on MyMemo's memory page are applied directly, as their own edits (actor: user).
• Works with zero external dependencies: anything that needs a model endpoint is optional and degrades instead of failing.
• No dependency on MyMemo services, accounts or databases. The OpenMyMemo Cloud connector is the one optional piece that talks to MyMemo (the relay and, with the person's consent, MyMemo Memory sync); everything else works without it, and removing it changes nothing else. Code and UI patterns may be borrowed from MyMemo's own apps; other runtime coupling may not.
• Don't weaken the panel API guard (guard in web.py: Host, Origin, X-OpenMyMemo header) or the /mcp token check.

Commands

uv sync
uv run pytest                               # all tests, including MCP end to end over stdio and real HTTP
uv run ruff check src tests scripts
uv run openmymemo --vault /tmp/v init       # CLI
uv run python scripts/demo_vault.py /tmp/d  # demo data
cd web && pnpm install && pnpm build        # panel → src/openmymemo/static/ (commit the build output)
cd web && pnpm test                         # panel tests (vitest)
cd desktop && pnpm install && pnpm tauri dev # Mac app (needs Rust); `pnpm tauri build` for the .app
python3 scripts/stage_desktop.py && (cd desktop/src-tauri && cargo test)  # Mac or Windows app tests (`python` on Windows)

Code map

Conventions

• Everything user-facing is English: docs, panel copy, CLI output, MCP tool names and descriptions. Chinese belongs only in data handling (classifier keywords, parsing pasted pages, test fixtures), because users' memories may be in Chinese.
• File formats (memories/*.md, connectors.yaml, .openmymemo/*) are a public contract specified in docs/MEMORY_FORMAT.md: change the spec first and keep reading older files.
• Topic slugs are the file names; titles come from the files.
• All writes go through Vault methods, which lock, re-read from disk, write atomically and update meta and history.
• The mcp SDK is 2.x: from mcp.server.mcpserver import MCPServer, Context; static resources can't take a Context.
• Plugins run uv run from the installed copy of this repo, so anything the package needs at runtime must be inside the repo (and inside the .mcpb staging list in scripts/build_mcpb.py). Keep the version in pyproject.toml, src/openmymemo/__init__.py, both plugin.json files, server.json (the MCP Registry entry, both of its versions), the .mcpb manifest, web/package.json, the Mac app (desktop/package.json, desktop/src-tauri/tauri.conf.json, desktop/src-tauri/Cargo.toml) and the version line at the top of README.md in sync (tests/test_packaging.py checks), and run uv lock after a bump.
• CI (.github/workflows/ci.yml) is three jobs, one per runner: the Python tests and lint on Linux (Python 3.11 and 3.13), the Python tests and the Mac app's tests on macOS (Python 3.12), and the panel (its tests, and that the committed build matches web/) with packing the .mcpb. The main ruleset requires these three checks by name, so renaming a job means updating it. To release: bump the version, merge, then push a tag v<version>; .github/workflows/release.yml publishes the .mcpb, wheel and sdist as a GitHub release, the wheel and sdist on PyPI (trusted publishing, environment pypi), and then server.json on the MCP Registry (GitHub OIDC; the registry checks the mcp-name: line in README.md, so keep it).
• Don't add a root .mcp.json: Claude Code would treat it as project config for everyone working on this repo. The Claude Code MCP server is declared inline in .claude-plugin/plugin.json.
• Commit messages are imperative English; one topic per PR.
• OpenMyMemo Cloud (called MyMemo Cloud until its launch on 2026-10-19; the id stays mymemo-cloud) is listed by default and does nothing until the person signs in; it can be hidden in Settings (or openmymemo cloud settings --hide) and is always listed while linked (product-design.md §16.11). settings.json is format 2: an older file's show is ignored, because 0.2.8 and older wrote "show": false as their default. Only the live relay is launched: cloud.FEATURES stays empty, so hello() doesn't advertise queue, and nothing user-facing may promise the offline queue until both sides turn it on; cloud.queue_enabled() (the same constant) keeps welcome.queued and a plan's queue out of the panel and the CLI, leaves item frames unfiled and unacknowledged, and the queue wording out of the relayed tool descriptors (tests/fixtures/cloud/bridge/hello.json). It reads OPENMYMEMO_CLOUD_URL (the service; overrides the one chosen in Settings, default https://api.mymemo.ai) and OPENMYMEMO_CLOUD_DIR (the folder of cloud.json and settings.json). tests/conftest.py gives every test its own HOME, cloud folder and a local URL; set both yourself before trying openmymemo cloud … or the panel's sign-in by hand, so nothing touches your real link or MyMemo.
• MyMemo Memory sync (product-design.md §20, sync.py) is off until the person turns it on, a consent of its own on a linked computer; hello() lists sync only then (read from sync.json at each connection, so cloud.FEATURES and queue_enabled() are unchanged), and turning it on or off makes the bridge say hello again. Its state is sync.json next to cloud.json, bound to the link's device, and never holds memory text. What comes from MyMemo is filed through proposals.py as cloud-* connectors, except the person's own edits on MyMemo's memory page (from: "user"), which are applied as theirs after a version check. Tests drive it with FakeSync in tests/cloud_fake.py; the frames are pinned by tests/fixtures/cloud/sync/, byte-identical in the MyMemo service (tests/test_sync.py checks the folder's digest).
• The OpenMyMemo Assistant is off until turned on in Settings → Assistant or with openmymemo assistant set. Code that uses it builds Assistant.from_settings(vault), checks available(feature), calls json_call with material in Data blocks (never mixed into the instructions; memories through assistant.memory_data(...), topic lists from assistant.topic_choices(), both of which leave out what may not be sent; guard.py refuses anything else that would leak) and falls back to the rule path on None; it writes only through Assistant.propose. Tests use a fake endpoint (openmymemo.assistant.client.TRANSPORT, an httpx2.MockTransport); tests/conftest.py keeps the Keychain and the shell's OPENMYMEMO_ASSISTANT_* variables out.
• Search by meaning is optional twice over: the local model is opt-in (Settings → Assistant → "Search by meaning on this computer", openmymemo semantic on), downloaded on demand, never bundled; onnxruntime and tokenizers are the semantic extra, never default dependencies. A model is downloadable only once its files are pinned in src/openmymemo/recall/model_pins.json by scripts/pin_embedding_models.py. Tests never download: tests/recall/recall_harness.py has a deterministic stand-in embedder and replays recorded model answers; tests/recall/ is the recall test set (hit@k must not fall below baseline.json).
• The Mac app adds nothing to the panel's API: it is the same panel in another layout. New panel features go into the web screens; give the Mac layout its own version only where the design has one. A native command the panel calls must be listed in desktop/src-tauri/build.rs and granted in capabilities/default.json, because the panel is a remote origin to Tauri.