openmymemo 0.2.4__tar.gz

openmymemo-0.2.4/.agents/plugins/marketplace.json

@@ -0,0 +1,12 @@
+{
+  "name": "openmymemo",
+  "interface": { "displayName": "OpenMyMemo" },
+  "plugins": [
+    {
+      "name": "openmymemo",
+      "source": { "source": "local", "path": "./" },
+      "policy": { "installation": "AVAILABLE", "authentication": "ON_INSTALL" },
+      "category": "Productivity"
+    }
+  ]
+}

openmymemo-0.2.4/.claude-plugin/marketplace.json

@@ -0,0 +1,14 @@
+{
+  "name": "openmymemo",
+  "description": "OpenMyMemo: a local, user-owned AI memory for Claude Code.",
+  "owner": { "name": "MyMemo", "url": "https://github.com/MyMemoAI/openmymemo" },
+  "plugins": [
+    {
+      "name": "openmymemo",
+      "source": ".",
+      "description": "Start every session with your memory; what Claude writes shows up in a digest you can undo.",
+      "category": "productivity",
+      "tags": ["memory", "mcp", "local-first"]
+    }
+  ]
+}

openmymemo-0.2.4/.claude-plugin/plugin.json

@@ -0,0 +1,39 @@
+{
+  "name": "openmymemo",
+  "displayName": "OpenMyMemo",
+  "version": "0.2.4",
+  "description": "Your AI memory as a local folder you own. Claude starts each session with it and writes what it learns; you see every change and can undo it.",
+  "author": {
+    "name": "MyMemo",
+    "url": "https://github.com/MyMemoAI/openmymemo"
+  },
+  "homepage": "https://github.com/MyMemoAI/openmymemo",
+  "repository": "https://github.com/MyMemoAI/openmymemo",
+  "license": "Apache-2.0",
+  "keywords": [
+    "memory",
+    "local-first",
+    "mcp",
+    "privacy"
+  ],
+  "mcpServers": {
+    "openmymemo": {
+      "command": "uv",
+      "args": [
+        "run",
+        "--directory",
+        "${CLAUDE_PLUGIN_ROOT}",
+        "--frozen", "--no-dev",
+        "--quiet",
+        "openmymemo",
+        "mcp",
+        "--connector",
+        "claude-code",
+        "--init",
+        "--panel-port",
+        "8787"
+      ]
+    }
+  },
+  "hooks": "./integrations/claude-code/hooks/hooks.json"
+}

openmymemo-0.2.4/.github/dependabot.yml

@@ -0,0 +1,11 @@
+# Security fixes for Python and panel dependencies come from Dependabot security updates (repo setting).
+# This file only keeps the GitHub Actions used by the workflows up to date, in one monthly PR.
+version: 2
+updates:
+  - package-ecosystem: github-actions
+    directory: /
+    schedule:
+      interval: monthly
+    groups:
+      actions:
+        patterns: ["*"]

openmymemo-0.2.4/.github/workflows/ci.yml

