cli-mem 0.4.0__tar.gz → 0.5.1__tar.gz

cli_mem-0.5.1/.github/workflows/ci.yml

@@ -0,0 +1,86 @@
+name: CI
+
+on:
+  push:
+    branches: [master]
+  # Deliberately unfiltered by base branch. With a `branches: [master]` filter,
+  # a pull request targeting anything else gets no CI at all — which silently
+  # excluded every stacked PR in this series, the exact review model in use.
+  pull_request:
+
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  test:
+    runs-on: macos-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        # Must cover every version pyproject declares support for. Claiming
+        # >=3.10 while only testing 3.11/3.12 is an untested promise.
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v7
+
+      - uses: actions/setup-python@v7
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install
+        run: pip install -e ".[dev]"
+
+      - name: Lint
+        run: ruff check .
+
+      - name: Format check
+        run: ruff format --check .
+
+      - name: Test
+        run: pytest -v
+
+  build:
+    runs-on: macos-latest
+    steps:
+      - uses: actions/checkout@v7
+
+      - uses: actions/setup-python@v7
+        with:
+          python-version: "3.12"
+
+      # Catches packaging breakage at PR time instead of at tag time, when the
+      # release workflow is the only thing standing between a bad build and PyPI.
+      - name: Build distributions
+        run: |
+          pip install build twine
+          python -m build
+          twine check --strict dist/*
+
+      - name: Verify the installed console script is ours
+        run: |
+          python -m venv /tmp/verify
+          /tmp/verify/bin/pip install --quiet dist/*.whl
+          OUT="$(/tmp/verify/bin/mem --version)"
+          echo "$OUT"
+          case "$OUT" in
+            "mem, version "*) ;;
+            *) echo "::error::unexpected --version output: $OUT"; exit 1 ;;
+          esac
+
+      # The hooks are the entry point for every piece of data mem stores, and
+      # they only reach users through the wheel. They used to be looked up at a
+      # repo-relative path that no installed wheel has, so `mem init` silently
+      # served a stale second copy inlined in cli.py — and the test suite,
+      # which always ran from a source checkout, never noticed. Only an
+      # install-then-run check can catch that class of bug.
+      - name: Verify the wheel ships the shell hooks
+        run: |
+          for shell in zsh bash fish; do
+            OUT="$(/tmp/verify/bin/mem init "$shell")"
+            if ! diff <(printf '%s\n' "$OUT") "src/mem/hooks/mem.$shell"; then
+              echo "::error::mem init $shell does not match src/mem/hooks/mem.$shell"
+              exit 1
+            fi
+          done
+          echo "all three hooks served from the installed wheel"

cli_mem-0.5.1/.github/workflows/release.yml

@@ -0,0 +1,151 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - "v*"
+
+permissions:
+  contents: write
+
+# A tag pushed twice (or force-moved) must not race two publishes against PyPI.
+concurrency:
+  group: release-${{ github.ref }}
+  cancel-in-progress: false
+
+jobs:
+  release:
+    runs-on: macos-latest
+    steps:
+      - uses: actions/checkout@v7
+
+      - uses: actions/setup-python@v7
+        with:
+          python-version: "3.12"
+
+      - name: Verify version matches tag
+        run: |
+          TAG="${{ github.ref_name }}"
+          TAG_VERSION="${TAG#v}"
+          PKG_VERSION=$(python -c "import tomllib; print(tomllib.load(open('pyproject.toml','rb'))['project']['version'])")
+          INIT_VERSION=$(python -c "exec(open('src/mem/__init__.py').read()); print(__version__)")
+          echo "Tag: $TAG_VERSION | pyproject.toml: $PKG_VERSION | __init__.py: $INIT_VERSION"
+          if [ "$TAG_VERSION" != "$PKG_VERSION" ] || [ "$TAG_VERSION" != "$INIT_VERSION" ]; then
+            echo "::error::Version mismatch! Tag=$TAG_VERSION pyproject.toml=$PKG_VERSION __init__.py=$INIT_VERSION"
+            echo "Fix: update both pyproject.toml and src/mem/__init__.py, commit, then re-tag."
+            exit 1
+          fi
+
+      - name: Build
+        run: |
+          pip install build twine
+          python -m build
+          twine check --strict dist/*
+
+      # Everything that can fail must fail BEFORE the upload step: a release
+      # published to PyPI cannot be replaced, only yanked.
+      - name: Smoke-test the built wheel
+        run: |
+          set -euo pipefail
+          python -m venv /tmp/smoke
+          /tmp/smoke/bin/pip install --quiet dist/*.whl
+          OUT="$(/tmp/smoke/bin/mem --version)"
+          echo "$OUT"
+          EXPECTED="mem, version ${GITHUB_REF_NAME#v}"
+          if [ "$OUT" != "$EXPECTED" ]; then
+            echo "::error::wheel reports '$OUT', expected '$EXPECTED'"
+            exit 1
+          fi
+          # The hooks reach users only through the wheel, and they used to be
+          # looked up at a repo-relative path no installed wheel has — so
+          # `mem init` silently served a stale inlined copy and the test suite,
+          # always running from a checkout, never noticed. CI checks this on
+          # every PR; checking it again here costs two seconds and covers a tag
+          # pushed at a commit that somehow skipped it.
+          # `$(...)` strips every trailing newline and printf puts exactly one
+          # back, which normalises the extra newline click.echo appends.
+          for shell in zsh bash fish; do
+            OUT="$(/tmp/smoke/bin/mem init "$shell")"
+            diff <(printf '%s\n' "$OUT") "src/mem/hooks/mem.$shell" \
+              || { echo "::error::mem init $shell does not match the source hook"; exit 1; }
+          done
+
+          # The console script dispatches through mem._entry now; a broken
+          # dispatch breaks every command, and --version alone would not show it.
+          /tmp/smoke/bin/mem tui --help > /dev/null
+          echo "wheel smoke test passed"
+
+      # TODO: migrate to PyPI Trusted Publishing (pypa/gh-action-pypi-publish
+      # with `id-token: write`) to retire the long-lived PYPI_TOKEN secret.
+      # Requires configuring the publisher on PyPI first, so it is a deliberate
+      # follow-up rather than a silent swap.
+      - name: Publish to PyPI
+        env:
+          TWINE_USERNAME: __token__
+          TWINE_PASSWORD: ${{ secrets.PYPI_TOKEN }}
+        run: twine upload --skip-existing dist/*
+
+      - name: Create GitHub Release
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          set -euo pipefail
+          TAG="${{ github.ref_name }}"
+          if gh release view "$TAG" >/dev/null 2>&1; then
+            echo "Release $TAG already exists — uploading artifacts only."
+            gh release upload "$TAG" dist/* --clobber
+          else
+            gh release create "$TAG" --title "$TAG" --generate-notes dist/*
+          fi
+
+      - name: Update Homebrew tap
+        env:
+          TAP_TOKEN: ${{ secrets.TAP_TOKEN }}
+        run: |
+          set -euo pipefail
+
+          TAG="${{ github.ref_name }}"
+          TARBALL_URL="https://github.com/${{ github.repository }}/archive/refs/tags/${TAG}.tar.gz"
+
+          # -f so an HTTP error is an error: without it curl pipes the error page
+          # into shasum and the tap gets a checksum of "404: Not Found".
+          SHA=$(curl -fsSL --retry 5 --retry-delay 2 "$TARBALL_URL" | shasum -a 256 | cut -d' ' -f1)
+          if [ ${#SHA} -ne 64 ]; then
+            echo "::error::refusing to publish a malformed sha256: '$SHA'"
+            exit 1
+          fi
+          echo "Tag: $TAG"
+          echo "SHA256: $SHA"
+
+          # Clone the tap repo
+          git clone "https://x-access-token:${TAP_TOKEN}@github.com/matinsaurralde/homebrew-tap.git" /tmp/tap
+          cd /tmp/tap
+
+          # Update only the release url and sha256 (lines 7-8), not dependency resources.
+          # Uses awk to replace only the FIRST url/sha256 pair matching the release pattern.
+          awk -v tag_url="$TARBALL_URL" -v sha="$SHA" '
+            /url.*github.com\/matinsaurralde\/mem\/archive/ {
+              print "  url \"" tag_url "\""
+              found_url = 1
+              next
+            }
+            found_url && /sha256/ {
+              print "  sha256 \"" sha "\""
+              found_url = 0
+              next
+            }
+            { print }
+          ' Formula/mem.rb > Formula/mem.rb.tmp
+          mv Formula/mem.rb.tmp Formula/mem.rb
+
+          if ! grep -q "$SHA" Formula/mem.rb; then
+            echo "::error::awk did not write the new sha256 into Formula/mem.rb"
+            exit 1
+          fi
+
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          git add Formula/mem.rb
+          git diff --cached --quiet && echo "No changes" && exit 0
+          git commit -m "mem ${TAG}"
+          git push

{cli_mem-0.4.0 → cli_mem-0.5.1}/ARCHITECTURE.md

@@ -21,7 +21,7 @@ Technical overview of how mem works under the hood.
 │  mem list          mem session      mem stats            │
 │  mem forget        mem export       mem import           │
 │  mem group *       mem saved *      mem vars *           │
-│  mem init <shell>                                       │
+│  mem init <shell>  mem agent *      mem mcp              │
 │  mem _capture (hidden)  mem _sync (hidden)              │
 └───┬────────────┬──────────┬──────────┬──────────────────┘
     │            │          │          │
@@ -55,14 +55,16 @@ Technical overview of how mem works under the hood.
 │                    ~/.mem/ (filesystem)                  │
 │                                                         │
 │  repos/              sessions/           patterns/      │
-│    myapp.jsonl         2026-03-05.jsonl    kubectl.json  │
-│    infra.jsonl         2026-03-06.jsonl    docker.json   │
+│    myapp-3f9a1c07.jsonl 2026-03-05.jsonl   kubectl.json  │
+│    infra-b21d4e88.jsonl 2026-03-06.jsonl   docker.json   │
 │    _global.jsonl                           git.json      │
 │                                                         │
 │  groups/                                                │
 │    repos/                                               │
 │      myapp.json      vars.json            .sync_counter │
 │    _global.json      .session_state.json                │
+│                                                         │
+│  agent.json          agent-audit.jsonl                  │
 └─────────────────────────────────────────────────────────┘
 ```
 
@@ -90,7 +92,7 @@ capture.capture_command()
     │ builds CapturedCommand with all metadata
     ▼
 storage.append_command()
-    │ appends one JSON line to ~/.mem/repos/<repo>.jsonl
+    │ appends one JSON line to ~/.mem/repos/<repo-slug>-<hash>.jsonl
     ▼
 capture.SessionTracker.update()
     │ checks idle time and repo change
@@ -115,20 +117,26 @@ cli.cli() dispatches to search
     ▼
 search.search("kubectl", current_repo="infra")
     │
-    ├── read ~/.mem/repos/infra.jsonl (current repo first)
+    ├── read ~/.mem/repos/infra-<hash>.jsonl (current repo first)
     ├── read ~/.mem/repos/_global.jsonl
     ├── read other repo files
     │
     ▼
-Filter: substring match "kubectl" in command text
+Prefilter: needle test on the raw line's command span (skips json.loads)
     │
     ▼
-Score each match:
-    score = (frequency × 0.4) + (recency × 0.4) + (context × 0.2)
+Filter: every query term must appear in the command text
+    │   (if nothing matches, expand through the concept map and retry)
+    ▼
+Score each match (mem/ranking.py — stdlib only, shared with the finder):
+    score = (picks × 0.40) + (frequency × 0.21) + (recency × 0.21)
+          + (prefix × 0.09) + (context × 0.09)
     │
-    ├── frequency: count of identical commands
-    ├── recency: exp(-days × ln2/7), half-life 7 days
-    └── context: 1.0 same repo, 0.5 same prefix, 0.0 other
+    ├── picks:     1 - 2^-w over the finder's decayed selections, 21d half-life
+    ├── frequency: log1p(n)/log1p(50), capped at 1
+    ├── recency:   exp(-days × ln2/7), half-life 7 days
+    ├── prefix:    1.0 if the command starts with the query
+    └── context:   1.0 same repo, 0.5 sibling, 0.0 other
     │
     ▼
 Deduplicate by command string (keep highest score)
@@ -232,7 +240,7 @@ Parse inline VAR=VALUE arguments
 Resolve all variables upfront (before any execution):
     1. Inline arguments  ← highest priority
     2. Shell environment (os.environ)
-    3. Persistent store (~/.mem/vars.json)
+    3. Persistent store (macOS Keychain, indexed by ~/.mem/vars.json)
     4. Default value (from --var at save time)
     5. Interactive prompt ← last resort
     ▼
@@ -245,7 +253,7 @@ Execute commands with substituted values
 
 ## JSONL Schemas
 
-### Command Entry (`repos/<repo>.jsonl`)
+### Command Entry (`repos/<repo-slug>-<hash>.jsonl`)
 
 ```json
 {
@@ -322,17 +330,91 @@ Execute commands with substituted values
 }
 ```
 
-### Variable Store (`vars.json`)
+### Variable Store (`vars.json` + macOS Keychain)
+
+An index, not a vault. The values are Keychain items under the service
+`mem-cli-vars` with the variable name as the account
+([ADR-010](docs/decisions/010-keychain-for-variable-values.md)); `value` is
+`null` for every entry mem writes, and a non-null one is a pre-ADR-010
+plaintext value awaiting migration.
 
 ```json
 {
   "vars": {
-    "API_TOKEN": { "value": "sk-abc123...", "last_used": 1709600000 },
-    "DB_HOST": { "value": "staging.db.internal", "last_used": 1709500000 }
+    "API_TOKEN": { "value": null, "last_used": 1709600000, "backend": "keychain" },
+    "DB_HOST": { "value": null, "last_used": 1709500000, "backend": "keychain" }
   }
 }
 ```
 
+### Agent Access Flag (`agent.json`)
+
+```json
+{
+  "enabled": false,
+  "updated_at": 1709600000
+}
+```
+
+Absent, unreadable or unparseable all mean `enabled: false`. A privacy switch
+must fail closed — the one thing it may never do is grant access because it
+could not read the answer.
+
+### Agent Audit Entry (`agent-audit.jsonl`)
+
+```json
+{
+  "ts": 1709600000,
+  "tool": "search_history",
+  "arguments": { "query": "kubectl prod" },
+  "results": 4,
+  "ok": true,
+  "error": null
+}
+```
+
+`arguments` is redacted before it is written: an agent can put a secret in a
+query string, and an audit log that records secrets is a second copy of the
+thing the audit exists to protect. The file is append-only and is never
+rotated; `mem forget` is the only thing that removes lines from it.
+
+## MCP Server (stdio)
+
+```
+Claude Code / Claude Desktop
+       │  spawns `mem mcp`, keeps the pipe open
+       ▼
+  stdin  ──→ newline-delimited JSON-RPC 2.0 ──→ mem.mcp.serve()
+                                                    │
+                                    ┌───────────────┼───────────────┐
+                                    ▼               ▼               ▼
+                             agent.json      search / groups    audit append
+                            (opt-in gate)      (read-only)     (agent-audit)
+                                    │
+                                    ▼
+                            redact_secrets()  ← single choke point
+                                    │
+  stdout ←── one JSON-RPC frame per line ←──────────┘
+```
+
+Design points:
+
+- **Stdio only.** No socket, no listener, no localhost port. The HTTP/SSE
+  transport is not implemented — "only on loopback" is still a listener.
+- **No MCP SDK dependency.** The official Python SDK pulls uvicorn, starlette
+  and httpx into a project whose first principle is that it never imports a
+  networking stack. The protocol is hand-rolled in `src/mem/mcp.py`.
+- **stdout is the wire.** `serve()` rebinds `sys.stdout` to stderr for its
+  whole lifetime, so a stray `print`, a Rich console write, or a
+  corrupted-JSONL warning becomes a diagnostic rather than a corrupt frame.
+- **Four read-only tools**, and nothing that executes a command.
+- **The access flag is read per request**, so `mem agent disable` takes effect
+  without restarting the client.
+
+`backend` is derived from the absence of `value` on every read, never trusted
+from the file — so an entry cannot claim to be encrypted while holding a
+secret.
+
 ## Session Boundary Detection
 
 A new session begins when either condition is met:
@@ -347,3 +429,11 @@ See `docs/decisions/` for detailed ADRs:
 - [002: Apple FM SDK for Patterns](docs/decisions/002-apple-fm-sdk-for-patterns.md)
 - [003: No Daemon, Background Subprocess Instead](docs/decisions/003-no-daemon.md)
 - [004: Per-Repository JSONL Files](docs/decisions/004-per-repo-jsonl.md)
+- [005: A Derived Index, With the JSONL as the Source of Truth](docs/decisions/005-derived-index-jsonl-source-of-truth.md)
+- [006: App Intents, Shortcuts and Spotlight — Evaluated and Deferred](docs/decisions/006-app-intents-shortcuts-spotlight-deferred.md)
+- [007: MCP Over Stdio, Never HTTP](docs/decisions/007-mcp-over-stdio-never-http.md)
+- [008: The Interactive TUI Is Built on the Standard Library](docs/decisions/008-stdlib-tui.md)
+- [009: Ranking Learns From What You Select](docs/decisions/009-ranking-learns-from-selections.md)
+- [010: The Keychain for Variable Values](docs/decisions/010-keychain-for-variable-values.md)
+- [011: A Concept Map, Not Embeddings](docs/decisions/011-concept-map-over-embeddings.md)
+- [012: Promote Mines Sequences, and Ranking Is What Makes It Trustworthy](docs/decisions/012-promote-mines-sequences-not-commands.md)