cli-mem 0.1.0__tar.gz

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

@@ -0,0 +1,29 @@
+name: CI
+
+on:
+  push:
+    branches: [master]
+  pull_request:
+    branches: [master]
+
+jobs:
+  test:
+    runs-on: macos-latest
+    strategy:
+      matrix:
+        python-version: ["3.11", "3.12"]
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install
+        run: pip install -e ".[dev]"
+
+      - name: Lint
+        run: ruff check .
+
+      - name: Test
+        run: pytest -v

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

@@ -0,0 +1,65 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - "v*"
+
+permissions:
+  contents: write
+
+jobs:
+  release:
+    runs-on: macos-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Create GitHub Release
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          gh release create "${{ github.ref_name }}" \
+            --title "${{ github.ref_name }}" \
+            --generate-notes
+
+      - 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"
+
+          # Download tarball and compute SHA256
+          SHA=$(curl -sL "$TARBALL_URL" | shasum -a 256 | cut -d' ' -f1)
+          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
+
+          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.1.0/.gitignore

@@ -0,0 +1,44 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+*.egg-info/
+*.egg
+dist/
+build/
+*.whl
+
+# Virtual environments
+.venv/
+venv/
+env/
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+.mypy_cache/
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Internal tooling — not part of the public project
+.specify/
+.claude/
+specs/
+CLAUDE.md
+
+# Homebrew formula (lives in separate homebrew-tap repo)
+Formula/
+
+# mem runtime data (never commit user history)
+.mem/

cli_mem-0.1.0/ARCHITECTURE.md

