memdex-mcp 0.1.0__tar.gz

memdex_mcp-0.1.0/LICENSE

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

memdex_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,150 @@
+Metadata-Version: 2.4
+Name: memdex-mcp
+Version: 0.1.0
+Summary: Zero-dependency shared memory for AI coding agents: content-hash file summaries, symbol map, notes and handoffs over MCP.
+License: MIT
+Project-URL: Homepage, https://github.com/ChoYugyeong/memdex
+Project-URL: Issues, https://github.com/ChoYugyeong/memdex/issues
+Keywords: mcp,ai,agent,memory,claude,codex,context,sqlite
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Software Development
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# memdex
+
+**Shared, token-saving memory for AI coding agents.** Zero dependencies, one SQLite file, any MCP client.
+
+[한국어 README](README.ko.md)
+
+Every new agent session starts from nothing: it re-reads the same files, re-runs the same searches
+and re-discovers the same pitfalls. When several agents (Claude Code, Codex, Cursor, DeepSeek, …)
+work on one machine, they also can't see what the others learned or are doing right now.
+
+memdex fixes that with a small MCP server:
+
+| Feature | What it does | Borrowed idea |
+|---|---|---|
+| **Content-hash summary cache** | An agent reads a 3,000-token file once and saves a 100-token summary. The summary is keyed to the file's sha256, so it stays valid until the content changes, then is flagged stale automatically. Identical content in other worktrees or branches shares it. | content-addressed storage |
+| **Incremental index** | Only files whose size or mtime moved are re-read. Re-indexing an 800-file repo takes ~0.2 s. | [Everything](https://www.voidtools.com/)'s USN-journal approach |
+| **Outline + symbol map** | Free outlines (docstring + classes/functions with line numbers) for Python, JS/TS, Vue/Svelte, Go (receiver methods as `Type.Method`), Rust, Java, Kotlin, Scala, C#, Swift, Dart, C/C++, Ruby, PHP, Lua, GDScript, shell, PowerShell, Markdown, Elixir, Clojure, Zig, Julia, R, Haskell, Groovy, Protobuf, GraphQL, SQL. `where_is` replaces repeated grepping. | Serena / repo maps, without tree-sitter |
+| **Notes that know when they rot** | Decisions, pitfalls, todos and handoffs, linked to the files they're about. When those files change, the note is marked "⚠ changed since". Notes are append-only (`supersedes`), safe for concurrent agents. | Basic Memory, mem0 |
+| **Agent coordination** | `post`/`inbox` messaging and `claim`s ("I'm editing src/store, 2h") with conflict warnings. All worktrees of a repo share one project memory. | — |
+| **Hybrid search** | SQLite FTS5 trigram (works for Korean/Japanese/Chinese, with a fallback for 2-character terms) + optional local embeddings via Ollama, merged by reciprocal rank fusion. | claude-context |
+| **Bounded reads** | `read_snippet` returns ~256 tokens around a match or a line instead of the whole file. Pair it with `where_is`. | [Kensaku](https://github.com/yjid/kensaku)'s `read_snippet` |
+| **Whole-machine content search** | With Kensaku installed, `search` also returns full-text, OCR and semantic hits from PDFs, Office docs and screenshots. | Kensaku |
+
+Measured on a real 800-file TypeScript repo: a 144 KB source file → 1.6 KB `file_summary` response (outline only,
+before any agent summary was saved).
+
+## Install
+
+```bash
+pipx install memdex-mcp        # or: pip install memdex-mcp
+```
+
+The PyPI name is `memdex-mcp` (plain `memdex` was taken); the command, package and MCP server are all `memdex`.
+From source: `pipx install git+https://github.com/ChoYugyeong/memdex` or `pip install -e .` in a checkout.
+
+Python 3.9+. No other dependencies — the MCP stdio protocol is implemented directly, so it won't break across MCP SDK versions.
+
+## Connect your agents
+
+`memdex config --agent <name>` prints these snippets.
+
+**Claude Code**
+
+```bash
+claude mcp add memdex --scope user -e MEMDEX_AGENT=claude -- memdex serve
+```
+
+Optional: inject the brief at every session start (`~/.claude/settings.json`):
+
+```json
+{ "hooks": { "SessionStart": [ { "hooks": [ { "type": "command", "command": "memdex hook session-start --agent claude" } ] } ] } }
+```
+
+**Any other MCP client** (Claude Desktop, Cursor, Codex, Windsurf, DeepSeek harness, …)
+
+```json
+{ "mcpServers": { "memdex": { "command": "memdex", "args": ["serve"], "env": { "MEMDEX_AGENT": "codex" } } } }
+```
+
+Give each agent its own `MEMDEX_AGENT` name. Its full id becomes `name@checkout`, e.g. `claude@myrepo-wt`.
+
+## Tools
+
+| Tool | Use |
+|---|---|
+| `project_brief` | Start of session: last handoff, pitfalls, decisions, todos, unread messages, other agents' claims. Refreshes the index. |
+| `file_summary` | Before reading a file: cached summary (if the content is unchanged) + outline. |
+| `file_summary_save` | After reading a file: store a 2–6 line summary for everyone. |
+| `where_is` | Symbol definition lookup. |
+| `read_snippet` | A bounded slice of a file around `query` or `line` (default ~256 tokens). |
+| `search` | Notes, handoffs and file summaries; keyword + semantic. Plus Kensaku content hits when installed (`everywhere: true` for the whole machine). |
+| `remember` / `note` | Save / read / archive notes (`note`, `decision`, `pitfall`, `todo`, `handoff`). |
+| `handoff` | End of session: done / next / decisions / pitfalls. Releases your claims. |
+| `post` / `inbox` | Messages between agents (broadcast or `to: "deepseek"`). |
+| `claim` | Announce what you're editing; warns about overlaps. |
+
+The server sends usage instructions in its MCP `initialize` response, so agents know the workflow without extra prompting.
+The 12 tool schemas cost about 1,000 tokens per request.
+
+## CLI
+
+Everything the MCP tools do is also a command, for shell-capable agents and for humans:
+
+```bash
+memdex brief --agent codex              # start of session: handoff, notes, inbox, claims
+memdex file src/store.py                # cached summary + outline
+memdex file src/store.py --summary "…"  # save a summary
+memdex snippet src/store.py --query "def index"
+memdex search "locked"
+memdex remember pitfall "WAL mode needed" --body "…" --files src/store.py
+memdex claim src/store.py --intent "refactor"
+memdex post "store.py is mine for an hour" --to claude
+memdex inbox
+memdex handoff "Done X" --next "Y" --pitfalls "Z"
+memdex index · memdex export --out notes/ · memdex stats
+```
+
+## Where data lives
+
+Everything is in `~/.memdex/memdex.db` (override with `MEMDEX_HOME`). Nothing is written into your
+repositories, so memory never ends up in a commit. Files that look like secrets (`.env*`, `*.pem`, `*.key`,
+`*secret*`, `*credential*`, …), binaries, lockfiles, files over 512 KB and anything git ignores are never read.
+
+A project is identified by its git common directory, so all worktrees of a repository share notes,
+messages and claims, while each worktree keeps its own file index.
+
+## Kensaku integration (optional)
+
+[Kensaku](https://github.com/yjid/kensaku) is a local, read-only desktop search engine that indexes
+file names, the full text of PDF/DOCX/EPUB, OCR'd screenshots and a semantic tier. memdex covers a
+project's source; Kensaku covers the rest of the machine. If `kensaku-cli` is on PATH (or
+`MEMDEX_KENSAKU` points to it), `search` appends Kensaku's content hits, scoped to the project unless
+`everywhere` is set. `MEMDEX_KENSAKU=off` disables it.
+
+## Semantic search (optional)
+
+```bash
+ollama pull bge-m3
+export MEMDEX_EMBED=ollama:bge-m3   # MEMDEX_OLLAMA_URL defaults to http://localhost:11434
+```
+
+Notes and summaries get embedded when saved; search merges keyword and vector rankings.
+If Ollama is unreachable, memdex silently falls back to keyword search.
+
+## Development
+
+```bash
+python -m unittest discover tests
+```
+
+## License
+
+MIT

memdex_mcp-0.1.0/README.md

@@ -0,0 +1,133 @@
+# memdex
+
+**Shared, token-saving memory for AI coding agents.** Zero dependencies, one SQLite file, any MCP client.
+
+[한국어 README](README.ko.md)
+
+Every new agent session starts from nothing: it re-reads the same files, re-runs the same searches
+and re-discovers the same pitfalls. When several agents (Claude Code, Codex, Cursor, DeepSeek, …)
+work on one machine, they also can't see what the others learned or are doing right now.
+
+memdex fixes that with a small MCP server:
+
+| Feature | What it does | Borrowed idea |
+|---|---|---|
+| **Content-hash summary cache** | An agent reads a 3,000-token file once and saves a 100-token summary. The summary is keyed to the file's sha256, so it stays valid until the content changes, then is flagged stale automatically. Identical content in other worktrees or branches shares it. | content-addressed storage |
+| **Incremental index** | Only files whose size or mtime moved are re-read. Re-indexing an 800-file repo takes ~0.2 s. | [Everything](https://www.voidtools.com/)'s USN-journal approach |
+| **Outline + symbol map** | Free outlines (docstring + classes/functions with line numbers) for Python, JS/TS, Vue/Svelte, Go (receiver methods as `Type.Method`), Rust, Java, Kotlin, Scala, C#, Swift, Dart, C/C++, Ruby, PHP, Lua, GDScript, shell, PowerShell, Markdown, Elixir, Clojure, Zig, Julia, R, Haskell, Groovy, Protobuf, GraphQL, SQL. `where_is` replaces repeated grepping. | Serena / repo maps, without tree-sitter |
+| **Notes that know when they rot** | Decisions, pitfalls, todos and handoffs, linked to the files they're about. When those files change, the note is marked "⚠ changed since". Notes are append-only (`supersedes`), safe for concurrent agents. | Basic Memory, mem0 |
+| **Agent coordination** | `post`/`inbox` messaging and `claim`s ("I'm editing src/store, 2h") with conflict warnings. All worktrees of a repo share one project memory. | — |
+| **Hybrid search** | SQLite FTS5 trigram (works for Korean/Japanese/Chinese, with a fallback for 2-character terms) + optional local embeddings via Ollama, merged by reciprocal rank fusion. | claude-context |
+| **Bounded reads** | `read_snippet` returns ~256 tokens around a match or a line instead of the whole file. Pair it with `where_is`. | [Kensaku](https://github.com/yjid/kensaku)'s `read_snippet` |
+| **Whole-machine content search** | With Kensaku installed, `search` also returns full-text, OCR and semantic hits from PDFs, Office docs and screenshots. | Kensaku |
+
+Measured on a real 800-file TypeScript repo: a 144 KB source file → 1.6 KB `file_summary` response (outline only,
+before any agent summary was saved).
+
+## Install
+
+```bash
+pipx install memdex-mcp        # or: pip install memdex-mcp
+```
+
+The PyPI name is `memdex-mcp` (plain `memdex` was taken); the command, package and MCP server are all `memdex`.
+From source: `pipx install git+https://github.com/ChoYugyeong/memdex` or `pip install -e .` in a checkout.
+
+Python 3.9+. No other dependencies — the MCP stdio protocol is implemented directly, so it won't break across MCP SDK versions.
+
+## Connect your agents
+
+`memdex config --agent <name>` prints these snippets.
+
+**Claude Code**
+
+```bash
+claude mcp add memdex --scope user -e MEMDEX_AGENT=claude -- memdex serve
+```
+
+Optional: inject the brief at every session start (`~/.claude/settings.json`):
+
+```json
+{ "hooks": { "SessionStart": [ { "hooks": [ { "type": "command", "command": "memdex hook session-start --agent claude" } ] } ] } }
+```
+
+**Any other MCP client** (Claude Desktop, Cursor, Codex, Windsurf, DeepSeek harness, …)
+
+```json
+{ "mcpServers": { "memdex": { "command": "memdex", "args": ["serve"], "env": { "MEMDEX_AGENT": "codex" } } } }
+```
+
+Give each agent its own `MEMDEX_AGENT` name. Its full id becomes `name@checkout`, e.g. `claude@myrepo-wt`.
+
+## Tools
+
+| Tool | Use |
+|---|---|
+| `project_brief` | Start of session: last handoff, pitfalls, decisions, todos, unread messages, other agents' claims. Refreshes the index. |
+| `file_summary` | Before reading a file: cached summary (if the content is unchanged) + outline. |
+| `file_summary_save` | After reading a file: store a 2–6 line summary for everyone. |
+| `where_is` | Symbol definition lookup. |
+| `read_snippet` | A bounded slice of a file around `query` or `line` (default ~256 tokens). |
+| `search` | Notes, handoffs and file summaries; keyword + semantic. Plus Kensaku content hits when installed (`everywhere: true` for the whole machine). |
+| `remember` / `note` | Save / read / archive notes (`note`, `decision`, `pitfall`, `todo`, `handoff`). |
+| `handoff` | End of session: done / next / decisions / pitfalls. Releases your claims. |
+| `post` / `inbox` | Messages between agents (broadcast or `to: "deepseek"`). |
+| `claim` | Announce what you're editing; warns about overlaps. |
+
+The server sends usage instructions in its MCP `initialize` response, so agents know the workflow without extra prompting.
+The 12 tool schemas cost about 1,000 tokens per request.
+
+## CLI
+
+Everything the MCP tools do is also a command, for shell-capable agents and for humans:
+
+```bash
+memdex brief --agent codex              # start of session: handoff, notes, inbox, claims
+memdex file src/store.py                # cached summary + outline
+memdex file src/store.py --summary "…"  # save a summary
+memdex snippet src/store.py --query "def index"
+memdex search "locked"
+memdex remember pitfall "WAL mode needed" --body "…" --files src/store.py
+memdex claim src/store.py --intent "refactor"
+memdex post "store.py is mine for an hour" --to claude
+memdex inbox
+memdex handoff "Done X" --next "Y" --pitfalls "Z"
+memdex index · memdex export --out notes/ · memdex stats
+```
+
+## Where data lives
+
+Everything is in `~/.memdex/memdex.db` (override with `MEMDEX_HOME`). Nothing is written into your
+repositories, so memory never ends up in a commit. Files that look like secrets (`.env*`, `*.pem`, `*.key`,
+`*secret*`, `*credential*`, …), binaries, lockfiles, files over 512 KB and anything git ignores are never read.
+
+A project is identified by its git common directory, so all worktrees of a repository share notes,
+messages and claims, while each worktree keeps its own file index.
+
+## Kensaku integration (optional)
+
+[Kensaku](https://github.com/yjid/kensaku) is a local, read-only desktop search engine that indexes
+file names, the full text of PDF/DOCX/EPUB, OCR'd screenshots and a semantic tier. memdex covers a
+project's source; Kensaku covers the rest of the machine. If `kensaku-cli` is on PATH (or
+`MEMDEX_KENSAKU` points to it), `search` appends Kensaku's content hits, scoped to the project unless
+`everywhere` is set. `MEMDEX_KENSAKU=off` disables it.
+
+## Semantic search (optional)
+
+```bash
+ollama pull bge-m3
+export MEMDEX_EMBED=ollama:bge-m3   # MEMDEX_OLLAMA_URL defaults to http://localhost:11434
+```
+
+Notes and summaries get embedded when saved; search merges keyword and vector rankings.
+If Ollama is unreachable, memdex silently falls back to keyword search.
+
+## Development
+
+```bash
+python -m unittest discover tests
+```
+
+## License
+
+MIT

memdex_mcp-0.1.0/memdex/__init__.py

@@ -0,0 +1,3 @@
+"""memdex: shared, token-saving memory for AI coding agents."""
+
+__version__ = "0.1.0"

memdex_mcp-0.1.0/memdex/__main__.py

@@ -0,0 +1,3 @@
+from .cli import main
+
+raise SystemExit(main())

memdex_mcp-0.1.0/memdex/cli.py

@@ -0,0 +1,209 @@
+"""Command line: run the MCP server, index, search, hooks, export."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import re
+import sys
+import time
+from typing import Optional
+
+from . import __version__
+from . import project as projects
+from .store import Store, default_path
+from .tools import Session, render_brief
+
+
+def _session(args) -> Session:
+    s = Session(Store(args.db), agent_name=getattr(args, "agent", "") or "")
+    if getattr(args, "path", None):
+        s.cwd = args.path
+    return s
+
+
+def cmd_serve(args) -> int:
+    from .mcp import serve
+    serve(args.db, args.path)
+    return 0
+
+
+def cmd_index(args) -> int:
+    s = _session(args)
+    t = time.time()
+    st = s.store.index(s.project)
+    print(f"{s.project.name}: {st['files']} files, {st['changed']} changed, {st['removed']} removed "
+          f"({time.time() - t:.2f}s) → {s.store.path}")
+    return 0
+
+
+def cmd_brief(args) -> int:
+    s = _session(args)
+    print(render_brief(s.store, s.project, s.agent))
+    return 0
+
+
+def cmd_search(args) -> int:
+    print(_session(args).search(" ".join(args.query), limit=args.limit))
+    return 0
+
+
+def cmd_file(args) -> int:
+    s = _session(args)
+    print(s.file_summary_save(args.file, args.summary) if args.summary else s.file_summary(args.file))
+    return 0
+
+
+def cmd_snippet(args) -> int:
+    print(_session(args).read_snippet(args.file, args.query or "", args.line or 0, args.max_tokens))
+    return 0
+
+
+def cmd_remember(args) -> int:
+    print(_session(args).remember(args.kind, args.title, args.body or "", args.files, args.supersedes))
+    return 0
+
+
+def cmd_handoff(args) -> int:
+    print(_session(args).handoff(args.done, args.next or "", args.decisions or "", args.pitfalls or "", args.files))
+    return 0
+
+
+def cmd_post(args) -> int:
+    print(_session(args).post(args.message, args.to or ""))
+    return 0
+
+
+def cmd_inbox(args) -> int:
+    print(_session(args).inbox(args.peek))
+    return 0
+
+
+def cmd_claim(args) -> int:
+    print(_session(args).claim(args.paths or None, args.intent or "", args.minutes, args.release))
+    return 0
+
+
+def cmd_hook(args) -> int:
+    """Hook entry points. session-start prints the brief, which Claude Code adds to context."""
+    payload = {}
+    if not sys.stdin.isatty():
+        try:
+            payload = json.loads(sys.stdin.read() or "{}")
+        except (json.JSONDecodeError, OSError):
+            payload = {}
+    args.path = args.path or payload.get("cwd") or os.getcwd()
+    s = _session(args)
+    if args.event == "session-start":
+        print(render_brief(s.store, s.project, s.agent))
+        print("(memdex MCP tools: file_summary before reading files, remember/handoff to save.)")
+    return 0
+
+
+def cmd_export(args) -> int:
+    """Write the project's notes as Markdown files (one per note) for reading or backup."""
+    s = _session(args)
+    out = args.out or os.path.join(os.getcwd(), "memdex-export")
+    os.makedirs(out, exist_ok=True)
+    rows = s.store.db.execute(
+        "SELECT * FROM notes WHERE project=? AND archived=0 ORDER BY id", (s.project.key,)).fetchall()
+    for n in rows:
+        slug = re.sub(r"[^\w가-힣ぁ-んァ-ン一-龥-]+", "-", n["title"]).strip("-")[:50] or "note"
+        with open(os.path.join(out, f"{n['id']:04d}-{n['kind']}-{slug}.md"), "w", encoding="utf-8") as f:
+            f.write(f"---\nid: {n['id']}\nkind: {n['kind']}\nauthor: {n['author']}\n"
+                    f"created: {time.strftime('%Y-%m-%d %H:%M', time.localtime(n['created_at']))}\n"
+                    f"superseded_by: {n['superseded_by'] or ''}\nrefs: {n['refs']}\n---\n\n"
+                    f"# {n['title']}\n\n{n['body']}\n")
+    print(f"exported {len(rows)} notes → {out}")
+    return 0
+
+
+def cmd_config(args) -> int:
+    agent = args.agent or "claude"
+    exe = "memdex"
+    print(f"""# Claude Code (user scope, all projects)
+claude mcp add memdex --scope user -e MEMDEX_AGENT={agent} -- {exe} serve
+
+# Any MCP client (Claude Desktop, Cursor, Codex, DeepSeek harness, ...): mcpServers entry
+{json.dumps({"mcpServers": {"memdex": {"command": exe, "args": ["serve"], "env": {"MEMDEX_AGENT": agent}}}}, indent=2)}
+
+# Claude Code SessionStart hook (~/.claude/settings.json): injects the brief automatically
+{json.dumps({"hooks": {"SessionStart": [{"hooks": [{"type": "command", "command": f"{exe} hook session-start --agent {agent}"}]}]}}, indent=2)}
+""")
+    return 0
+
+
+def cmd_stats(args) -> int:
+    st = Store(args.db)
+    q = lambda sql: st.db.execute(sql).fetchone()[0]
+    size = os.path.getsize(st.path) if os.path.exists(st.path) else 0
+    print(f"db: {st.path} ({size / 1024:.0f} KB)\nfiles: {q('SELECT count(*) FROM files')}  "
+          f"summaries: {q('SELECT count(*) FROM summaries')}  notes: {q('SELECT count(*) FROM notes')}  "
+          f"messages: {q('SELECT count(*) FROM messages')}  trigram: {st.trigram}")
+    return 0
+
+
+def main(argv: Optional[list[str]] = None) -> int:
+    for stream in (sys.stdout, sys.stderr):
+        try:
+            stream.reconfigure(encoding="utf-8")
+        except (AttributeError, ValueError):
+            pass
+    p = argparse.ArgumentParser(prog="memdex", description="Shared, token-saving memory for AI coding agents.")
+    p.add_argument("--version", action="version", version=f"memdex {__version__}")
+    p.add_argument("--db", default=None, help=f"database path (default {default_path()}, or $MEMDEX_HOME)")
+    sub = p.add_subparsers(dest="cmd", required=True)
+
+    def add(name, fn, help_):
+        sp = sub.add_parser(name, help=help_)
+        sp.set_defaults(fn=fn)
+        sp.add_argument("--path", default=None, help="project path (default: current directory)")
+        sp.add_argument("--agent", default="", help="agent name, e.g. claude, deepseek, codex")
+        return sp
+
+    add("serve", cmd_serve, "run the MCP server on stdio")
+    add("index", cmd_index, "update the file index (changed files only)")
+    add("brief", cmd_brief, "print the project brief")
+    sp = add("search", cmd_search, "search notes and file summaries")
+    sp.add_argument("query", nargs="+")
+    sp.add_argument("--limit", type=int, default=8)
+    sp = add("file", cmd_file, "show a file's cached summary and outline, or save a summary")
+    sp.add_argument("file")
+    sp.add_argument("--summary", default=None, help="save this 2-6 line summary for the file's current content")
+    sp = add("snippet", cmd_snippet, "read a bounded part of a file around a query or line")
+    sp.add_argument("file")
+    sp.add_argument("--query", default=None)
+    sp.add_argument("--line", type=int, default=0)
+    sp.add_argument("--max-tokens", type=int, default=256)
+    sp = add("remember", cmd_remember, "save a note, decision, pitfall or todo")
+    sp.add_argument("kind", choices=["note", "decision", "pitfall", "todo"])
+    sp.add_argument("title")
+    sp.add_argument("--body", default="")
+    sp.add_argument("--files", nargs="*", default=None, help="files this note is about (flagged when they change)")
+    sp.add_argument("--supersedes", type=int, default=None, help="id of the note this one replaces")
+    sp = add("handoff", cmd_handoff, "end-of-session handoff for the next session or agent")
+    sp.add_argument("done")
+    sp.add_argument("--next", default="")
+    sp.add_argument("--decisions", default="")
+    sp.add_argument("--pitfalls", default="")
+    sp.add_argument("--files", nargs="*", default=None)
+    sp = add("post", cmd_post, "message other agents on this project")
+    sp.add_argument("message")
+    sp.add_argument("--to", default="", help="agent name such as claude or deepseek; default everyone")
+    sp = add("inbox", cmd_inbox, "unread messages from other agents")
+    sp.add_argument("--peek", action="store_true", help="do not mark as read")
+    sp = add("claim", cmd_claim, "announce files you are editing; no paths lists active claims")
+    sp.add_argument("paths", nargs="*")
+    sp.add_argument("--intent", default="")
+    sp.add_argument("--minutes", type=int, default=120)
+    sp.add_argument("--release", action="store_true")
+    sp = add("hook", cmd_hook, "hook entry point for agent harnesses")
+    sp.add_argument("event", choices=["session-start"])
+    sp = add("export", cmd_export, "export notes as Markdown")
+    sp.add_argument("--out", default=None)
+    add("config", cmd_config, "print setup snippets for MCP clients and hooks")
+    add("stats", cmd_stats, "database statistics")
+
+    args = p.parse_args(argv)
+    return args.fn(args)

memdex_mcp-0.1.0/memdex/embed.py

@@ -0,0 +1,57 @@
+"""Optional semantic search through a local embedding model.
+
+Off by default. Set MEMDEX_EMBED=ollama:<model> (for example ollama:bge-m3,
+which handles Korean, Japanese and English) to turn it on. Vectors are
+normalised float32 blobs searched by brute force, which stays fast for the
+few thousand notes and summaries a project accumulates, with no extra library.
+"""
+
+from __future__ import annotations
+
+import json
+import math
+import os
+import urllib.request
+from array import array
+from typing import Optional
+
+_disabled_after_error = False
+
+
+def config() -> Optional[tuple[str, str]]:
+    spec = os.environ.get("MEMDEX_EMBED", "").strip()
+    if not spec or _disabled_after_error:
+        return None
+    provider, _, model = spec.partition(":")
+    if provider != "ollama" or not model:
+        return None
+    return provider, model
+
+
+def embed(text: str) -> Optional[bytes]:
+    global _disabled_after_error
+    cfg = config()
+    if not cfg or not text.strip():
+        return None
+    url = os.environ.get("MEMDEX_OLLAMA_URL", "http://localhost:11434").rstrip("/") + "/api/embed"
+    req = urllib.request.Request(
+        url, data=json.dumps({"model": cfg[1], "input": text[:8000]}).encode(),
+        headers={"Content-Type": "application/json"},
+    )
+    try:
+        with urllib.request.urlopen(req, timeout=30) as r:
+            vec = json.loads(r.read())["embeddings"][0]
+    except Exception:
+        _disabled_after_error = True  # don't stall every call on a dead server
+        return None
+    n = math.sqrt(sum(x * x for x in vec)) or 1.0
+    return array("f", (x / n for x in vec)).tobytes()
+
+
+def similarity(a: bytes, b: bytes) -> float:
+    va, vb = array("f"), array("f")
+    va.frombytes(a)
+    vb.frombytes(b)
+    if len(va) != len(vb):
+        return -1.0
+    return sum(x * y for x, y in zip(va, vb))

memdex_mcp-0.1.0/memdex/kensaku.py

@@ -0,0 +1,60 @@
+"""Optional bridge to Kensaku (https://github.com/yjid/kensaku).
+
+Kensaku is a local desktop search engine: file names, full text of PDF/DOCX/
+EPUB, OCR'd screenshots and a static-vector semantic tier, read-only, nothing
+leaves the machine. memdex indexes a project's source; Kensaku indexes the whole
+computer. When `kensaku-cli` is on PATH (or MEMDEX_KENSAKU names it), memdex
+search also returns Kensaku's content hits, so an agent can find "the PDF about
+the auth flow" or "the screenshot with the CUDA error" without a second tool.
+
+Set MEMDEX_KENSAKU=off to disable.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import shutil
+import subprocess
+from typing import Any, Optional
+
+
+def command() -> Optional[str]:
+    spec = os.environ.get("MEMDEX_KENSAKU", "").strip()
+    if spec.lower() in ("off", "0", "false"):
+        return None
+    return spec or shutil.which("kensaku-cli")
+
+
+def _run(args: list[str], timeout: float) -> Optional[str]:
+    try:
+        r = subprocess.run(args, capture_output=True, timeout=timeout)
+    except (OSError, subprocess.SubprocessError):
+        return None
+    if r.returncode != 0:  # 3 = no index yet; 2 = usage
+        return None
+    return r.stdout.decode("utf-8", "replace")
+
+
+def search(query: str, root: Optional[str] = None, limit: int = 5, timeout: float = 15) -> list[dict[str, Any]]:
+    """Ranked Kensaku hits as {path, snippet, match}. Empty when unavailable."""
+    cmd = command()
+    if not cmd or not query.strip():
+        return []
+    args = [cmd, "search", query, "--json", "--limit", str(max(1, min(limit, 50)))]
+    if root:
+        args += ["--path", root]
+    out = _run(args, timeout)
+    if not out:
+        return []
+    try:
+        data = json.loads(out)
+    except json.JSONDecodeError:
+        return []
+    hits = []
+    for it in (data.get("results") or [])[:limit]:
+        if not isinstance(it, dict) or not it.get("path"):
+            continue
+        snippet = " ".join(str(it.get("snippet") or "").split())[:240]
+        hits.append({"path": str(it["path"]), "snippet": snippet, "match": str(it.get("match_type") or "")})
+    return hits