cli-mem 0.1.0__py3-none-any.whl

cli_mem-0.1.0.dist-info/METADATA

@@ -0,0 +1,315 @@
+Metadata-Version: 2.4
+Name: cli-mem
+Version: 0.1.0
+Summary: Privacy-first CLI that turns shell history into searchable memory
+Project-URL: GitHub, https://github.com/matinsaurralde/mem
+Author: Matias Insaurralde
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: System :: Shells
+Requires-Python: >=3.10
+Requires-Dist: click
+Requires-Dist: pydantic
+Requires-Dist: rich
+Provides-Extra: ai
+Requires-Dist: apple-fm-sdk; extra == 'ai'
+Provides-Extra: dev
+Requires-Dist: pytest; extra == 'dev'
+Requires-Dist: pytest-asyncio; extra == 'dev'
+Requires-Dist: ruff; extra == 'dev'
+Description-Content-Type: text/markdown
+
+<p align="center">
+  <h1 align="center">mem</h1>
+  <p align="center">
+    <strong>Your shell history, understood. Not just searched.</strong>
+  </p>
+  <p align="center">
+    A privacy-first CLI that turns your terminal history into an intelligent,<br>
+    searchable memory system — powered by on-device AI, with zero cloud dependencies.
+  </p>
+  <p align="center">
+    <a href="#installation"><img alt="macOS 26+" src="https://img.shields.io/badge/macOS-26%2B-blue?logo=apple&logoColor=white"></a>
+    <a href="#installation"><img alt="Python 3.10+" src="https://img.shields.io/badge/python-3.10%2B-3776AB?logo=python&logoColor=white"></a>
+    <a href="LICENSE"><img alt="License: MIT" src="https://img.shields.io/badge/license-MIT-green"></a>
+    <a href="PHILOSOPHY.md"><img alt="Privacy: 100% on-device" src="https://img.shields.io/badge/privacy-100%25%20on--device-brightgreen"></a>
+  </p>
+</p>
+
+<p align="center">
+  <img src="assets/demo.gif" alt="mem demo" width="700">
+</p>
+
+<!-- TODO: Record a demo GIF showing: mem deploy → results from different repos -->
+<!-- Use https://github.com/faressoft/terminalizer or asciinema + agg -->
+
+---
+
+Unlike `Ctrl+R`, mem knows *where* you are. The same query returns different results depending on your current git repository — because `kubectl apply` means something different in your infra repo than in your backend repo.
+
+Unlike cloud-based history tools, **nothing ever leaves your machine**. Every command, pattern, and session stays in plain text files you can `cat`, `grep`, and `tail`.
+
+## Features
+
+- **Context-aware search** — results ranked by your current git repo, not just recency
+- **AI pattern extraction** — learns that `kubectl get pods`, `kubectl get services`, `kubectl get deployments` are all `kubectl get <resource>`
+- **100% on-device** — uses Apple Foundation Models locally. Zero network. Zero telemetry
+- **Plain text storage** — everything in `~/.mem/` as JSONL files. Inspect with `cat`. Search with `grep`
+- **Silent capture** — shell hook adds <5ms to prompt. You won't notice it
+- **Session replay** — recall the exact sequence of commands from last Tuesday's debugging session
+
+## Quick start
+
+### 1. Install
+
+```bash
+# Homebrew (recommended)
+brew install matinsaurralde/tap/mem
+
+# Quick install script
+curl -fsSL https://raw.githubusercontent.com/matinsaurralde/mem/main/install.sh | bash
+
+# pip / pipx
+pipx install mem-cli
+```
+
+### 2. Activate
+
+```bash
+echo 'eval "$(mem init zsh)"' >> ~/.zshrc
+source ~/.zshrc
+```
+
+### 3. Use your terminal
+
+Every command is silently captured with full context — directory, git repo, exit code, duration.
+
+### 4. Search
+
+```bash
+mem deploy
+```
+
+```
+ 1  kubectl apply -f deployment.yaml    infra       2h ago
+ 2  docker compose up -d                backend     1d ago
+ 3  fly deploy                          api         3d ago
+```
+
+That's it. mem gets smarter the more you use it.
+
+## Usage
+
+### Search history
+
+```bash
+mem kubectl                    # search by keyword
+mem "docker compose"           # search by phrase
+mem deploy -n 20               # show more results
+mem deploy --json              # machine-readable output
+```
+
+### See patterns
+
+After running `mem sync`, mem uses on-device AI to extract structural patterns from your history:
+
+```bash
+mem kubectl --pattern
+```
+
+```
+Patterns for "kubectl":
+
+  kubectl get <resource>
+  kubectl describe <resource> <name>
+  kubectl logs <pod> [--tail=<n>]
+  kubectl apply -f <file>
+```
+
+### Recall sessions
+
+```bash
+mem session "api outage"
+```
+
+```
++-----------------------------------------+
+| Session: 2026-03-07 14:30  myapp        |
+|-----------------------------------------|
+|  1  kubectl logs api-7f9b --tail=100    |
+|  2  kubectl get pods -n production      |
+|  3  kubectl rollout restart deploy api  |
+|  4  curl -s localhost:8080/health       |
++-----------------------------------------+
+
+Replay a session? [number/n]: _
+```
+
+### More commands
+
+```bash
+mem stats                      # top commands, repos, totals
+mem sync                       # extract patterns + clean old data
+mem forget "API_KEY=sk-..."    # permanently delete sensitive commands
+mem init zsh                   # print shell hook code
+```
+
+## How it works
+
+```
+You type a command
+        │
+        ▼
+   Shell hook (preexec/precmd)
+        │
+        ▼
+   mem _capture  ← runs in background, <5ms
+        │
+        ▼
+   Append one JSON line to ~/.mem/repos/<repo>.jsonl
+```
+
+When you search, mem reads the JSONL file for your current repo and scores each command:
+
+```
+score = (frequency × 0.4) + (recency × 0.4) + (context × 0.2)
+```
+
+- **Frequency** — how often you've run this exact command
+- **Recency** — exponential decay with a 7-day half-life
+- **Context** — 1.0 if same repo, 0.5 if same directory prefix, 0.0 otherwise
+
+Pattern extraction uses [Apple Foundation Models](https://developer.apple.com/machine-learning/api/) running entirely on-device. No API keys, no cloud calls, no data exfiltration — just your Mac's neural engine.
+
+## Storage
+
+All data lives in `~/.mem/` as human-readable plain text:
+
+```
+~/.mem/
+  repos/
+    infra-k8s.jsonl          # commands from this git repo
+    backend.jsonl
+    _global.jsonl            # commands outside any repo
+  sessions/
+    2026-03-05.jsonl         # grouped work sessions
+  patterns/
+    kubectl.json             # AI-extracted patterns
+    docker.json
+```
+
+Every file is inspectable:
+
+```bash
+cat ~/.mem/repos/myapp.jsonl
+tail -f ~/.mem/repos/myapp.jsonl    # watch commands arrive in real-time
+grep "docker" ~/.mem/repos/*.jsonl  # search across all repos with grep
+```
+
+## Privacy
+
+mem is built on a simple promise: **your shell history never leaves your machine**.
+
+- Zero network requests — not even update checks
+- Zero telemetry — no usage tracking, no analytics, no crash reports
+- Zero cloud dependencies — works fully offline, always
+- On-device AI only — Apple Foundation Models run on your Mac's neural engine
+- Plain text storage — no proprietary formats, no encrypted blobs. You own your data
+
+Read more in [PHILOSOPHY.md](PHILOSOPHY.md).
+
+## Requirements
+
+| Requirement | Version |
+|-------------|---------|
+| macOS       | 26.0+  |
+| Python      | 3.10+  |
+| Apple Intelligence | Enabled (for pattern extraction) |
+
+> **Note:** mem works without Apple Intelligence — you just won't get AI-extracted patterns. Search, capture, and everything else works fine.
+
+## Installation
+
+### Homebrew
+
+```bash
+brew tap matinsaurralde/tap
+brew install mem
+```
+
+### Quick install
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/matinsaurralde/mem/main/install.sh | bash
+```
+
+### pipx (recommended for Python users)
+
+```bash
+pipx install mem-cli
+```
+
+### From source
+
+```bash
+git clone https://github.com/matinsaurralde/mem.git
+cd mem
+pip install -e ".[ai]"     # with AI pattern extraction
+pip install -e "."         # without AI (search-only)
+```
+
+### Shell setup
+
+After installation, add the hook to your shell:
+
+```bash
+# zsh (v1)
+echo 'eval "$(mem init zsh)"' >> ~/.zshrc
+source ~/.zshrc
+```
+
+Bash and fish support coming in v1.5.
+
+## Data retention
+
+mem never grows unbounded. Running `mem sync` automatically cleans old data:
+
+| Data | Retention | Rationale |
+|------|-----------|-----------|
+| Commands | 90 days | High-volume, older ones rarely recalled |
+| Sessions | 30 days | Useful for recent postmortems |
+| Patterns | Forever | Small files, accumulated learning |
+
+Override defaults: `mem sync --keep-commands 180 --keep-sessions 60`
+
+## Uninstall
+
+```bash
+brew uninstall mem          # or: pipx uninstall mem-cli
+rm -rf ~/.mem               # remove all captured data
+```
+
+Remove the `eval "$(mem init zsh)"` line from your `~/.zshrc`.
+
+## Contributing
+
+Contributions are welcome. Please read the [PHILOSOPHY.md](PHILOSOPHY.md) first to understand the principles that guide this project.
+
+```bash
+git clone https://github.com/matinsaurralde/mem.git
+cd mem
+pip install -e ".[dev]"
+pytest
+```
+
+## License
+
+[MIT](LICENSE)

cli_mem-0.1.0.dist-info/RECORD

@@ -0,0 +1,12 @@
+mem/__init__.py,sha256=ewEZCQcr5gM10n0oX2bYh0wXGchwtdehJzqYSSBggmg,69
+mem/capture.py,sha256=rvO-x0axVLrZ3uozeIcoWRbTbZNy674mUCjntCpdLlY,6652
+mem/cli.py,sha256=Po_QiDm46yXd1ntXSlVPt9KV89HCgBWhCii5GiXNukI,10591
+mem/models.py,sha256=AXLCjOR02-MW50uw1XLjlQJhM5JWjG8XWol8kRs6gf4,2206
+mem/patterns.py,sha256=NeGQGQDZomt1m93__-6U74jLgx3aRt0sJeILqZ1oErE,8203
+mem/search.py,sha256=AItSepaTFG63fXuVIdjGpt8f4r1yC6rF_WzXmETGKpk,6005
+mem/storage.py,sha256=4eXFtpRnraliUVh8nRmeg1aFtBFP4qfS-ooCB4heHFg,10750
+cli_mem-0.1.0.dist-info/METADATA,sha256=Won8Vj6QbgmjeINboWJuI3Zy7Um9qWBJz7gA6tojA0o,9018
+cli_mem-0.1.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+cli_mem-0.1.0.dist-info/entry_points.txt,sha256=KiuCWp4iI84ovCretwybDasM3_8g9YdK-nypnmeOIWw,36
+cli_mem-0.1.0.dist-info/licenses/LICENSE,sha256=SeV7jm8yfSsZQjMq2fYTOK9FZQqR6chFVGhqjrxl9P8,1084
+cli_mem-0.1.0.dist-info/RECORD,,

cli_mem-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any

cli_mem-0.1.0.dist-info/entry_points.txt

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

cli_mem-0.1.0.dist-info/licenses/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.

mem/__init__.py

@@ -0,0 +1,3 @@
+"""mem — your shell history, understood."""
+
+__version__ = "0.1.0"

mem/capture.py

@@ -0,0 +1,198 @@
+"""
+Shell history capture module.
+
+Handles command capture from shell hooks and session tracking.
+The capture pipeline: shell hook -> mem _capture -> this module -> storage.
+"""
+
+from __future__ import annotations
+
+import json
+import subprocess
+import time
+import uuid
+
+from mem.models import CapturedCommand, SessionState, WorkSession
+from mem import storage
+
+
+def get_git_repo(directory: str) -> str | None:
+    """Detect the current git repository's root path.
+
+    Runs `git rev-parse --show-toplevel` to find the repo root
+    and returns the full absolute path (e.g., /Users/me/projects/myapp).
+
+    Uses the full path — not the basename — so repos with the same
+    folder name under different parents stay isolated (e.g.,
+    /work/client-a/api and /work/client-b/api are distinct).
+
+    Returns None if the directory is not inside a git repository.
+
+    Why subprocess over gitpython: zero dependencies. git is always
+    available on macOS, and we only need one command.
+    """
+    try:
+        result = subprocess.run(
+            ["git", "-C", directory, "rev-parse", "--show-toplevel"],
+            capture_output=True,
+            text=True,
+            timeout=5,
+        )
+        if result.returncode == 0:
+            return result.stdout.strip()
+        return None
+    except (subprocess.TimeoutExpired, FileNotFoundError):
+        return None
+
+
+def capture_command(raw: str, directory: str, exit_code: int, duration_ms: int) -> None:
+    """Capture a shell command with full context and persist it.
+
+    Called by the shell hook after every command execution.
+    Builds a CapturedCommand with the current timestamp and git repo,
+    then appends it to the appropriate JSONL file.
+    """
+    repo = get_git_repo(directory)
+    cmd = CapturedCommand(
+        command=raw,
+        ts=int(time.time()),
+        dir=directory,
+        repo=repo,
+        exit_code=exit_code,
+        duration_ms=duration_ms,
+    )
+    storage.append_command(cmd)
+
+    # Update session tracking
+    try:
+        tracker = SessionTracker()
+        tracker.update(cmd)
+    except Exception:
+        pass  # Session tracking failure should never block capture
+
+
+class SessionTracker:
+    """Tracks work sessions across shell commands.
+
+    A session is a coherent sequence of commands grouped by time
+    proximity and repository context. Session boundaries are detected
+    when:
+
+    1. More than 300 seconds (5 minutes) of idle time between commands
+    2. The user switches to a different git repository
+
+    Why 300 seconds: Five minutes is long enough that brief interruptions
+    (reading docs, bathroom breaks) don't split a session, but short
+    enough that genuine context switches are detected. This threshold
+    was chosen by observing that most developers maintain focus on a
+    single task for at least 5 minutes, and breaks longer than that
+    typically indicate a task switch.
+
+    State is persisted in ~/.mem/.session_state.json so sessions
+    survive shell restarts.
+    """
+
+    def __init__(self) -> None:
+        self._state_path = storage.MEM_DIR / ".session_state.json"
+
+    def _load_state(self) -> SessionState | None:
+        """Load the current session state from disk."""
+        if not self._state_path.exists():
+            return None
+        try:
+            data = json.loads(self._state_path.read_text(encoding="utf-8"))
+            return SessionState(**data)
+        except Exception:
+            return None
+
+    def _save_state(self, state: SessionState) -> None:
+        """Persist session state to disk."""
+        storage.ensure_dirs()
+        self._state_path.write_text(
+            state.model_dump_json(), encoding="utf-8"
+        )
+
+    def _clear_state(self) -> None:
+        """Remove session state file."""
+        if self._state_path.exists():
+            self._state_path.unlink()
+
+    def update(self, cmd: CapturedCommand) -> None:
+        """Process a new command and update session state.
+
+        Detects session boundaries and closes sessions when:
+        - More than 300 seconds have passed since the last command
+        - The git repo has changed
+        """
+        state = self._load_state()
+
+        if state is None:
+            # Start a new session
+            new_state = SessionState(
+                session_id=uuid.uuid4().hex,
+                last_command_ts=cmd.ts,
+                last_repo=cmd.repo,
+                commands=[cmd.command],
+            )
+            self._save_state(new_state)
+            return
+
+        idle_time = cmd.ts - state.last_command_ts
+        repo_changed = cmd.repo != state.last_repo
+
+        # Session boundary: >300s idle OR repo change
+        if idle_time > 300 or repo_changed:
+            self._close_session(state)
+            # Start new session
+            new_state = SessionState(
+                session_id=uuid.uuid4().hex,
+                last_command_ts=cmd.ts,
+                last_repo=cmd.repo,
+                commands=[cmd.command],
+            )
+            self._save_state(new_state)
+        else:
+            # Continue current session
+            state.commands.append(cmd.command)
+            state.last_command_ts = cmd.ts
+            state.last_repo = cmd.repo
+            self._save_state(state)
+
+    def _close_session(self, state: SessionState) -> None:
+        """Close and persist a completed session."""
+        if not state.commands:
+            return
+
+        # Generate summary — use first command as fallback when AI unavailable
+        summary = self._generate_summary(state.commands, state.last_repo)
+
+        session = WorkSession(
+            id=state.session_id,
+            summary=summary,
+            started_at=state.last_command_ts - (len(state.commands) * 10),  # approximate
+            ended_at=state.last_command_ts,
+            dir="",  # not tracked in state for simplicity
+            repo=state.last_repo,
+            commands=state.commands,
+        )
+        storage.append_session(session)
+
+    def _generate_summary(self, commands: list[str], repo: str | None) -> str:
+        """Generate a session summary.
+
+        Uses Apple FM SDK if available, otherwise falls back to
+        using the first command as the summary.
+        """
+        try:
+            import asyncio
+            from mem.patterns import generate_session_summary
+            result = asyncio.run(generate_session_summary(commands))
+            if result:
+                return result
+        except Exception:
+            pass
+
+        # Fallback: first command + count
+        if len(commands) == 1:
+            return commands[0]
+        return f"{commands[0]} (+{len(commands) - 1} more commands)"