{"id":50108859,"url":"https://github.com/parallelclaw/memex-mvp","last_synced_at":"2026-05-25T22:01:16.580Z","repository":{"id":356392809,"uuid":"1232293202","full_name":"parallelclaw/memex-mvp","owner":"parallelclaw","description":"Local-first MCP memory server. Indexes Claude Code/Cowork/Telegram chats; any MCP-compatible AI agent (Cursor, Cline, Continue) can search them.","archived":false,"fork":false,"pushed_at":"2026-05-23T10:49:20.000Z","size":872,"stargazers_count":14,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-23T12:30:45.412Z","etag":null,"topics":["ai-agent","ai-memory","claude-code","claude-cowork","cline","cursor","fts5","local-first","mcp","memory","model-context-protocol","sqlite"],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/parallelclaw.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-07T19:35:06.000Z","updated_at":"2026-05-23T10:49:22.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/parallelclaw/memex-mvp","commit_stats":null,"previous_names":["parallelclaw/memex-mvp"],"tags_count":23,"template":false,"template_full_name":null,"purl":"pkg:github/parallelclaw/memex-mvp","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/parallelclaw%2Fmemex-mvp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/parallelclaw%2Fmemex-mvp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/parallelclaw%2Fmemex-mvp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/parallelclaw%2Fmemex-mvp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/parallelclaw","download_url":"https://codeload.github.com/parallelclaw/memex-mvp/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/parallelclaw%2Fmemex-mvp/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33492983,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-25T14:31:05.219Z","status":"ssl_error","status_checked_at":"2026-05-25T14:31:02.878Z","response_time":57,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-agent","ai-memory","claude-code","claude-cowork","cline","cursor","fts5","local-first","mcp","memory","model-context-protocol","sqlite"],"created_at":"2026-05-23T12:03:21.264Z","updated_at":"2026-05-25T22:01:16.520Z","avatar_url":"https://github.com/parallelclaw.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# memex-mvp · your AI's missing memory\n\n\u003e **English** · [Русский](README.ru.md)\n\n[![npm](https://img.shields.io/npm/v/memex-mvp.svg)](https://www.npmjs.com/package/memex-mvp)\n[![downloads](https://img.shields.io/npm/dw/memex-mvp.svg)](https://www.npmjs.com/package/memex-mvp)\n[![license](https://img.shields.io/npm/l/memex-mvp.svg)](LICENSE)\n\n\u003e **A single store for all your AI and Telegram chats.**\n\nA local-first MCP server that indexes **every conversation you have with AI** — Claude Code, Claude Cowork, Cursor, Cline, Continue, Zed, Obsidian notes, and selected Telegram chats — into one searchable SQLite + FTS5 corpus and serves it back to **any MCP-compatible client** through a handful of tools.\n\nNo cloud. No account. No data leaves your machine.\n\n```\n~/.memex/inbox/              ← drop chat exports here (or symlink AI session files)\n     ↓ chokidar watcher\nparser  (Telegram JSON · Claude Code JSONL · Cursor SQLite · Obsidian md)\n     ↓\nSQLite + FTS5  (~/.memex/data/memex.db)\n     ↓\nMCP server  →  Cursor · Cline · Claude Code · Continue · Zed · Codex · …\n```\n\n---\n\n## Install in 60 seconds\n\n**One-line install (recommended):**\n\n```sh\ncurl -fsSL https://memex.parallelclaw.ai/install.sh | bash\n```\n\nThat single command:\n1. Verifies Node ≥ 20.\n2. Runs `npm install -g memex-mvp`, auto-fixing `EACCES` by moving npm's prefix to `~/.npm-global` (no `sudo` needed, ever).\n3. Installs the auto-capture daemon (`memex-sync install`) **with** the v0.8 Brian Chesky auto-context hook into `~/.claude/settings.json` (preserves existing hooks).\n4. Backfills history (`memex-sync scan`) so memex already knows about your past sessions.\n5. If `claude` (Claude Code CLI) is on PATH, runs `claude mcp add memex --scope user -- memex` to wire MCP automatically.\n\nIdempotent — safe to re-run. To inspect the script before piping to bash: `curl -fsSL https://memex.parallelclaw.ai/install.sh | less`.\n\n**Prefer manual install?**\n\n```sh\nnpm install -g memex-mvp\nmemex-sync install      # macOS LaunchAgent for auto-capture\n```\n\nIf `npm install -g` hits `EACCES` (system Node on macOS), either fix your prefix once:\n\n```sh\nmkdir -p ~/.npm-global\nnpm config set prefix ~/.npm-global\necho 'export PATH=~/.npm-global/bin:$PATH' \u003e\u003e ~/.zshrc\nsource ~/.zshrc\n```\n\nOr use one-shot `sudo npm install -g memex-mvp`.\n\n**Want to try without installing globally?**\n\n```sh\nnpx memex-mvp install\n```\n\n### Install via AI skill (Claude Code / OpenClaw)\n\nIf you'd rather have an AI agent walk you through everything, drop the\n[install-memex skill](skills/install-memex/) into `~/.claude/skills/`:\n\n```sh\nmkdir -p ~/.claude/skills\ncurl -fsSL https://raw.githubusercontent.com/parallelclaw/memex-mvp/main/skills/install-memex/SKILL.md \\\n  -o ~/.claude/skills/install-memex/SKILL.md\n```\n\nThen in Claude Code (or any Skills-aware agent) just say:\n\n\u003e install memex\n\n…or `/install-memex`. The agent handles `npm install`, MCP-config wiring,\nauto-capture daemon, and verification — ~2 minutes.\n\n---\n\n## Connect to your MCP client\n\nAfter install, point your client at `memex` (an alias of `server.js` exposed on `PATH`):\n\n### Claude Code\n\n```sh\nclaude mcp add memex --scope user -- memex\n```\n\n### Cursor / Cline / Continue / Zed\n\nAdd to that client's MCP config (e.g. `~/.cursor/mcp.json`):\n\n```json\n{\n  \"mcpServers\": {\n    \"memex\": { \"command\": \"memex\" }\n  }\n}\n```\n\nRestart the client. Try the prompt:\n\n\u003e *\"Use memex_overview to show me what's in my AI memory.\"*\n\nIf you see a snapshot of sources and recent conversations — you're done.\n\nFor a fully-automated install across all detected MCP clients, see [the AI-driven install guide](https://memex.parallelclaw.ai) on the landing page (paste the prompt into any MCP-enabled agent, it'll wire everything up itself).\n\n---\n\n## Terminal CLI (v0.7+) — query memex without MCP\n\nThe same `memex` binary that runs as an MCP server also has a terminal mode for direct queries. Useful when MCP isn't wired up, when you want to pipe results into shell scripts, or when debugging MCP-config issues:\n\n```sh\nmemex search \"Postgres migration\"          # full-text search\nmemex search \"Q2 deck\" --chat \"Memex Bot\"  # scope to one conversation by title\nmemex search \"JWT\" --as-of 2026-05-01      # v0.8.1: time-travel — only msgs before date\nmemex when \"Brian Chesky\"                   # v0.8.1: \"when did we talk about X\" — dates + chats\nmemex recent --limit 5                      # last 5 messages across all sources\nmemex list --source web                     # all saved URLs\nmemex get web-1582ab51a7b7                  # full content of one conversation\nmemex overview                              # snapshot of corpus + v0.8.1: capture streak\nmemex projects                              # distinct project_paths captured\nmemex import ~/projects/memex/result.json  # v0.10.12: ingest any file from any path\nmemex help                                  # full user guide (HELP.md)\nmemex --help                                # command reference\n```\n\n### Ingest from any path (v0.10.12+)\n\n```sh\nmemex import ~/projects/memex/result.json           # auto-detects Telegram JSON\nmemex import ~/Downloads/ChatExport_2026-05-18/     # Telegram HTML export directory\nmemex import ~/path/to/session.jsonl                # Claude Code JSONL\nmemex import ~/Downloads/result.json --force        # skip Telegram privacy gate\nmemex import some-file --format claude-jsonl        # explicit format override\n```\n\nFor Telegram, the privacy gate fires for any chat that isn't on your allow-list — the command exits with a preview (title, message count, date range, senders) so you can review before re-running with `--force`. Same path via MCP: any AI agent can call `memex_import_file({path: \"...\"})` to ingest one file in one tool call (instead of ~10k tokens of bash `mv`-shuffling).\n\nEvery query supports `--json` for machine-readable output: `memex search foo --json | jq '.results[].snippet'`. The DB is opened **read-only** — safe to run while `memex-sync` daemon is writing.\n\nWhen called **without arguments** (`memex`), the binary still runs as an MCP stdio server (the way Claude Code / Cursor / Cline launch it). CLI mode and MCP mode are the same package — no extra install.\n\n---\n\n## Auto-context (v0.8+) — Claude already knows what you were doing\n\nAfter `memex-sync install`, you're prompted to enable **auto-context**. When yes, memex adds a SessionStart hook to `~/.claude/settings.json` so that **every time you open Claude Code in a project**, Claude gets injected with ~500-1500 tokens of relevant context — what you did recently in this project, which conversations touched it, which related topics came up. No prompts. No tool calls. Just memory.\n\n```sh\n# Adding/removing the hook outside the install flow:\nmemex hook install        # add SessionStart hook (idempotent)\nmemex hook uninstall      # remove only the memex entry, preserves other hooks\nmemex hook status         # show current state\n\n# Inspecting what gets injected:\nmemex context             # dry-run the hook output for the current dir\nmemex context --pwd /path # for a different project\nmemex context --no-source telegram  # exclude a source\n```\n\nThe hook respects existing hooks (e.g. `gstack`, custom user hooks) — they're preserved untouched.\n\n**Currently only Claude Code has native SessionStart hooks.** For Cursor / Cline / Continue / Zed, MCP-tool-based fallback is on the v0.9.0 roadmap.\n\n---\n\n## Save URLs into memex (v0.6+)\n\nOnce memex is installed, any MCP-aware agent can also save **web pages, AI chat shares, and pasted text** into your memex memory — searchable from any other AI chat later. In Claude Code, Cursor, Cline, …:\n\n```\nSave https://www.perplexity.ai/share/\u003cid\u003e to memex\nAdd this article to my memex: https://example.com/long-post\n```\n\nThe agent fetches the page via its own WebFetch (auto-falling back to `r.jina.ai` for Cloudflare-protected sites — memex teaches the trick) and calls `memex_store_document`. Memex stores the content verbatim as a `web` source conversation, indistinguishable from AI chats at search time.\n\nPerplexity threads need to be made **Public** in the Share dialog first — memex detects private threads and tells the user how to fix it. Full guide: [HELP.md §8](HELP.md).\n\n**Memex stays 100% local** — the agent fetches, memex only stores. Zero outbound calls from memex itself.\n\n---\n\n## Telegram chats (v0.10+) — agent walks you through it\n\nTelegram-export setup used to be 8 steps. v0.10+ collapses it to 2 (you click in Telegram; you pick which chats to keep). The rest is automatic.\n\n**How it works:**\n1. The daemon watches `~/Downloads/Telegram Desktop/` in the background. **No setup needed** — already on after install.\n2. You export a chat from Telegram Desktop (chat → ⋮ → Export chat history → HTML or JSON).\n3. memex detects the export, **moves it to `~/.memex/pending/`** (NOT into your DB yet).\n4. Your AI agent (or you in terminal) calls `memex_telegram_pending` — sees a numbered list with chat name, msg count, date range.\n5. You pick which to import. Sensitive ones (Bank, Therapist, Tinder) — skip. memex remembers and won't ask again.\n6. Future re-exports of allowed chats auto-merge. Skipped ones stay out.\n\n**The agent leads.** Just say *\"set up Telegram for memex\"* (or **install memex** in a fresh session — the install-memex skill v1.2+ proactively offers it). The agent will:\n- Check if Telegram Desktop is installed (give you the right download link if not)\n- Check the 24h post-login export-block window (tell you when you can export)\n- Show the click-path in Telegram\n- Wait for your export, then present the picker\n\n**Three modes:** `pick` (default — review each export), `auto` (allowed chats auto-import; new ones go to pending), `manual` (watcher off — drop files yourself).\n\nTerminal equivalents: `memex telegram check / pending / import 1 3 5 / skip 2 / mode auto`. Full reference: `memex telegram --help`.\n\n**v0.10.1: 4-channel proactive notification.** You'll find out about pending exports from whichever channel reaches you first:\n\n1. **In the AI agent (active session)** — `memex_search` / `memex_recent` / `memex_overview` tool responses include a `telegram_pending` field with chat names. Agent surfaces it as a natural aside.\n2. **In the terminal** — any `memex` CLI command appends a 💡 tip line when pending \u003e 0. Throttled to once per 6h.\n3. **macOS native notification** (opt-in) — daemon fires a banner when a new export is staged. `memex telegram notifications on` to enable. Default OFF for lock-screen privacy; add `--show-titles` if you want chat names in the banner. **v0.10.4+ clickable:** if `terminal-notifier` is installed (`brew install terminal-notifier`), clicking the banner opens — in priority order — Claude Code CLI in a fresh Terminal (Brian Chesky moment via SessionStart hook), Claude Desktop, or Terminal with `memex telegram pending` queued. Override priority via `memex telegram notifications target \u003cauto|claude-cli|claude-desktop|terminal|none\u003e`.\n4. **Brian Chesky hook (next Claude Code session)** — `memex context` injection includes a \"🆕 N exports awaiting review\" block with chat names. Claude leads with the question before you type anything.\n\n---\n\n## Web dashboard (v0.10.8+) — see your own memory\n\nOpt-in, read-only local UI for browsing the corpus without any AI in the loop. Same SQLite, different surface.\n\n```sh\nmemex web --open      # localhost:8765, opens in browser\nmemex web --port 9000 # custom port\nmemex web --public --token s3cret   # bind on 0.0.0.0 with bearer auth (for remote / tunnel)\nmemex web --help\n```\n\nFive pages:\n\n| Page              | What it shows                                                                            |\n|-------------------|------------------------------------------------------------------------------------------|\n| `/`               | Stats grid · sources breakdown · pending Telegram callout · recent 10 conversations      |\n| `/conversations`  | Live FTS5 search via htmx (200ms debounce) · source-chip filters · hit counts per chat   |\n| `/c/:id`          | **Verbatim** transcript in chat-bubbles · in-chat search with `\u003cmark\u003e` highlight · paged |\n| `/pending`        | Telegram exports awaiting decision · bulk Import / Skip checkboxes · decision history    |\n| `/settings`       | Daemon status · DB path \u0026 size · hooks installed · TG decisions counts (read-only)       |\n\n**Design constraints:**\n- **Opt-in, not always-on.** `memex web` starts the server; Ctrl+C stops it. No daemon.\n- **Read-only by default.** The only writes are TG import / skip on the `/pending` page — same privacy gate as `memex telegram import`.\n- **Localhost-only by default.** Binds `127.0.0.1`. Use `--public --token \u003c…\u003e` for remote access (cron-friendly: same endpoint reserved for the future multi-host sync API).\n- **No build step.** Node raw `http` + tagged template literals + htmx 14KB CDN. Total client bundle: ~30KB.\n- **Brand-aligned.** Same Inter + mint palette as [memex.parallelclaw.ai](https://memex.parallelclaw.ai).\n\n---\n\n## What it captures\n\n| Source                | How it gets in                                                 |\n|-----------------------|----------------------------------------------------------------|\n| Claude Code sessions  | Auto: `memex-sync` watches `~/.claude/projects/`               |\n| Claude Cowork         | Auto: same watcher, including all subagent transcripts         |\n| Cursor IDE chats      | Auto: reads Cursor's local SQLite session store                |\n| Continue / Zed        | Auto: filesystem watchers per platform                         |\n| Obsidian notes        | Auto: per-vault markdown watcher                               |\n| Telegram exports      | **v0.10+: auto.** Daemon watches `~/Downloads/Telegram Desktop/`. Each new ChatExport appears in `memex telegram pending` — review chat-by-chat, import the ones you want. Privacy-first: nothing lands in the DB without your `memex telegram import \u003cindices\u003e`. Allow-list remembers your decisions so future re-exports auto-merge. JSON + HTML both supported. (Legacy path still works: drop into `~/.memex/inbox/`.) |\n| Telegram (live)       | Run [`memex-bot`](bot/README.md) — captures messages you send/forward to your private bot |\n| **Web pages, AI chat shares, pasted text** | From any MCP agent: *\"save https://... to memex\"*. Agent fetches; memex stores verbatim. Cloudflare-protected pages (Perplexity, npm.com, Twitter, Medium, …) handled via the agent's r.jina.ai fallback. See [HELP.md §8](HELP.md) |\n\nAll sources land in the same FTS5 corpus, searchable by one `memex_search` call.\n\n---\n\n## MCP tools\n\n| Tool                          | What it does                                                              |\n|-------------------------------|---------------------------------------------------------------------------|\n| `memex_overview`              | Corpus snapshot — sources, counts, recent chats, daemon health           |\n| `memex_search`                | Full-text search with BM25 × recency boost                               |\n| `memex_recent`                | Most recent messages across all sources                                  |\n| `memex_get_conversation`      | Full transcript by `conversation_id`                                     |\n| `memex_list_conversations`    | Conversations sorted by activity, filterable by source                   |\n| `memex_list_projects`         | Distinct project paths captured (for the `project` filter)               |\n| `memex_archive_conversation`  | Hide a chat from default listings (data preserved)                       |\n| `memex_export_markdown`       | Export one conversation as Markdown (for Obsidian round-trip)            |\n| `memex_store_document`        | Save a web page, AI chat share, or pasted text. Agent fetches; memex stores verbatim. Teaches the Jina r.jina.ai trick for Cloudflare-blocked pages |\n| `memex_list_sources`          | Per-source enabled/disabled + counts                                     |\n| `memex_status`                | Daemon health: PID, last capture, watched files                          |\n| `memex_sources_status`        | Which sources are captured + the exact CLI to opt out                    |\n| `memex_help`                  | Returns the full user guide with concrete use cases                      |\n| `memex_telegram_check`        | v0.10+: Detect Telegram Desktop, login age (24h block), pending count, suggested next step |\n| `memex_telegram_pending`      | v0.10+: List exports staged for review with chat name + msg count + dates |\n| `memex_telegram_import`       | v0.10+: Import selected exports into memex.db (by index or title) — auto-allowlists |\n| `memex_telegram_skip`         | v0.10+: Mark chats as \"never index\" — applies to future re-exports too  |\n| `memex_telegram_mode`         | v0.10+: Get/set capture mode: pick (default) · auto · manual            |\n\nDetailed search parameters (filters, sort, format) live in [HELP.md](HELP.md).\n\n---\n\n## Why memex (vs. cloud memory services)\n\n| Concern                       | memex                              | Cloud memory (Mem0 / Supermemory / …) |\n|-------------------------------|------------------------------------|---------------------------------------|\n| Where your data lives         | Your machine, one SQLite file      | Their servers                         |\n| Cost per ingested turn        | 0 (no LLM call on write)           | $0.005+/1K tokens                     |\n| Cross-AI corpus               | ✅ same DB for all clients         | ⚠️ depends on plugin coverage         |\n| Telegram ingestion            | ✅ first-class                     | ❌ not supported                      |\n| Verbatim storage              | ✅ raw text preserved              | ❌ usually fact-extracted             |\n| Survives if vendor blocks you | ✅ your DB stays on disk           | ❌ data inaccessible                  |\n| Offline / air-gapped          | ✅                                 | ❌                                    |\n| Trade-off                     | Lexical search (FTS5), not semantic | Semantic + reranker, but cloud-bound  |\n\n---\n\n## Privacy\n\n- **Zero network egress** during normal operation. The MCP server only listens on stdio.\n- **No account, no telemetry.** First-time install ping (planned, opt-out) is the only network call ever — and it's anonymous (UUID + version + OS, no content).\n- **The DB is one file** at `~/.memex/data/memex.db`. Back it up, encrypt it (FileVault is enough), `rm` it — your call.\n- **Source opt-out per category**: `memex-sync sources \u003cname\u003e disable` keeps that source out of the corpus permanently.\n\nSee [PRIVACY section in the Russian README](README.ru.md#приватность-и-безопасность--privacy--security) for the full breakdown.\n\n---\n\n## Cross-device\n\nmemex is single-machine by design — but you can sync the DB between your own devices via iCloud Drive symlink, syncthing, or one-time `scp`. The corpus is one SQLite file plus a small inbox directory, so any file-sync tool handles it. See [README.ru.md](README.ru.md#между-устройствами--across-devices) for tested recipes.\n\n---\n\n## Limitations (v0.5)\n\n- **FTS5 only** — no semantic search yet. Russian/English cross-lingual queries don't bridge (\"git rebase\" vs \"перебазирование коммитов\" return different hits). Vector embeddings are on the roadmap.\n- **macOS-first** — daemon installer registers a LaunchAgent. Linux works as a foreground process; Windows untested.\n- **Single user** — the Telegram bot serves exactly one Telegram user_id (you).\n- **No webhook for the bot** — long-polling only, captures buffer ~24h server-side when laptop is offline.\n\n---\n\n## Resources\n\n- 🏠 Landing: [memex.parallelclaw.ai](https://memex.parallelclaw.ai) — the AI-driven install prompt\n- 📖 [HELP.md](HELP.md) — concrete use cases + full tool reference + troubleshooting\n- 🤖 [bot/README.md](bot/README.md) — Telegram capture bot setup\n- 🇷🇺 [README.ru.md](README.ru.md) — full Russian README with deeper privacy / migration sections\n- 🐛 [Issues](https://github.com/parallelclaw/memex-mvp/issues) on GitHub\n\n---\n\n## License\n\nMIT — see [LICENSE](LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fparallelclaw%2Fmemex-mvp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fparallelclaw%2Fmemex-mvp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fparallelclaw%2Fmemex-mvp/lists"}