@@ -0,0 +1,75 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
+# Three jobs, one per kind of runner: Linux tests the oldest and newest Python we support, macOS tests the
+# middle one together with the Mac app, and the panel job checks the committed build and packs the extension.
+jobs:
+  linux:
+    name: Python tests (Linux, 3.11 and 3.13)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: astral-sh/setup-uv@v7
+      - run: uv run --frozen --python 3.13 ruff check src tests scripts
+      - name: Tests on Python 3.11
+        run: uv run --frozen --python 3.11 pytest
+      - name: Tests on Python 3.13
+        run: uv run --frozen --python 3.13 pytest
+
+  macos:
+    name: macOS tests and Mac app (Python 3.12)
+    runs-on: macos-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: astral-sh/setup-uv@v7
+        with:
+          python-version: "3.12"
+      - run: uv run --frozen pytest
+      - run: python3 scripts/stage_desktop.py  # the bundled core and uv, which the Tauri build checks for
+      - run: cargo test --locked
+        working-directory: desktop/src-tauri
+
+  panel:
+    name: Panel build and extension
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: pnpm/action-setup@v6
+        with:
+          version: 10
+      - uses: actions/setup-node@v7
+        with:
+          node-version: 22
+          cache: pnpm
+          cache-dependency-path: web/pnpm-lock.yaml
+      - uses: astral-sh/setup-uv@v7
+      - run: pnpm install --frozen-lockfile
+        working-directory: web
+      - run: pnpm build  # type-checks with vue-tsc first
+        working-directory: web
+      - run: pnpm test
+        working-directory: web
+      - name: src/openmymemo/static matches web/
+        run: |
+          if [ -n "$(git status --porcelain src/openmymemo/static)" ]; then
+            git status --short src/openmymemo/static
+            echo "::error::The committed panel build is out of date. Run 'cd web && pnpm build' and commit src/openmymemo/static."
+            exit 1
+          fi
+      - run: uv run --frozen python scripts/build_mcpb.py  # validates the manifest
+      - uses: actions/upload-artifact@v7
+        with:
+          name: openmymemo-mcpb
+          path: dist/*.mcpb
+          if-no-files-found: error

openmymemo-0.2.4/.github/workflows/release.yml

@@ -0,0 +1,202 @@
+name: Release
+
+# Push a tag named after the version (v0.2.2) to publish the Mac app, the Claude Desktop extension and the
+# Python package as a GitHub release, the Python package on PyPI, and server.json on the MCP Registry. The version
+# must already be bumped everywhere (tests/test_packaging.py).
+# The release is created once every file is built, so it never lacks the disk image; if a job fails, nothing
+# is published and "Re-run failed jobs" picks up from there.
+on:
+  push:
+    tags: ["v*"]
+
+# Only the job that publishes can write; the Mac build runs many build scripts next to the signing secrets.
+permissions:
+  contents: read
+
+jobs:
+  mac:
+    name: Mac app
+    # Builds OpenMyMemo-<version>-arm64.dmg. With these repository secrets the app is signed with a Developer
+    # ID and notarized; without them (a fork) it is signed ad hoc, and macOS asks once to open it (README).
+    #   APPLE_CERTIFICATE           the "Developer ID Application" certificate and its key as a .p12, base64
+    #   APPLE_CERTIFICATE_PASSWORD  the .p12's password
+    #   APPLE_SIGNING_IDENTITY      the certificate's name: "Developer ID Application: <Company> (<Team ID>)"
+    #   APPLE_API_ISSUER            notarization with an App Store Connect API key: the issuer id,
+    #   APPLE_API_KEY_ID            the key id,
+    #   APPLE_API_PRIVATE_KEY       and the text of the key's .p8 file
+    #   APPLE_ID, APPLE_PASSWORD, APPLE_TEAM_ID
+    #                               optional: notarization with an Apple ID and an app-specific password,
+    #                               used only when the API key secrets are absent
+    # Tauri reads the APPLE_* variables itself (tauri-apps/tauri, crates/tauri-bundler/src/bundle/macos/sign.rs):
+    # it imports the certificate into a temporary keychain, and APPLE_SIGNING_IDENTITY overrides the ad hoc
+    # "signingIdentity": "-" in tauri.conf.json (crates/tauri-cli/src/interface/rust.rs).
+    runs-on: macos-latest
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7
+        with:
+          persist-credentials: false
+      - name: The tag matches the version
+        run: |
+          version=$(sed -n 's/^version = "\(.*\)"$/\1/p' pyproject.toml | head -n 1)
+          if [ "$GITHUB_REF_NAME" != "v$version" ]; then
+            echo "::error::Tag $GITHUB_REF_NAME doesn't match version $version in pyproject.toml."
+            exit 1
+          fi
+          echo "VERSION=$version" >> "$GITHUB_ENV"
+      - uses: astral-sh/setup-uv@37802adc94f370d6bfd71619e3f0bf239e1f3b78  # v7; stage_desktop.py bundles this uv
+      - uses: pnpm/action-setup@0977fd99725f1db4007ccb2928dbb4e90d06cc86  # v6
+        with:
+          version: 10
+      - uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1  # v7
+        with:
+          node-version: 22
+          cache: pnpm
+          cache-dependency-path: desktop/pnpm-lock.yaml
+      - run: pnpm install --frozen-lockfile
+        working-directory: desktop
+      - name: Build the app and the disk image
+        working-directory: desktop
+        env:
+          # CI=true also makes Tauri skip the Finder scripting that lays out the disk image window.
+          CI: "true"
+          APPLE_CERTIFICATE: ${{ secrets.APPLE_CERTIFICATE }}
+          APPLE_CERTIFICATE_PASSWORD: ${{ secrets.APPLE_CERTIFICATE_PASSWORD }}
+          APPLE_SIGNING_IDENTITY: ${{ secrets.APPLE_SIGNING_IDENTITY }}
+          APPLE_API_ISSUER: ${{ secrets.APPLE_API_ISSUER }}
+          APPLE_API_KEY: ${{ secrets.APPLE_API_KEY_ID }}
+          APPLE_API_PRIVATE_KEY: ${{ secrets.APPLE_API_PRIVATE_KEY }}
+          APPLE_ID: ${{ secrets.APPLE_ID }}
+          APPLE_PASSWORD: ${{ secrets.APPLE_PASSWORD }}
+          APPLE_TEAM_ID: ${{ secrets.APPLE_TEAM_ID }}
+        run: |
+          # A missing secret arrives as an empty variable, which Tauri would take as set.
+          for name in APPLE_CERTIFICATE APPLE_CERTIFICATE_PASSWORD APPLE_SIGNING_IDENTITY APPLE_API_ISSUER \
+                      APPLE_API_KEY APPLE_API_PRIVATE_KEY APPLE_ID APPLE_PASSWORD APPLE_TEAM_ID; do
+            if [ -z "${!name}" ]; then unset "$name"; fi
+          done
+          if [ -z "${APPLE_CERTIFICATE:-}" ] || [ -z "${APPLE_CERTIFICATE_PASSWORD:-}" ] || [ -z "${APPLE_SIGNING_IDENTITY:-}" ]; then
+            echo "::warning::No Developer ID certificate in the secrets: the app is signed ad hoc and not notarized."
+            unset APPLE_CERTIFICATE APPLE_CERTIFICATE_PASSWORD APPLE_SIGNING_IDENTITY APPLE_API_ISSUER APPLE_API_KEY \
+                  APPLE_ID APPLE_PASSWORD APPLE_TEAM_ID
+          elif [ -n "${APPLE_API_PRIVATE_KEY:-}" ] && [ -n "${APPLE_API_KEY:-}" ] && [ -n "${APPLE_API_ISSUER:-}" ]; then
+            # Tauri would use APPLE_ID first if it were set; the API key is the one to use.
+            unset APPLE_ID APPLE_PASSWORD
+            export APPLE_API_KEY_PATH="$RUNNER_TEMP/AuthKey_$APPLE_API_KEY.p8"
+            ( umask 077 && printf '%s\n' "$APPLE_API_PRIVATE_KEY" > "$APPLE_API_KEY_PATH" )
+          elif [ -z "${APPLE_ID:-}" ] || [ -z "${APPLE_PASSWORD:-}" ] || [ -z "${APPLE_TEAM_ID:-}" ]; then
+            echo "::warning::No notarization credentials in the secrets: the app is signed but not notarized."
+            unset APPLE_ID APPLE_PASSWORD APPLE_API_ISSUER APPLE_API_KEY
+          fi
+          unset APPLE_API_PRIVATE_KEY
+          pnpm tauri build --bundles app,dmg
+      - name: Check the signature and name the disk image
+        run: |
+          bundle=desktop/src-tauri/target/release/bundle
+          codesign --verify --deep --strict --verbose=2 "$bundle/macos/OpenMyMemo.app"
+          codesign -dv "$bundle/macos/OpenMyMemo.app" 2>&1 | grep -E '^(Authority|Signature|TeamIdentifier)=' || true
+          mkdir -p dist
+          cp "$bundle/dmg/OpenMyMemo_${VERSION}_aarch64.dmg" "dist/OpenMyMemo-${VERSION}-arm64.dmg"
+          hdiutil verify "dist/OpenMyMemo-${VERSION}-arm64.dmg"
+      - uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9  # v7
+        with:
+          name: openmymemo-dmg
+          path: dist/*.dmg
+          if-no-files-found: error
+
+  release:
+    needs: mac
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write  # gh release create
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7
+        with:
+          persist-credentials: false
+      - uses: astral-sh/setup-uv@37802adc94f370d6bfd71619e3f0bf239e1f3b78  # v7
+      - uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1  # v7
+        with:
+          node-version: 22
+      - name: The tag matches the version
+        run: |
+          version=$(python3 -c "import tomllib; print(tomllib.load(open('pyproject.toml', 'rb'))['project']['version'])")
+          if [ "$GITHUB_REF_NAME" != "v$version" ]; then
+            echo "::error::Tag $GITHUB_REF_NAME doesn't match version $version in pyproject.toml."
+            exit 1
+          fi
+      - run: uv sync --frozen
+      - run: uv run pytest
+      - run: uv run python scripts/build_mcpb.py
+      - run: uv build
+      - uses: actions/download-artifact@37930b1c2abaa49bbe596cd826c3c89aef350131  # v7
+        with:
+          name: openmymemo-dmg
+          path: dist
+      - name: Publish the release
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          gh release create "$GITHUB_REF_NAME" dist/*.dmg dist/*.mcpb dist/*.whl dist/*.tar.gz \
+            --title "OpenMyMemo ${GITHUB_REF_NAME#v}" --generate-notes
+      - uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9  # v7
+        with:
+          name: openmymemo-python
+          path: |
+            dist/*.whl
+            dist/*.tar.gz
+          if-no-files-found: error
+
+  pypi:
+    # The same wheel and sdist as the GitHub release, uploaded with PyPI's trusted publishing: PyPI accepts this
+    # job's OIDC token, so there is no API token in the secrets. One-time setup on pypi.org: a trusted publisher
+    # for MyMemoAI/openmymemo, workflow release.yml, environment pypi. If it fails after the GitHub release is
+    # out, "Re-run failed jobs" runs only this job. PyPI never takes the same version twice.
+    needs: release
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/project/openmymemo/
+    permissions:
+      id-token: write
+    steps:
+      - uses: astral-sh/setup-uv@37802adc94f370d6bfd71619e3f0bf239e1f3b78  # v7
+      - uses: actions/download-artifact@37930b1c2abaa49bbe596cd826c3c89aef350131  # v7
+        with:
+          name: openmymemo-python
+          path: dist
+      - run: uv publish --trusted-publishing always dist/*
+
+  mcp-registry:
+    # Lists this version on the official MCP Registry (registry.modelcontextprotocol.io), which MCP clients and
+    # other directories read. The registry stores only server.json: it checks that the PyPI package of that
+    # version exists and that its README names this server ("mcp-name:" near the top of README.md), so it runs
+    # after PyPI. GitHub OIDC proves the namespace io.github.MyMemoAI, so there is no token in the secrets.
+    needs: pypi
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      id-token: write
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7
+        with:
+          persist-credentials: false
+      - name: Install mcp-publisher
+        env:
+          VERSION: v1.8.1
+          SHA256: a06c9096dcb9727c13555b6be26c7effa707b01f06a4c561ba7a3635443cf2cc
+        run: |
+          curl -fsSL -o mcp-publisher.tar.gz \
+            "https://github.com/modelcontextprotocol/registry/releases/download/$VERSION/mcp-publisher_linux_amd64.tar.gz"
+          echo "$SHA256  mcp-publisher.tar.gz" | sha256sum --check
+          tar xzf mcp-publisher.tar.gz mcp-publisher
+      - run: ./mcp-publisher validate
+      - run: ./mcp-publisher login github-oidc
+      - name: Publish server.json
+        run: |
+          # PyPI can take a minute to serve a version it has just accepted.
+          for wait in 0 30 60 120; do
+            sleep "$wait"
+            if ./mcp-publisher publish; then exit 0; fi
+          done
+          exit 1

openmymemo-0.2.4/.gitignore

@@ -0,0 +1,227 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[codz]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+/build/
+/develop-eggs/
+/dist/
+/downloads/
+/eggs/
+/.eggs/
+/lib/
+/lib64/
+/parts/
+/sdist/
+/var/
+/wheels/
+/share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#   Usually these files are written by a python script from a template
+#   before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py.cover
+*.lcov
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+# Pipfile.lock
+
+# uv
+#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+# uv.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+# poetry.lock
+# poetry.toml
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#   pdm recommends including project-wide configuration in pdm.toml, but excluding .pdm-python.
+#   https://pdm-project.org/en/latest/usage/project/#working-with-version-control
+# pdm.lock
+# pdm.toml
+.pdm-python
+.pdm-build/
+
+# pixi
+#   Similar to Pipfile.lock, it is generally recommended to include pixi.lock in version control.
+# pixi.lock
+#   Pixi creates a virtual environment in the .pixi directory, just like venv module creates one
+#   in the .venv directory. It is recommended not to include this directory in version control.
+.pixi/*
+!.pixi/config.toml
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule*
+celerybeat.pid
+
+# Redis
+*.rdb
+*.aof
+*.pid
+
+# RabbitMQ
+mnesia/
+rabbitmq/
+rabbitmq-data/
+
+# ActiveMQ
+activemq-data/
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.envrc
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs/Zensical documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#   JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#   be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#   and can be added to the global gitignore or merged into this file.  For a more nuclear
+#   option (not recommended) you can uncomment the following to ignore the entire idea folder.
+# .idea/
+
+# Abstra
+#   Abstra is an AI-powered process automation framework.
+#   Ignore directories containing user credentials, local state, and settings.
+#   Learn more at https://abstra.io/docs
+.abstra/
+
+# Visual Studio Code
+#   Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore that
+#   can be found at https://github.com/github/gitignore/blob/main/Global/VisualStudioCode.gitignore
+#   and can be added to the global gitignore or merged into this file. However, if you prefer, you
+#   could uncomment the following to ignore the entire vscode folder
+# .vscode/
+# Temporary file for partial code execution
+tempCodeRunnerFile.py
+
+# Ruff stuff:
+.ruff_cache/
+
+# PyPI configuration file
+.pypirc
+
+# Marimo
+marimo/_static/
+marimo/_lsp/
+__marimo__/
+
+# Streamlit
+.streamlit/secrets.toml
+
+# OpenMyMemo
+node_modules/
+web/.vite/
+
+# Agent worktrees created by Claude Code sessions
+.claude/worktrees/

openmymemo-0.2.4/AGENTS.md

@@ -0,0 +1,72 @@
+# OpenMyMemo — agent guide
+
+A local-first, open-source AI memory folder with an approval panel. [docs/product-design.md](./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 MyMemo Cloud connector (product-design.md §16), which does nothing until the person signs in and never holds memory in readable form at rest. The server listens on `127.0.0.1` only.
+- 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.
+- 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 MyMemo Cloud connector is the one optional piece that talks to MyMemo; 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
+
+```bash
+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 app tests
+```
+
+## Code map
+
+| File | Responsibility |
+| --- | --- |
+| `src/openmymemo/mdfile.py` | Parse and rewrite topic files (frontmatter, sections, memory lines; format-1 header migration); untouched lines must survive byte for byte |
+| `src/openmymemo/vault.py` | The vault: sync (editor edits → meta/history), add/update/archive/restore/rollback, settings, locking |
+| `src/openmymemo/topics.py` | The 14 default topics, groups, classification keywords |
+| `docs/MEMORY_FORMAT.md` | The folder format; change it before changing what the code reads or writes |
+| `docs/distribution.md`, `llms-install.md` | Where OpenMyMemo is published and listed, the shared listing details, and the setup guide AI agents such as Cline follow |
+| `src/openmymemo/textutil.py` | Similarity, search scoring, rule-based classification |
+| `src/openmymemo/connectors.py` | Connector permissions, tokens, revocation tombstones |
+| `src/openmymemo/clients.py` | The catalog of AI apps (product-design.md §15.1): detection, status, one-click connect and disconnect by editing an app's MCP config (JSON or Codex TOML) or running its `mcp add`, and the manual snippets |
+| `src/openmymemo/appfiles.py` | Writing other apps' files (their MCP configs, Codex's `hooks.json`): atomic, permissions kept from the first byte, through symlinks, with a one-time `<file>.openmymemo-backup` |
+| `src/openmymemo/proposals.py` | Proposal lifecycle, dedupe, auto-apply and undo |
+| `src/openmymemo/context.py` | Compiles what an AI sees, MEMORY.md, log.md, search |
+| `src/openmymemo/transfer.py` | Import (ChatGPT / Claude / Markdown / JSON) and export |
+| `src/openmymemo/mcp_server.py` | MCP tools (mcp SDK 2.x `MCPServer`); `relayed=` builds the MyMemo Cloud variant |
+| `src/openmymemo/web.py` | Panel API, `/mcp` and `/cloud/callback` combined into one ASGI app; `panel_server()` is the uvicorn server that starts MyMemo Cloud once its port is bound |
+| `src/openmymemo/cloud.py` | MyMemo Cloud (product-design.md §16): the per-computer link (`cloud.json`, never in the folder), linking with PKCE and a loopback callback, and the bridge: one outbound WebSocket that answers relayed tool calls as `cloud-<slug>` connectors and files the offline queue (HPKE-sealed proposals) through `proposals.py`. The wire format is pinned by `tests/fixtures/cloud/` (the MyMemo service tests against the same files); `tests/cloud_fake.py` is a fake service built from it |
+| `src/openmymemo/cli.py` | Typer CLI |
+| `src/openmymemo/codex.py` | Codex session hook: merges it into `~/.codex/hooks.json` and takes it out again (Codex doesn't run plugin hooks) |
+| `web/` | Vue 3 + Tailwind v4 panel source; all copy lives in `web/src/i18n.ts` |
+| `web/src/components/ConnectApps.vue` | The app list with Connect / Disconnect / Set up, used by the Connectors page and the first-run guide; `ConnectNote` shows what's left to do, `ConnectorPanel` a connected app's permissions, `CloudRow` the MyMemo Cloud row (sign-in, status, setup for ChatGPT and claude.ai, its web apps) |
+| `web/src/desktop.ts` | The Mac layout switch (`?desktop=1`), the shell's commands and shortcuts; `MemoriesDesktopView`, `MemoryInspector`, `DesktopSidebar`, `DesktopToolbar` are its screens; `memorySaves.ts` queues the inspector's saves per memory. `PageHeader` becomes the window toolbar there |
+| `desktop/` | Mac app (Tauri 2, product-design.md §14, §15.2): `src-tauri/src/core.rs` installs the core (non-editable) and finds or starts the server for the folder, `launcher.rs` writes the `openmymemo` launcher AI apps run, `install.rs` moves the app from the disk image to Applications, `main.rs` has the window, menus, menu-bar item, notifications, settings and link handling; `scripts/stage_desktop.py` stages the core and `uv` before each build |
+| `.claude-plugin/` | Claude Code plugin manifest and marketplace (the repo root is the plugin) |
+| `plugin.json`, `mcp.json`, `.agents/plugins/` | Codex plugin (Agent Plugins format) and its marketplace |
+| `skills/` | Skills shared by the Claude Code and Codex plugins |
+| `integrations/hooks/` | Session-start hook script shared by Claude Code (plugin hook in `integrations/claude-code/hooks/hooks.json`) and Codex (user-level hook installed by `setup codex`; `integrations/codex/setup.sh` runs it from the installed plugin) |
+| `integrations/claude-desktop/` | `.mcpb` manifest; build with `scripts/build_mcpb.py` |
+| `integrations/icons/`, `web/public/logo.png` | The MyMemo logo at each size, rendered from MyMemo's app icon by `scripts/make_icons.py` |
+
+## 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](./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` and the Mac app (`desktop/package.json`, `desktop/src-tauri/tauri.conf.json`, `desktop/src-tauri/Cargo.toml`) 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.
+- MyMemo Cloud is hidden until turned on in Settings (or `openmymemo cloud settings --show`), and listed while linked (product-design.md §16.11). 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.
+- 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.