@@ -0,0 +1,219 @@
+# Architecture
+
+Technical overview of how mem works under the hood.
+
+## Component Diagram
+
+```
+┌─────────────────────────────────────────────────────────┐
+│                      User's Shell                       │
+│                                                         │
+│  preexec ──► capture cmd + start time                   │
+│  precmd  ──► compute exit code + duration               │
+│              └── mem _capture (background, &!)          │
+└────────────────────────┬────────────────────────────────┘
+                         │
+                         ▼
+┌─────────────────────────────────────────────────────────┐
+│                    src/mem/cli.py                        │
+│                                                         │
+│  mem <query>          mem sync         mem session       │
+│  mem init <shell>     mem stats        mem forget        │
+│  mem _capture (hidden)                                   │
+└───┬────────────┬──────────────┬──────────────┬──────────┘
+    │            │              │              │
+    ▼            ▼              ▼              ▼
+┌────────┐ ┌─────────┐ ┌──────────┐ ┌──────────────────┐
+│capture │ │ search  │ │ patterns │ │    storage        │
+│  .py   │ │   .py   │ │   .py    │ │      .py         │
+│        │ │         │ │          │ │                   │
+│ hook   │ │ score   │ │ Apple FM │ │ JSONL read/write  │
+│ capture│ │ rank    │ │ SDK      │ │ JSON read/write   │
+│ session│ │ filter  │ │ guided   │ │ rotate / forget   │
+│ tracker│ │ dedup   │ │ gen      │ │                   │
+└───┬────┘ └────┬────┘ └────┬─────┘ └────────┬──────────┘
+    │           │           │                 │
+    └───────────┴───────────┴─────────────────┘
+                         │
+                         ▼
+┌─────────────────────────────────────────────────────────┐
+│                    ~/.mem/ (filesystem)                   │
+│                                                         │
+│  repos/              sessions/           patterns/       │
+│    myapp.jsonl         2026-03-05.jsonl    kubectl.json  │
+│    infra.jsonl         2026-03-06.jsonl    docker.json   │
+│    _global.jsonl                           git.json      │
+└─────────────────────────────────────────────────────────┘
+```
+
+## Data Flows
+
+### Command Capture
+
+```
+User runs: kubectl get pods
+    │
+    ▼
+preexec hook fires
+    │ saves command text + start timestamp
+    ▼
+Command executes...
+    │
+    ▼
+precmd hook fires
+    │ computes exit code + duration
+    │ runs: mem _capture "kubectl get pods" "/path" "0" "312" &!
+    │        └── background, disowned, silent
+    ▼
+capture.capture_command()
+    │ detects git repo via `git rev-parse --show-toplevel`
+    │ builds CapturedCommand with all metadata
+    ▼
+storage.append_command()
+    │ appends one JSON line to ~/.mem/repos/<repo>.jsonl
+    ▼
+capture.SessionTracker.update()
+    │ checks idle time and repo change
+    │ closes session if boundary detected
+    ▼
+Done (total overhead: <5ms added to prompt)
+```
+
+### Search Query
+
+```
+User runs: mem kubectl
+    │
+    ▼
+cli.cli() dispatches to search
+    │ detects current repo via git
+    ▼
+search.search("kubectl", current_repo="infra")
+    │
+    ├── read ~/.mem/repos/infra.jsonl (current repo first)
+    ├── read ~/.mem/repos/_global.jsonl
+    ├── read other repo files
+    │
+    ▼
+Filter: substring match "kubectl" in command text
+    │
+    ▼
+Score each match:
+    score = (frequency × 0.4) + (recency × 0.4) + (context × 0.2)
+    │
+    ├── 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
+    │
+    ▼
+Deduplicate by command string (keep highest score)
+    │
+    ▼
+Return top N sorted by score descending
+```
+
+### Pattern Extraction
+
+```
+User runs: mem sync
+    │
+    ▼
+patterns.sync_all_patterns()
+    │ reads ALL commands from all repo files
+    │ groups by tool (first token)
+    │ skips tools with <5 commands
+    │
+    ▼ (for each tool with enough data)
+patterns.extract_patterns_for_tool()
+    │
+    ├── If apple-fm-sdk available:
+    │   │ builds prompt with command list
+    │   │ calls Apple FM with Pydantic guided generation
+    │   └── returns PatternExtractionResult
+    │
+    └── If not available:
+        │ groups identical commands
+        └── returns frequency-based "patterns" (fallback)
+    │
+    ▼
+storage.write_patterns()
+    │ writes to ~/.mem/patterns/<tool>.json
+    │ atomic: write tmp file, then rename
+    ▼
+storage.rotate()
+    │ removes commands older than 90 days
+    │ deletes session files older than 30 days
+    │ NEVER touches patterns/
+    ▼
+Done
+```
+
+## JSONL Schemas
+
+### Command Entry (`repos/<repo>.jsonl`)
+
+```json
+{
+  "command": "kubectl rollout restart deployment api",
+  "ts": 1709600000,
+  "dir": "/Users/mati/projects/services/api",
+  "repo": "services",
+  "exit_code": 0,
+  "duration_ms": 312,
+  "session": "abc123def456"
+}
+```
+
+### Session Entry (`sessions/YYYY-MM-DD.jsonl`)
+
+```json
+{
+  "id": "abc123def456",
+  "summary": "debugging API outage in production",
+  "started_at": 1709599500,
+  "ended_at": 1709600400,
+  "dir": "/Users/mati/projects/services/api",
+  "repo": "services",
+  "commands": [
+    "kubectl logs api-7f9b --tail=100",
+    "kubectl get pods -n production",
+    "kubectl rollout restart deployment api"
+  ]
+}
+```
+
+### Pattern Entry (`patterns/<tool>.json`)
+
+```json
+{
+  "tool": "kubectl",
+  "patterns": [
+    {
+      "pattern": "kubectl get <resource>",
+      "example": "kubectl get pods",
+      "frequency": 42
+    },
+    {
+      "pattern": "kubectl describe <resource> <name>",
+      "example": "kubectl describe pod api-7f9b",
+      "frequency": 17
+    }
+  ],
+  "last_updated": 1709600000
+}
+```
+
+## Session Boundary Detection
+
+A new session begins when either condition is met:
+- **Idle time > 300 seconds (5 minutes)**: Long enough that brief interruptions don't split sessions, short enough that genuine context switches are detected.
+- **Repository change**: Switching to a different git repo almost always means a different task.
+
+## Design Decisions
+
+See `docs/decisions/` for detailed ADRs:
+
+- [001: JSONL Over SQLite](docs/decisions/001-jsonl-over-sqlite.md)
+- [002: Apple FM SDK for Patterns](docs/decisions/002-apple-fm-sdk-for-patterns.md)
+- [003: No Background Daemon](docs/decisions/003-no-daemon.md)
+- [004: Per-Repository JSONL Files](docs/decisions/004-per-repo-jsonl.md)

