mcp-memex 0.1.0__tar.gz

mcp_memex-0.1.0/.claude/settings.local.json

@@ -0,0 +1,7 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(gh pr *)"
+    ]
+  }
+}

mcp_memex-0.1.0/.gitignore

@@ -0,0 +1,11 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.venv/
+venv/
+.env
+*.db
+*.db-shm
+*.db-wal

mcp_memex-0.1.0/CLAUDE.md

@@ -0,0 +1,32 @@
+## memex: Session Memory
+
+At the **start of every session**, call `mem_load` with a brief hint about
+what you're working on. This gives you context from past sessions so you
+don't rediscover things you already know.
+
+```
+mem_load(hint="<what you're about to work on>", files=["<relevant files>"])
+```
+
+During a session, call `mem_save` whenever you:
+- Finish a meaningful task
+- Make an architectural or design decision
+- Discover something surprising or easy to get wrong
+
+```
+mem_save(
+    task="One-sentence summary of what was done",
+    files=["list", "of", "files", "touched"],
+    decisions=["Any design decisions made"],
+    warnings=["Anything surprising or easy to get wrong"],
+    tags=["short", "labels"],
+    notes="Any extra freeform context"
+)
+```
+
+Other tools:
+- `mem_search(query)` — find past work on a specific topic
+- `mem_list()` — see all stored entries
+- `mem_delete(id)` — remove stale entries
+
+Memory is stored locally in ~/.memex/ as SQLite — no LLMs, no network.

