memstrata 0.6.0__tar.gz

memstrata-0.6.0/LICENSE

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

memstrata-0.6.0/PKG-INFO

@@ -0,0 +1,182 @@
+Metadata-Version: 2.4
+Name: memstrata
+Version: 0.6.0
+Summary: A local-first, verification-first context engine for AI workflows
+License: MIT License
+        
+        Copyright (c) 2026 MemStrata Contributors
+        
+        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.
+        
+Project-URL: Homepage, https://memstrata.dev
+Project-URL: Repository, https://github.com/yadu9989/MemStrata
+Project-URL: Issues, https://github.com/yadu9989/MemStrata/issues
+Keywords: llm,context,memory,mcp,local-first,ai-tools
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+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 :: Software Development
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: fastapi>=0.115
+Requires-Dist: uvicorn[standard]>=0.32
+Requires-Dist: httpx>=0.27
+Requires-Dist: pydantic>=2.10
+Requires-Dist: sqlite-vec>=0.1.6
+Requires-Dist: tree-sitter>=0.22
+Requires-Dist: tree-sitter-python>=0.21
+Requires-Dist: tree-sitter-javascript>=0.21
+Requires-Dist: tree-sitter-typescript>=0.21
+Requires-Dist: mcp>=1.0
+Requires-Dist: truststore>=0.9; python_version >= "3.10"
+Requires-Dist: python-dotenv>=1.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
+Requires-Dist: ruff>=0.6; extra == "dev"
+Requires-Dist: mypy>=1.11; extra == "dev"
+Requires-Dist: respx>=0.21; extra == "dev"
+Dynamic: license-file
+
+# MemStrata
+
+**A local-first, verification-first context engine for AI workflows.**
+
+MemStrata sits between you and every AI tool you use. It captures conversations
+from the browser, indexes your codebase locally, and serves a context block to
+whichever LLM you're talking to next. Your code stays on your machine. Your
+conversation history stays on your machine. No telemetry leaves the box.
+
+This repository is the **open-source core**: the local daemon, the chat-capture
+browser extension, the MCP server, and the dashboard. It is MIT-licensed and
+fully usable on its own.
+
+The commercial Pro tier (token-budgeted context injection through a proxy
+harness, money-back-guaranteed savings, IDE integration) lives in a separate,
+private repository and consumes this package as a PyPI dependency. See
+[memstrata.dev](https://memstrata.dev) if you want the paid product.
+
+---
+
+## What's in this repo
+
+| Path | What it does |
+|---|---|
+| `memstrata/layer3/api_server.py` | The local daemon's FastAPI app — telemetry, dashboard, MCP routing |
+| `memstrata/layer3/ingestion/` | File watcher, tree-sitter chunker, opt-in lifecycle, denylists |
+| `memstrata/layer3/mcp_server.py`, `mcp_app.py` | MCP server (Anthropic-spec) for Claude Desktop / Cursor / etc. |
+| `memstrata/layer3/_db.py` | SQLite schema with `sqlite-vec` for local vector search |
+| `memstrata/layer3/retrieval.py` | Token-budgeted context retrieval against the local store |
+| `memstrata/layer3/pricing/` | Live OpenRouter price sync + bundled static fallback for offline use |
+| `memstrata/layer3/ollama_health.py` | Shared Ollama reachability probe (used by the dashboard) |
+| `memstrata/workers/embedding_worker.py` | Background worker that embeds new turns into the vector store |
+| `memstrata/cli/` | The `memstrata` CLI: `register`, `ingest`, the cd-hook generator |
+| `memstrata/config/keychain.py` | OS keyring wrapper for storing per-provider API keys |
+| `browser-extension/` | Chrome / Edge / Firefox extension that captures chat turns from every major LLM front-end |
+| `migrations/` | SQL migrations |
+| `shared/telemetry_schema.json` | The JSON schema for telemetry events (public contract) |
+
+---
+
+## Quickstart
+
+```bash
+pip install memstrata
+memstrata init     # one-time interactive setup
+memstrata api      # start the daemon on 127.0.0.1:8000
+```
+
+The daemon binds to `127.0.0.1:8000`. Open `http://127.0.0.1:8000/dashboard`
+to see what's captured.
+
+Install the browser extension from your browser's add-on store (see the
+[browser-extension/](browser-extension/) directory for build instructions
+if you want to load it unpacked).
+
+---
+
+## Architecture commitments
+
+These aren't aspirational — they're enforced in the code and tested for in CI:
+
+1. **Localhost-only binding.** Every HTTP server in this repo hard-codes
+   `host="127.0.0.1"`. No `0.0.0.0`, no LAN exposure, no remote access.
+
+2. **No TLS interception.** The MCP server and the dashboard speak plain
+   HTTP on loopback. The browser extension talks directly to provider
+   APIs and to this daemon's loopback endpoint. There is no MITM proxy
+   in the open-source stack.
+
+3. **Local storage only.** All telemetry, all chat history, all vectors,
+   all API keys live in `~/.memstrata/` (or `$ML_DATA_DIR` if set).
+   Nothing is uploaded to a MemStrata-owned cloud service. There is no
+   such service.
+
+4. **Telemetry never includes user content.** The dashboard and the
+   MCP server expose your data back to you. Nothing is sent off-machine.
+
+5. **The Pro tier is structurally separate.** Pro code lives in a
+   different repository under a different license. This repo has
+   zero `import` statements that touch Pro code.
+
+---
+
+## Provider pricing (for the dashboard's savings calculator)
+
+The dashboard's session-level savings columns compute against a price
+table. By default the daemon syncs the table once per day from
+[OpenRouter](https://openrouter.ai/api/v1/models). When the network is
+down or OpenRouter is unreachable, the bundled
+`memstrata/layer3/pricing/pricing_matrix.json` provides a static
+fallback. The fallback covers the most common Claude, OpenAI, Gemini,
+DeepSeek, xAI, and Mistral models. Prices in the fallback are
+USD-per-million-tokens, last verified mid-2026.
+
+---
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md). The short version: open issues
+first for non-trivial changes, run `pytest` before submitting, and keep
+the architectural commitments above intact.
+
+## Security
+
+See [SECURITY.md](SECURITY.md). Vulnerability reports go to
+`security@memstrata.dev`, **not** GitHub issues.
+
+## License
+
+[MIT](LICENSE). See `LICENSE` for the full text.
+
+## Related
+
+- **Commercial Pro tier**: [memstrata.dev](https://memstrata.dev) — the
+  token-budgeting interception harness, the money-back guarantee, and
+  the IDE extension. Proprietary, paid, separate codebase.
+- **Browser extension store listings**: shipped from the same source
+  tree in this repo; see [browser-extension/README.md](browser-extension/)
+  for build + sideload instructions.

memstrata-0.6.0/README.md

@@ -0,0 +1,119 @@
+# MemStrata
+
+**A local-first, verification-first context engine for AI workflows.**
+
+MemStrata sits between you and every AI tool you use. It captures conversations
+from the browser, indexes your codebase locally, and serves a context block to
+whichever LLM you're talking to next. Your code stays on your machine. Your
+conversation history stays on your machine. No telemetry leaves the box.
+
+This repository is the **open-source core**: the local daemon, the chat-capture
+browser extension, the MCP server, and the dashboard. It is MIT-licensed and
+fully usable on its own.
+
+The commercial Pro tier (token-budgeted context injection through a proxy
+harness, money-back-guaranteed savings, IDE integration) lives in a separate,
+private repository and consumes this package as a PyPI dependency. See
+[memstrata.dev](https://memstrata.dev) if you want the paid product.
+
+---
+
+## What's in this repo
+
+| Path | What it does |
+|---|---|
+| `memstrata/layer3/api_server.py` | The local daemon's FastAPI app — telemetry, dashboard, MCP routing |
+| `memstrata/layer3/ingestion/` | File watcher, tree-sitter chunker, opt-in lifecycle, denylists |
+| `memstrata/layer3/mcp_server.py`, `mcp_app.py` | MCP server (Anthropic-spec) for Claude Desktop / Cursor / etc. |
+| `memstrata/layer3/_db.py` | SQLite schema with `sqlite-vec` for local vector search |
+| `memstrata/layer3/retrieval.py` | Token-budgeted context retrieval against the local store |
+| `memstrata/layer3/pricing/` | Live OpenRouter price sync + bundled static fallback for offline use |
+| `memstrata/layer3/ollama_health.py` | Shared Ollama reachability probe (used by the dashboard) |
+| `memstrata/workers/embedding_worker.py` | Background worker that embeds new turns into the vector store |
+| `memstrata/cli/` | The `memstrata` CLI: `register`, `ingest`, the cd-hook generator |
+| `memstrata/config/keychain.py` | OS keyring wrapper for storing per-provider API keys |
+| `browser-extension/` | Chrome / Edge / Firefox extension that captures chat turns from every major LLM front-end |
+| `migrations/` | SQL migrations |
+| `shared/telemetry_schema.json` | The JSON schema for telemetry events (public contract) |
+
+---
+
+## Quickstart
+
+```bash
+pip install memstrata
+memstrata init     # one-time interactive setup
+memstrata api      # start the daemon on 127.0.0.1:8000
+```
+
+The daemon binds to `127.0.0.1:8000`. Open `http://127.0.0.1:8000/dashboard`
+to see what's captured.
+
+Install the browser extension from your browser's add-on store (see the
+[browser-extension/](browser-extension/) directory for build instructions
+if you want to load it unpacked).
+
+---
+
+## Architecture commitments
+
+These aren't aspirational — they're enforced in the code and tested for in CI:
+
+1. **Localhost-only binding.** Every HTTP server in this repo hard-codes
+   `host="127.0.0.1"`. No `0.0.0.0`, no LAN exposure, no remote access.
+
+2. **No TLS interception.** The MCP server and the dashboard speak plain
+   HTTP on loopback. The browser extension talks directly to provider
+   APIs and to this daemon's loopback endpoint. There is no MITM proxy
+   in the open-source stack.
+
+3. **Local storage only.** All telemetry, all chat history, all vectors,
+   all API keys live in `~/.memstrata/` (or `$ML_DATA_DIR` if set).
+   Nothing is uploaded to a MemStrata-owned cloud service. There is no
+   such service.
+
+4. **Telemetry never includes user content.** The dashboard and the
+   MCP server expose your data back to you. Nothing is sent off-machine.
+
+5. **The Pro tier is structurally separate.** Pro code lives in a
+   different repository under a different license. This repo has
+   zero `import` statements that touch Pro code.
+
+---
+
+## Provider pricing (for the dashboard's savings calculator)
+
+The dashboard's session-level savings columns compute against a price
+table. By default the daemon syncs the table once per day from
+[OpenRouter](https://openrouter.ai/api/v1/models). When the network is
+down or OpenRouter is unreachable, the bundled
+`memstrata/layer3/pricing/pricing_matrix.json` provides a static
+fallback. The fallback covers the most common Claude, OpenAI, Gemini,
+DeepSeek, xAI, and Mistral models. Prices in the fallback are
+USD-per-million-tokens, last verified mid-2026.
+
+---
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md). The short version: open issues
+first for non-trivial changes, run `pytest` before submitting, and keep
+the architectural commitments above intact.
+
+## Security
+
+See [SECURITY.md](SECURITY.md). Vulnerability reports go to
+`security@memstrata.dev`, **not** GitHub issues.
+
+## License
+
+[MIT](LICENSE). See `LICENSE` for the full text.
+
+## Related
+
+- **Commercial Pro tier**: [memstrata.dev](https://memstrata.dev) — the
+  token-budgeting interception harness, the money-back guarantee, and
+  the IDE extension. Proprietary, paid, separate codebase.
+- **Browser extension store listings**: shipped from the same source
+  tree in this repo; see [browser-extension/README.md](browser-extension/)
+  for build + sideload instructions.

memstrata-0.6.0/memstrata/__init__.py

@@ -0,0 +1,2 @@
+"""MemStrata — MIT open-source context server for LLM-assisted coding."""
+__version__ = "0.6.0"

memstrata-0.6.0/memstrata/cli/cd_hook.py

@@ -0,0 +1,148 @@
+"""
+Shell cd-hook generation and idempotent installation.
+
+Hook text and write/remove patterns taken verbatim from
+v5_1_reference/critical_snippets.py §2. The idempotent marker pair
+ensures repeated writes replace rather than duplicate the block.
+
+Hard Rule 54: hooks only check for .git/ — no process scanning.
+"""
+from __future__ import annotations
+
+import os
+import sys
+from pathlib import Path
+from typing import Optional
+
+_HOOK_MARKER_BEGIN = "# >>> memstrata cd-hook >>>"
+_HOOK_MARKER_END   = "# <<< memstrata cd-hook <<<"
+
+
+def hook_for_shell(shell: str) -> str:
+    """
+    Generate the hook block for the given shell.
+
+    The returned string is delimited by _HOOK_MARKER_BEGIN / _HOOK_MARKER_END
+    so write_hook can replace it idempotently.
+    """
+    if shell == "zsh":
+        body = """
+ml_cd_hook() {
+    if [ -d ".git" ] && command -v memstrata >/dev/null 2>&1; then
+        (memstrata register "$PWD" --quiet >/dev/null 2>&1 &)
+    fi
+}
+typeset -gaU chpwd_functions
+chpwd_functions+=(ml_cd_hook)
+"""
+    elif shell == "bash":
+        body = """
+ml_cd_hook() {
+    if [ -d ".git" ] && command -v memstrata >/dev/null 2>&1; then
+        (memstrata register "$PWD" --quiet >/dev/null 2>&1 &)
+    fi
+}
+PROMPT_COMMAND="ml_cd_hook;${PROMPT_COMMAND:-:}"
+"""
+    elif shell == "fish":
+        body = """
+function ml_cd_hook --on-variable PWD
+    if test -d .git
+        if command -v memstrata >/dev/null 2>&1
+            memstrata register "$PWD" --quiet >/dev/null 2>&1 &
+        end
+    end
+end
+"""
+    elif shell == "powershell":
+        body = """
+$global:__MlOriginalPrompt = if (Test-Path Function:prompt) { Get-Item Function:prompt } else { $null }
+function global:prompt {
+    if (Test-Path -PathType Container ".git") {
+        if (Get-Command memstrata -ErrorAction SilentlyContinue) {
+            Start-Job -ScriptBlock {
+                param($p) memstrata register $p --quiet
+            } -ArgumentList $PWD.Path | Out-Null
+        }
+    }
+    if ($global:__MlOriginalPrompt) { & $global:__MlOriginalPrompt }
+    else { "PS $($executionContext.SessionState.Path.CurrentLocation)$('>' * ($nestedPromptLevel + 1)) " }
+}
+"""
+    else:
+        raise ValueError(f"unsupported shell: {shell!r}")
+
+    return f"\n{_HOOK_MARKER_BEGIN}\n{body.strip()}\n{_HOOK_MARKER_END}\n"
+
+
+def write_hook(shell: str, config_path: Path) -> None:
+    """
+    Idempotently install the hook into config_path.
+
+    If the marker block is already present it is replaced in-place.
+    Otherwise the block is appended. A .ml-backup is created once on
+    the first write (never overwritten on subsequent writes).
+    """
+    backup = config_path.with_suffix(config_path.suffix + ".ml-backup")
+    if config_path.exists() and not backup.exists():
+        backup.write_text(config_path.read_text(encoding="utf-8"), encoding="utf-8")
+
+    existing = config_path.read_text(encoding="utf-8") if config_path.exists() else ""
+    new_block = hook_for_shell(shell)
+
+    if _HOOK_MARKER_BEGIN in existing:
+        before, _, rest = existing.partition(_HOOK_MARKER_BEGIN)
+        _, _, after = rest.partition(_HOOK_MARKER_END)
+        after = after.lstrip("\n")
+        result = before.rstrip() + new_block + ("\n" + after if after else "")
+    else:
+        # new_block already starts with "\n", so rstrip() + new_block gives one separator.
+        result = existing.rstrip() + new_block
+
+    config_path.parent.mkdir(parents=True, exist_ok=True)
+    config_path.write_text(result, encoding="utf-8")
+
+
+def remove_hook(config_path: Path) -> None:
+    """
+    Reverse write_hook. Strips the marker block from config_path in-place.
+    No-op if the file is missing or the block was never written.
+    """
+    if not config_path.exists():
+        return
+    text = config_path.read_text(encoding="utf-8")
+    if _HOOK_MARKER_BEGIN not in text:
+        return
+    before, _, rest = text.partition(_HOOK_MARKER_BEGIN)
+    _, _, after = rest.partition(_HOOK_MARKER_END)
+    config_path.write_text(before.rstrip() + "\n" + after.lstrip("\n"), encoding="utf-8")
+
+
+def detect_shell() -> str | None:
+    """Best-effort shell detection from the environment."""
+    shell_env = os.environ.get("SHELL", "")
+    if "zsh" in shell_env:
+        return "zsh"
+    if "bash" in shell_env:
+        return "bash"
+    if "fish" in shell_env:
+        return "fish"
+    if os.environ.get("PSModulePath") and not shell_env:
+        return "powershell"
+    return None
+
+
+def config_path_for_shell(shell: str) -> Path:
+    """Return the canonical config file path for the given shell."""
+    home = Path.home()
+    if shell == "zsh":
+        return home / ".zshrc"
+    if shell == "bash":
+        return home / ".bashrc"
+    if shell == "fish":
+        return home / ".config" / "fish" / "config.fish"
+    if shell == "powershell":
+        if sys.platform == "win32":
+            return home / "Documents" / "PowerShell" / "Microsoft.PowerShell_profile.ps1"
+        return home / ".config" / "powershell" / "Microsoft.PowerShell_profile.ps1"
+    raise ValueError(f"unsupported shell: {shell!r}")