cli_mem-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Matias Federico Insaurralde
+
+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.

cli_mem-0.1.0/PHILOSOPHY.md

@@ -0,0 +1,111 @@
+# Philosophy
+
+> Your shell history, understood. Not just searched.
+
+These are the principles that guide every design decision in mem.
+
+---
+
+## I. Privacy First
+
+All processing executes entirely on-device. Zero network requests.
+Zero telemetry. Zero cloud dependencies.
+
+- Shell history is treated as sensitive data at all times.
+- No command, pattern, or session data ever leaves the machine.
+- mem does not import or depend on any networking library.
+- Any feature that would require network access is rejected
+  at the design stage.
+
+**Why**: The shell history is one of the most sensitive artifacts
+a developer has. Privacy is non-negotiable.
+
+## II. Simple Where Simple Works
+
+Deterministic algorithms are used wherever they produce
+acceptable results. AI inference (Apple Foundation Models) is
+reserved exclusively for tasks where no deterministic approach
+can match the quality.
+
+- Frequency ranking and recency scoring are deterministic
+  (exponential decay, weighted sums).
+- Pattern extraction is the sole AI-powered operation — justified
+  because no regex or heuristic can infer abstract command structures
+  from arbitrary history.
+- Session summaries use AI for semantic matching — justified
+  because keyword search alone misses intent.
+
+**Why**: AI adds latency, complexity, and opacity. Use it only
+where it earns its keep.
+
+## III. Unix Citizen
+
+mem is composable, pipeable, and respectful of existing
+shell conventions.
+
+- All storage files are human-readable plain text (JSONL or JSON).
+- `cat`, `grep`, and `tail -f` work on every file in `~/.mem/`.
+- CLI output supports both human-readable (default) and JSON
+  (`--json`) formats.
+- mem reads from stdin and writes results to stdout; errors
+  and diagnostics go to stderr.
+- mem does not replace, wrap, or intercept the user's shell.
+  It hooks into existing precmd/preexec mechanisms only.
+
+**Why**: A tool that fights the Unix philosophy will be
+abandoned. mem extends the shell; it does not compete with it.
+
+## IV. Context Is Everything
+
+The same command means different things in different repositories.
+mem is context-aware by default.
+
+- Commands are stored per git repository in separate JSONL files.
+- Search results are ranked with a context multiplier:
+  higher for the current repo, lower for unrelated repos.
+- Session boundaries are defined by idle time or switching
+  to a different repository.
+
+**Why**: Context transforms a flat list of 10,000 commands into
+a focused, relevant recall system.
+
+## V. Learn Silently, Surface Explicitly
+
+mem does not interrupt the user's workflow. It captures data
+passively and speaks only when asked.
+
+- Shell hooks append one line per command execution — no
+  prompts, no confirmations, no output.
+- Pattern extraction and session grouping run only when the user
+  explicitly invokes `mem sync`.
+- No background daemons, no cron jobs, no scheduled processes.
+- The user is always in control of when analysis happens.
+
+**Why**: A tool that nags or slows the shell will be uninstalled
+within a day. Silence is a feature.
+
+## VI. Open Source
+
+mem is built to be open source from day one. The codebase is
+inspectable, forkable, and contributable.
+
+- Every design decision is documented and defensible.
+- No magic, no black boxes. If a contributor cannot understand
+  why a piece of code exists by reading it and its context,
+  documentation is missing.
+- Internal APIs and data formats are stable enough that
+  forks and community tools can rely on them.
+
+**Why**: Open source is not a distribution model — it is
+a quality bar. Code that must survive public scrutiny is better code.
+
+---
+
+## What mem is NOT
+
+- Not a shell replacement (no Warp, no Fig)
+- Not a semantic search engine (no embeddings, no vector DB)
+- Not a cloud product
+- Not an AI assistant that chats back
+- Not a replacement for `man` pages or docs
+- Not a database-backed tool of any kind