mcp_memex-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,36 @@
+# Contributing to memex
+
+Thanks for wanting to help. Here's everything you need to get started.
+
+## Setup
+
+```bash
+git clone https://github.com/pragneshbagary/memex.git
+cd memex
+python3 -m pip install -e ".[dev]"
+```
+
+The only runtime dependency is `mcp`. No build tools, no database to spin up.
+
+## Where to start
+
+Check the [`good first issue`](https://github.com/pragneshbagary/memex/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22) label — these are self-contained and well-scoped.
+
+The two main files:
+
+| File | What it contains |
+|------|-----------------|
+| `memex/server.py` | The MCP server and all five tools (`mem_save`, `mem_load`, etc.) |
+| `memex/cli.py` | The `memex` CLI (`install`, `remove`, `list`, `search`) |
+
+## Submitting a PR
+
+1. Fork the repo and create a branch
+2. Make your change
+3. Make sure `memex install` and `memex list` still work
+4. Open a PR — describe what you changed and why
+
+
+## Questions
+
+Open an issue or start a discussion. Happy to help.

mcp_memex-0.1.0/LICENSE

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

mcp_memex-0.1.0/PKG-INFO

@@ -0,0 +1,127 @@
+Metadata-Version: 2.4
+Name: mcp-memex
+Version: 0.1.0
+Summary: Persistent session memory for Claude Code — local SQLite, no LLMs, no network
+Project-URL: Repository, https://github.com/pragneshbagary/memex
+Project-URL: Issues, https://github.com/pragneshbagary/memex/issues
+License: MIT
+License-File: LICENSE
+Requires-Python: >=3.10
+Requires-Dist: mcp>=1.0
+Description-Content-Type: text/markdown
+
+# memex
+
+Every Claude Code session starts without knowing what you built last time — which files you changed, what decisions you made, what broke. You re-explain. Claude re-reads. You start over.
+
+**memex keeps a structured log of every session. Claude reads it at the start of the next one.**
+
+No cloud. No LLM extraction. No cost per save. Just local SQLite and two commands to install.
+
+## Install
+
+```bash
+pip install memex
+memex install
+```
+
+Restart Claude Code. That's it.
+
+## What gets saved
+
+Each entry has structure — not a blob of text:
+
+```python
+mem_save(
+    task="Replaced JWT auth with session cookies",
+    files=["src/auth.py", "src/middleware.py"],
+    decisions=["Session cookies over JWT — simpler, no token refresh needed"],
+    warnings=["Redis required — app won't start without REDIS_URL set"],
+    tags=["auth", "sessions"]
+)
+```
+
+Claude calls `mem_save` when it finishes something meaningful. You can also just tell it: *"save what we just did."*
+
+## What Claude sees at session start
+
+```
+=== memex: session context (db: my_project.db) ===
+
+--- Recent (2) ---
+[1] #4 — 2026-06-14T10:32
+  Task      : Replaced JWT auth with session cookies
+  Files     : src/auth.py, src/middleware.py
+  Decision  : Session cookies over JWT — simpler, no token refresh needed
+  Warning   : Redis required — app won't start without REDIS_URL set
+  Tags      : auth, sessions
+
+[2] #3 — 2026-06-13T15:10
+  Task      : Added rate limiting to /api/login
+  Files     : src/middleware.py
+  Warning   : Rate limiter is in-memory per process — resets on restart
+  Tags      : auth, rate-limiting
+```
+
+Claude calls `mem_load` automatically at the start of every session. It returns the most recent entries plus any entries that match what you're working on — by keyword and by file path.
+
+## Browse from the terminal
+
+You don't need to be inside Claude to look at your history:
+
+```bash
+memex list                  # recent entries for this project
+memex list --tag auth       # filter by tag
+memex search "rate limit"   # full-text search
+```
+
+## Five MCP tools
+
+| Tool | What it does |
+|------|--------------|
+| `mem_load` | Called at session start — returns recent + relevant entries |
+| `mem_save` | Saves a structured entry after meaningful work |
+| `mem_search` | Full-text search across all entries |
+| `mem_list` | Lists entries, optionally filtered by tag |
+| `mem_delete` | Removes a stale entry by id |
+
+## Why not just CLAUDE.md?
+
+`CLAUDE.md` is for static project documentation — architecture, conventions, how to run tests. It doesn't change much and it isn't session-aware.
+
+memex captures what's changing session to session: what you built yesterday, the decision you made this morning, the warning you discovered an hour ago. It's the difference between *"here's the project"* and *"here's what happened last time."*
+
+## Memory is scoped per project
+
+Each project gets its own SQLite database at `~/.memex/<project>.db` based on the working directory. Sessions from different projects never mix.
+
+## Configuration
+
+Set these in the MCP `env` block in `~/.claude.json` if you need to override defaults:
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `MEMEX_DIR` | `~/.memex` | Where DBs are stored |
+| `MEMEX_GLOBAL` | `0` | Set to `1` to share one DB across all projects |
+| `MEMEX_RECENT` | `5` | Max recent entries loaded per session |
+| `MEMEX_MATCHED` | `5` | Max FTS-matched entries loaded per session |
+
+## Uninstall
+
+```bash
+memex remove
+pip uninstall memex
+```
+
+Memory DBs are kept at `~/.memex/` — delete that directory manually if you want to wipe everything.
+
+## Requirements
+
+- Python 3.10+
+- `mcp` package (installed automatically)
+- SQLite with FTS5 (standard since Python 3.8)
+- Claude Code CLI
+
+## License
+
+MIT

mcp_memex-0.1.0/README.md

@@ -0,0 +1,115 @@
+# memex
+
+Every Claude Code session starts without knowing what you built last time — which files you changed, what decisions you made, what broke. You re-explain. Claude re-reads. You start over.
+
+**memex keeps a structured log of every session. Claude reads it at the start of the next one.**
+
+No cloud. No LLM extraction. No cost per save. Just local SQLite and two commands to install.
+
+## Install
+
+```bash
+pip install memex
+memex install
+```
+
+Restart Claude Code. That's it.
+
+## What gets saved
+
+Each entry has structure — not a blob of text:
+
+```python
+mem_save(
+    task="Replaced JWT auth with session cookies",
+    files=["src/auth.py", "src/middleware.py"],
+    decisions=["Session cookies over JWT — simpler, no token refresh needed"],
+    warnings=["Redis required — app won't start without REDIS_URL set"],
+    tags=["auth", "sessions"]
+)
+```
+
+Claude calls `mem_save` when it finishes something meaningful. You can also just tell it: *"save what we just did."*
+
+## What Claude sees at session start
+
+```
+=== memex: session context (db: my_project.db) ===
+
+--- Recent (2) ---
+[1] #4 — 2026-06-14T10:32
+  Task      : Replaced JWT auth with session cookies
+  Files     : src/auth.py, src/middleware.py
+  Decision  : Session cookies over JWT — simpler, no token refresh needed
+  Warning   : Redis required — app won't start without REDIS_URL set
+  Tags      : auth, sessions
+
+[2] #3 — 2026-06-13T15:10
+  Task      : Added rate limiting to /api/login
+  Files     : src/middleware.py
+  Warning   : Rate limiter is in-memory per process — resets on restart
+  Tags      : auth, rate-limiting
+```
+
+Claude calls `mem_load` automatically at the start of every session. It returns the most recent entries plus any entries that match what you're working on — by keyword and by file path.
+
+## Browse from the terminal
+
+You don't need to be inside Claude to look at your history:
+
+```bash
+memex list                  # recent entries for this project
+memex list --tag auth       # filter by tag
+memex search "rate limit"   # full-text search
+```
+
+## Five MCP tools
+
+| Tool | What it does |
+|------|--------------|
+| `mem_load` | Called at session start — returns recent + relevant entries |
+| `mem_save` | Saves a structured entry after meaningful work |
+| `mem_search` | Full-text search across all entries |
+| `mem_list` | Lists entries, optionally filtered by tag |
+| `mem_delete` | Removes a stale entry by id |
+
+## Why not just CLAUDE.md?
+
+`CLAUDE.md` is for static project documentation — architecture, conventions, how to run tests. It doesn't change much and it isn't session-aware.
+
+memex captures what's changing session to session: what you built yesterday, the decision you made this morning, the warning you discovered an hour ago. It's the difference between *"here's the project"* and *"here's what happened last time."*
+
+## Memory is scoped per project
+
+Each project gets its own SQLite database at `~/.memex/<project>.db` based on the working directory. Sessions from different projects never mix.
+
+## Configuration
+
+Set these in the MCP `env` block in `~/.claude.json` if you need to override defaults:
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `MEMEX_DIR` | `~/.memex` | Where DBs are stored |
+| `MEMEX_GLOBAL` | `0` | Set to `1` to share one DB across all projects |
+| `MEMEX_RECENT` | `5` | Max recent entries loaded per session |
+| `MEMEX_MATCHED` | `5` | Max FTS-matched entries loaded per session |
+
+## Uninstall
+
+```bash
+memex remove
+pip uninstall memex
+```
+
+Memory DBs are kept at `~/.memex/` — delete that directory manually if you want to wipe everything.
+
+## Requirements
+
+- Python 3.10+
+- `mcp` package (installed automatically)
+- SQLite with FTS5 (standard since Python 3.8)
+- Claude Code CLI
+
+## License
+
+MIT

mcp_memex-0.1.0/memex/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

mcp_memex-0.1.0/memex/cli.py

@@ -0,0 +1,266 @@
+#!/usr/bin/env python3
+"""
+memex CLI — wire memex into Claude Code and browse memories from the terminal.
+
+Usage:
+    memex install              # global (~/.claude.json)
+    memex install --local      # this project only (.claude.json)
+    memex remove               # remove from config
+    memex list [--tag TAG]     # show recent entries for this project
+    memex search QUERY         # search entries for this project
+    memex version              # print version
+"""
+
+import argparse
+import json
+import os
+import re
+import sqlite3
+import sys
+from pathlib import Path
+
+from memex import __version__
+
+GLOBAL_CONFIG = Path.home() / ".claude.json"
+LOCAL_CONFIG = Path.cwd() / ".claude.json"
+
+CLAUDE_MD_SNIPPET = """
+## memex: Session Memory
+
+At the **start of every session**, call `mem_load` with a brief hint about
+what you're working on. This gives you context from past sessions so you
+don't rediscover things you already know.
+
+```
+mem_load(hint="<what you're about to work on>", files=["<relevant files>"])
+```
+
+During a session, call `mem_save` whenever you:
+- Finish a meaningful task
+- Make an architectural or design decision
+- Discover something surprising or easy to get wrong
+
+```
+mem_save(
+    task="One-sentence summary of what was done",
+    files=["list", "of", "files", "touched"],
+    decisions=["Any design decisions made"],
+    warnings=["Anything surprising or easy to get wrong"],
+    tags=["short", "labels"],
+    notes="Any extra freeform context"
+)
+```
+
+Other tools:
+- `mem_search(query)` — find past work on a specific topic
+- `mem_list()` — see all stored entries
+- `mem_delete(id)` — remove stale entries
+
+Memory is stored locally in ~/.memex/ as SQLite — no LLMs, no network.
+""".strip()
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+def _load_json(path: Path) -> dict:
+    if path.exists():
+        try:
+            return json.loads(path.read_text())
+        except json.JSONDecodeError:
+            print(f"  ⚠ Could not parse {path} — treating as empty")
+    return {}
+
+
+def _save_json(path: Path, data: dict) -> None:
+    path.write_text(json.dumps(data, indent=2) + "\n")
+
+
+def _db_path() -> Path:
+    db_dir = Path(os.environ.get("MEMEX_DIR", Path.home() / ".memex"))
+    if os.environ.get("MEMEX_GLOBAL", "0") == "1":
+        return db_dir / "global.db"
+    cwd = os.environ.get("MEMEX_PROJECT", os.getcwd())
+    safe = re.sub(r"[^a-zA-Z0-9_\-]", "_", cwd).strip("_")[:120]
+    return db_dir / f"{safe}.db"
+
+
+def _format_row(row: dict) -> str:
+    lines = [f"#{row['id']} — {row['timestamp'][:16]}  {row['task']}"]
+    for field, label in (("files", "Files"), ("decisions", "Decision"), ("warnings", "Warning")):
+        try:
+            items = json.loads(row[field])
+        except (json.JSONDecodeError, TypeError):
+            items = []
+        for item in items:
+            lines.append(f"  {label:<9}: {item}")
+    if row.get("raw"):
+        lines.append(f"  Notes    : {row['raw']}")
+    return "\n".join(lines)
+
+
+# ---------------------------------------------------------------------------
+# Commands
+# ---------------------------------------------------------------------------
+
+def install(local: bool = False) -> None:
+    config_path = LOCAL_CONFIG if local else GLOBAL_CONFIG
+    scope = "local project" if local else "global"
+    print(f"Installing memex ({scope})...")
+
+    config = _load_json(config_path)
+    config.setdefault("mcpServers", {})
+
+    config["mcpServers"]["memex"] = {
+        "type": "stdio",
+        "command": sys.executable,
+        "args": ["-m", "memex.server"],
+    }
+
+    _save_json(config_path, config)
+    print(f"  ✓ MCP entry written: {config_path}")
+
+    claude_md = Path.cwd() / "CLAUDE.md"
+    if claude_md.exists():
+        existing = claude_md.read_text()
+        if "memex" in existing:
+            print("  ✓ CLAUDE.md already has memex section — skipped")
+        else:
+            claude_md.write_text(existing.rstrip() + "\n\n" + CLAUDE_MD_SNIPPET + "\n")
+            print("  ✓ Appended memex section to CLAUDE.md")
+    else:
+        claude_md.write_text(CLAUDE_MD_SNIPPET + "\n")
+        print("  ✓ Created CLAUDE.md")
+
+    print()
+    print("Done! Start a new Claude Code session — memex will be active automatically.")
+    print(f"Memory DB location: ~/.memex/")
+
+
+def remove() -> None:
+    print("Removing memex...")
+    removed = False
+    for config_path in [GLOBAL_CONFIG, LOCAL_CONFIG]:
+        config = _load_json(config_path)
+        mcp_servers = config.get("mcpServers", {})
+        for key in ("memex", "claude-mem"):
+            if key in mcp_servers:
+                del mcp_servers[key]
+                _save_json(config_path, config)
+                print(f"  ✓ Removed '{key}' from {config_path}")
+                removed = True
+
+    if not removed:
+        print("  — memex not found in any Claude Code config")
+
+    print()
+    print("Note: memory DBs kept at ~/.memex/ — delete manually if you want to wipe them.")
+
+
+def list_entries(tag: str | None = None, limit: int = 20) -> None:
+    db = _db_path()
+    if not db.exists():
+        print("No memories saved for this project yet.")
+        return
+
+    conn = sqlite3.connect(db)
+    conn.row_factory = sqlite3.Row
+    if tag:
+        rows = conn.execute(
+            "SELECT * FROM entries WHERE tags LIKE ? ORDER BY id DESC LIMIT ?",
+            (f'%"{tag}"%', limit),
+        ).fetchall()
+    else:
+        rows = conn.execute(
+            "SELECT * FROM entries ORDER BY id DESC LIMIT ?", (limit,)
+        ).fetchall()
+    conn.close()
+
+    if not rows:
+        print(f"No entries{f' with tag {tag!r}' if tag else ''}.")
+        return
+
+    print(f"=== memex: {len(rows)} entries ({db.name}) ===\n")
+    for row in rows:
+        print(_format_row(dict(row)))
+        print()
+
+
+def search_entries(query: str, limit: int = 10) -> None:
+    db = _db_path()
+    if not db.exists():
+        print("No memories saved for this project yet.")
+        return
+
+    safe = re.sub(r"[^a-zA-Z0-9 _\-]", " ", query).strip()
+    if not safe:
+        print("Query is empty after sanitisation.")
+        return
+
+    conn = sqlite3.connect(db)
+    conn.row_factory = sqlite3.Row
+    rows = conn.execute(
+        """SELECT e.* FROM entries e
+           JOIN entries_fts f ON f.rowid = e.id
+           WHERE entries_fts MATCH ?
+           ORDER BY rank LIMIT ?""",
+        (safe, limit),
+    ).fetchall()
+    conn.close()
+
+    if not rows:
+        print(f"No entries matched '{query}'.")
+        return
+
+    print(f"=== memex: {len(rows)} results for '{query}' ===\n")
+    for row in rows:
+        print(_format_row(dict(row)))
+        print()
+
+
+# ---------------------------------------------------------------------------
+# Entry point
+# ---------------------------------------------------------------------------
+
+def main() -> None:
+    parser = argparse.ArgumentParser(
+        description="memex — persistent session memory for Claude Code",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+    subparsers = parser.add_subparsers(dest="command", metavar="command")
+
+    install_parser = subparsers.add_parser("install", help="Install memex into Claude Code")
+    install_parser.add_argument("--local", action="store_true",
+                                help="Install for this project only")
+
+    subparsers.add_parser("remove", help="Remove memex from Claude Code config")
+
+    list_parser = subparsers.add_parser("list", help="Show recent memory entries")
+    list_parser.add_argument("--tag", help="Filter by tag")
+    list_parser.add_argument("--limit", type=int, default=20, help="Max entries (default 20)")
+
+    search_parser = subparsers.add_parser("search", help="Search memory entries")
+    search_parser.add_argument("query", help="Search query")
+    search_parser.add_argument("--limit", type=int, default=10, help="Max results (default 10)")
+
+    subparsers.add_parser("version", help="Print version")
+
+    args = parser.parse_args()
+
+    if args.command == "install":
+        install(local=args.local)
+    elif args.command == "remove":
+        remove()
+    elif args.command == "list":
+        list_entries(tag=args.tag, limit=args.limit)
+    elif args.command == "search":
+        search_entries(query=args.query, limit=args.limit)
+    elif args.command == "version":
+        print(f"memex {__version__}")
+    else:
+        parser.print_help()
+
+
+if __name__ == "__main__":
+    main()

mcp_memex-0.1.0/memex/server.py

@@ -0,0 +1,373 @@
+#!/usr/bin/env python3
+"""
+memex: Persistent session memory for Claude Code.
+No LLMs, no embeddings — just SQLite + FTS5 + structured entries.
+
+Tools exposed via MCP:
+  mem_save   — save a session entry (task, decisions, warnings, files, tags)
+  mem_load   — retrieve relevant entries for a new session
+  mem_search — free-text search across all entries
+  mem_list   — list recent entries (for inspection / housekeeping)
+  mem_delete — remove an entry by id
+"""
+
+import json
+import os
+import re
+import sqlite3
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Optional
+
+from mcp.server.fastmcp import FastMCP
+
+# ---------------------------------------------------------------------------
+# Config
+# ---------------------------------------------------------------------------
+
+DB_DIR = Path(os.environ.get("MEMEX_DIR", Path.home() / ".memex"))
+DB_DIR.mkdir(parents=True, exist_ok=True)
+
+# By default, memory is scoped per-project using the CWD at server startup.
+# Set MEMEX_GLOBAL=1 to share one DB across all projects.
+_global = os.environ.get("MEMEX_GLOBAL", "0") == "1"
+if _global:
+    DB_PATH = DB_DIR / "global.db"
+else:
+    cwd = os.environ.get("MEMEX_PROJECT", os.getcwd())
+    safe = re.sub(r"[^a-zA-Z0-9_\-]", "_", cwd).strip("_")[:120]
+    DB_PATH = DB_DIR / f"{safe}.db"
+
+MAX_LOAD_RECENT = int(os.environ.get("MEMEX_RECENT", "5"))
+MAX_LOAD_MATCHED = int(os.environ.get("MEMEX_MATCHED", "5"))
+
+# ---------------------------------------------------------------------------
+# DB setup
+# ---------------------------------------------------------------------------
+
+def get_conn() -> sqlite3.Connection:
+    conn = sqlite3.connect(DB_PATH)
+    conn.row_factory = sqlite3.Row
+    conn.execute("PRAGMA journal_mode=WAL")
+    conn.execute("PRAGMA foreign_keys=ON")
+    return conn
+
+
+def init_db() -> None:
+    with get_conn() as conn:
+        conn.executescript("""
+            CREATE TABLE IF NOT EXISTS entries (
+                id          INTEGER PRIMARY KEY AUTOINCREMENT,
+                project     TEXT    NOT NULL DEFAULT '',
+                timestamp   TEXT    NOT NULL,
+                task        TEXT    NOT NULL,
+                files       TEXT    NOT NULL DEFAULT '[]',
+                decisions   TEXT    NOT NULL DEFAULT '[]',
+                warnings    TEXT    NOT NULL DEFAULT '[]',
+                tags        TEXT    NOT NULL DEFAULT '[]',
+                raw         TEXT    NOT NULL DEFAULT ''
+            );
+
+            CREATE VIRTUAL TABLE IF NOT EXISTS entries_fts USING fts5(
+                task,
+                files,
+                decisions,
+                warnings,
+                tags,
+                raw,
+                content='entries',
+                content_rowid='id'
+            );
+
+            CREATE TRIGGER IF NOT EXISTS entries_ai AFTER INSERT ON entries BEGIN
+                INSERT INTO entries_fts(rowid, task, files, decisions, warnings, tags, raw)
+                VALUES (new.id, new.task, new.files, new.decisions, new.warnings, new.tags, new.raw);
+            END;
+
+            CREATE TRIGGER IF NOT EXISTS entries_ad AFTER DELETE ON entries BEGIN
+                INSERT INTO entries_fts(entries_fts, rowid, task, files, decisions, warnings, tags, raw)
+                VALUES ('delete', old.id, old.task, old.files, old.decisions, old.warnings, old.tags, old.raw);
+            END;
+
+            CREATE TRIGGER IF NOT EXISTS entries_au AFTER UPDATE ON entries BEGIN
+                INSERT INTO entries_fts(entries_fts, rowid, task, files, decisions, warnings, tags, raw)
+                VALUES ('delete', old.id, old.task, old.files, old.decisions, old.warnings, old.tags, old.raw);
+                INSERT INTO entries_fts(rowid, task, files, decisions, warnings, tags, raw)
+                VALUES (new.id, new.task, new.files, new.decisions, new.warnings, new.tags, new.raw);
+            END;
+        """)
+        # Migrate existing DBs with old column names
+        cols = {row[1] for row in conn.execute("PRAGMA table_info(entries)")}
+        if "gotchas" in cols:
+            conn.execute("ALTER TABLE entries RENAME COLUMN gotchas TO warnings")
+
+
+init_db()
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+def _row_to_dict(row: sqlite3.Row) -> dict:
+    d = dict(row)
+    for field in ("files", "decisions", "warnings", "tags"):
+        try:
+            d[field] = json.loads(d[field])
+        except (json.JSONDecodeError, TypeError):
+            d[field] = []
+    return d
+
+
+def _format_entry(e: dict, idx: Optional[int] = None) -> str:
+    prefix = f"[{idx}] " if idx is not None else ""
+    lines = [
+        f"{prefix}#{e['id']} — {e['timestamp'][:16]}",
+        f"  Task      : {e['task']}",
+    ]
+    if e.get("files"):
+        lines.append(f"  Files     : {', '.join(e['files'])}")
+    if e.get("decisions"):
+        for d in e["decisions"]:
+            lines.append(f"  Decision  : {d}")
+    if e.get("warnings"):
+        for w in e["warnings"]:
+            lines.append(f"  Warning   : {w}")
+    if e.get("tags"):
+        lines.append(f"  Tags      : {', '.join(e['tags'])}")
+    if e.get("raw"):
+        lines.append(f"  Notes     : {e['raw']}")
+    return "\n".join(lines)
+
+
+def _now_iso() -> str:
+    return datetime.now(timezone.utc).isoformat(timespec="seconds")
+
+# ---------------------------------------------------------------------------
+# MCP server
+# ---------------------------------------------------------------------------
+
+mcp = FastMCP(
+    "memex",
+    instructions=(
+        "Persistent session memory for Claude Code. "
+        "Call mem_load at the start of every session. "
+        "Call mem_save whenever you finish a task or learn something worth keeping. "
+        "Use mem_search to find specific past work. "
+        "Use mem_list / mem_delete for housekeeping."
+    ),
+)
+
+
+@mcp.tool()
+def mem_save(
+    task: str,
+    files: Optional[list[str]] = None,
+    decisions: Optional[list[str]] = None,
+    warnings: Optional[list[str]] = None,
+    tags: Optional[list[str]] = None,
+    notes: Optional[str] = None,
+) -> str:
+    """
+    Save a memory entry about work just completed.
+
+    Args:
+        task:      One-sentence summary of what was done.
+        files:     List of files touched / created / deleted.
+        decisions: Architectural or design decisions made.
+        warnings:  Anything surprising or easy to get wrong.
+        tags:      Short labels for later filtering (e.g. ["auth", "api"]).
+        notes:     Any freeform extra context.
+
+    Call this:
+      - At the end of a significant task or session.
+      - Whenever you discover something worth warning a future session about.
+      - After making an architectural decision.
+    """
+    entry = {
+        "project": os.getcwd(),
+        "timestamp": _now_iso(),
+        "task": task.strip(),
+        "files": json.dumps(files or []),
+        "decisions": json.dumps(decisions or []),
+        "warnings": json.dumps(warnings or []),
+        "tags": json.dumps(tags or []),
+        "raw": (notes or "").strip(),
+    }
+    with get_conn() as conn:
+        cur = conn.execute(
+            """INSERT INTO entries (project, timestamp, task, files, decisions, warnings, tags, raw)
+               VALUES (:project, :timestamp, :task, :files, :decisions, :warnings, :tags, :raw)""",
+            entry,
+        )
+        new_id = cur.lastrowid
+    return f"✓ Saved memory #{new_id}: {task[:80]}"
+
+
+@mcp.tool()
+def mem_load(
+    hint: Optional[str] = None,
+    files: Optional[list[str]] = None,
+) -> str:
+    """
+    Load relevant memory entries for a new session.
+
+    Returns the N most recent entries plus any entries that match the
+    hint (keyword search) or overlap with the files list.
+
+    Args:
+        hint:  Optional keyword or phrase describing the current task.
+        files: Optional list of files you're about to work on.
+
+    Call this at the START of every new Claude Code session.
+    """
+    with get_conn() as conn:
+        # 1. Recent entries
+        recent_rows = conn.execute(
+            "SELECT * FROM entries ORDER BY id DESC LIMIT ?",
+            (MAX_LOAD_RECENT,),
+        ).fetchall()
+        recent = [_row_to_dict(r) for r in recent_rows]
+        recent_ids = {e["id"] for e in recent}
+
+        matched: list[dict] = []
+
+        # 2. FTS keyword search on hint
+        if hint and hint.strip():
+            safe_hint = re.sub(r'[^a-zA-Z0-9 _\-]', ' ', hint).strip()
+            if safe_hint:
+                fts_rows = conn.execute(
+                    """SELECT e.* FROM entries e
+                       JOIN entries_fts f ON f.rowid = e.id
+                       WHERE entries_fts MATCH ?
+                       ORDER BY rank
+                       LIMIT ?""",
+                    (safe_hint, MAX_LOAD_MATCHED),
+                ).fetchall()
+                for r in fts_rows:
+                    d = _row_to_dict(r)
+                    if d["id"] not in recent_ids:
+                        matched.append(d)
+                        recent_ids.add(d["id"])
+
+        # 3. File-path overlap
+        if files:
+            for fpath in files[:10]:
+                like = f"%{fpath}%"
+                file_rows = conn.execute(
+                    "SELECT * FROM entries WHERE files LIKE ? ORDER BY id DESC LIMIT 3",
+                    (like,),
+                ).fetchall()
+                for r in file_rows:
+                    d = _row_to_dict(r)
+                    if d["id"] not in recent_ids:
+                        matched.append(d)
+                        recent_ids.add(d["id"])
+
+    if not recent and not matched:
+        return "No memories saved for this project yet."
+
+    parts = [f"=== memex: session context (db: {DB_PATH.name}) ===\n"]
+
+    if recent:
+        parts.append(f"--- Recent ({len(recent)}) ---")
+        for i, e in enumerate(recent):
+            parts.append(_format_entry(e, i + 1))
+
+    if matched:
+        parts.append(f"\n--- Matched your hint/files ({len(matched)}) ---")
+        for i, e in enumerate(matched):
+            parts.append(_format_entry(e, i + 1))
+
+    return "\n".join(parts)
+
+
+@mcp.tool()
+def mem_search(query: str, limit: int = 10) -> str:
+    """
+    Full-text search across all memory entries.
+
+    Args:
+        query: Keywords to search for (e.g. "JWT auth middleware").
+        limit: Max number of results (default 10).
+
+    Use this when you want to find past work on a specific topic.
+    """
+    safe_query = re.sub(r'[^a-zA-Z0-9 _\-]', ' ', query).strip()
+    if not safe_query:
+        return "Query is empty after sanitisation."
+
+    with get_conn() as conn:
+        rows = conn.execute(
+            """SELECT e.* FROM entries e
+               JOIN entries_fts f ON f.rowid = e.id
+               WHERE entries_fts MATCH ?
+               ORDER BY rank
+               LIMIT ?""",
+            (safe_query, limit),
+        ).fetchall()
+
+    if not rows:
+        return f"No entries matched '{query}'."
+
+    parts = [f"=== Search results for '{query}' ({len(rows)}) ==="]
+    for i, row in enumerate(rows):
+        parts.append(_format_entry(_row_to_dict(row), i + 1))
+    return "\n".join(parts)
+
+
+@mcp.tool()
+def mem_list(limit: int = 20, tag: Optional[str] = None) -> str:
+    """
+    List recent memory entries, optionally filtered by tag.
+
+    Args:
+        limit: How many entries to return (default 20).
+        tag:   Optional tag to filter by (e.g. "auth").
+
+    Use this to review or clean up stored memories.
+    """
+    with get_conn() as conn:
+        if tag:
+            rows = conn.execute(
+                "SELECT * FROM entries WHERE tags LIKE ? ORDER BY id DESC LIMIT ?",
+                (f'%"{tag}"%', limit),
+            ).fetchall()
+        else:
+            rows = conn.execute(
+                "SELECT * FROM entries ORDER BY id DESC LIMIT ?",
+                (limit,),
+            ).fetchall()
+
+    if not rows:
+        msg = f"No entries" + (f" with tag '{tag}'" if tag else "") + "."
+        return msg
+
+    parts = [f"=== memex: {len(rows)} entries ==="]
+    for i, row in enumerate(rows):
+        parts.append(_format_entry(_row_to_dict(row), i + 1))
+    return "\n".join(parts)
+
+
+@mcp.tool()
+def mem_delete(entry_id: int) -> str:
+    """
+    Delete a memory entry by its id.
+
+    Args:
+        entry_id: The numeric id shown in mem_list or mem_load output.
+
+    Use this to remove outdated or incorrect entries.
+    """
+    with get_conn() as conn:
+        cur = conn.execute("DELETE FROM entries WHERE id = ?", (entry_id,))
+        if cur.rowcount == 0:
+            return f"No entry with id {entry_id}."
+    return f"✓ Deleted entry #{entry_id}."
+
+
+# ---------------------------------------------------------------------------
+# Entrypoint
+# ---------------------------------------------------------------------------
+
+if __name__ == "__main__":
+    mcp.run()

mcp_memex-0.1.0/pyproject.toml

@@ -0,0 +1,22 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "mcp-memex"
+version = "0.1.0"
+description = "Persistent session memory for Claude Code — local SQLite, no LLMs, no network"
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.10"
+dependencies = ["mcp>=1.0"]
+
+[project.urls]
+Repository = "https://github.com/pragneshbagary/memex"
+Issues = "https://github.com/pragneshbagary/memex/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["memex"]
+
+[project.scripts]
+memex = "memex.cli:main"