Memex MVP

What is Memex MVP about?

Memex MVP aggregates and indexes every conversation you have with AI tools (Claude Code, Claude Cowork, Cursor, Cline, Continue, Zed, etc.), selected Telegram chats, and local notes (Obsidian, markdown files). All content is stored locally in a SQLite database with an FTS5 full‑text index and served via the Model Context Protocol (MCP) so any compatible agent can query the corpus on‑demand.

How to use Memex MVP?

1. Install – the quickest way is a one‑liner: curl -fsSL https://memex.parallelclaw.ai/install.sh | bash. Alternatively, run npx -y memex-mvp or npm install -g memex-mvp.
2. Start the server – after install the memex binary is on your PATH. Running memex without arguments starts an MCP stdio server that your agents connect to (e.g., claude mcp add memex --scope user -- memex).
3. Add sources – drop exported files into ~/.memex/inbox/ or let the auto‑capture daemon (memex-sync install) watch the relevant folders. The daemon watches Claude project directories, Cursor SQLite, Obsidian vaults, and Telegram export downloads.
4. Query – use the built‑in CLI (memex search "keyword") or call MCP tools such as memex_search, memex_recent, memex_get_conversation from any AI client.
5. Optional UI – launch a read‑only web dashboard with memex web --open to browse conversations, pending Telegram imports, and statistics.

Key Features

• Local‑first: No cloud storage, all data stays in ~/.memex/data/memex.db.
• Multi‑source ingestion: Claude Code/​Cowork JSONL, Cursor SQLite, Telegram JSON/HTML, Obsidian markdown, arbitrary web pages saved via MCP commands.
• Full‑text search: SQLite FTS5 with BM25 ranking, date‑range filters, project and source filters.
• Auto‑context hook: For Claude Code, a SessionStart hook injects recent relevant snippets (500‑1500 tokens) automatically.
• Telegram workflow: Watcher auto‑detects exported chats, presents a pending‑import UI, and respects an allow‑list to keep sensitive chats private.
• Terminal CLI: Same binary works as MCP server and as a stand‑alone query tool (memex search, memex recent, memex import …).
• Web dashboard: Light‑weight read‑only UI for browsing, searching, and managing pending Telegram imports.
• Experimental sync: Optional peer‑to‑peer database sync for multi‑device setups (experimental, toggled via MEMEX_SYNC_EXPERIMENTAL).
• Privacy‑first: Zero network egress during normal operation, no telemetry, opt‑in only for a one‑time anonymous version ping.

Use Cases

• Developer memory: Recall past code discussions, design decisions, and bug‑fix conversations across multiple AI assistants.
• Project continuity: When switching IDEs or agents, the same indexed corpus provides context without re‑importing data.
• Research tracking: Store and search through research notes, citations, and AI‑generated summaries.
• Customer support: Index internal chat logs and support tickets for quick reference by AI assistants.
• Personal knowledge base: Combine Telegram chats, web article saves, and personal notes into a searchable personal archive.

FAQ

Q: Do I need an internet connection? A: No. All ingestion, indexing, and querying happen locally. The only optional network call is the one‑time anonymous version ping.

Q: Can I use Memex MVP with other MCP‑compatible agents? A: Yes. Add the server to the agent’s mcpServers config (e.g., { "memex": { "command": "memex" } }). The built‑in tools are callable from any client.

Q: How does the Telegram privacy gate work? A: When a Telegram export is detected, Memex lists the chat’s title, message count, and date range. You must explicitly import (memex telegram import …) or skip it; skipped chats are remembered and never indexed.

Q: What if I want to back up or move the database? A: The DB is a single file at ~/.memex/data/memex.db. You can copy, encrypt, or sync it with any file‑sync tool (e.g., Syncthing, iCloud) as long as only one process writes at a time.

Q: Is there a way to disable a specific source? A: Yes. Use the daemon command memex-sync sources <name> disable to permanently stop indexing that source.

Q: Can I run the server on Windows? A: The package is primarily macOS‑first; Windows is not officially supported yet, though the CLI can be run under WSL.

Q: How do I enable the experimental multi‑device sync? A: Export MEMEX_SYNC_EXPERIMENTAL=1 and follow the steps in SYNC.md to install the sync server on a hub and pair other machines with memex-sync sync-pair.

memex-mvp · your AI's missing memory

English · Русский

A single store for all your AI and Telegram chats.

A 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.

No cloud. No account. No data leaves your machine.

~/.memex/inbox/              ← drop chat exports here (or symlink AI session files)
     ↓ chokidar watcher
parser  (Telegram JSON · Claude Code JSONL · Cursor SQLite · Obsidian md)
     ↓
SQLite + FTS5  (~/.memex/data/memex.db)
     ↓
MCP server  →  Cursor · Cline · Claude Code · Continue · Zed · Codex · …

---

Install in 60 seconds

One-line install (recommended):

curl -fsSL https://memex.parallelclaw.ai/install.sh | bash

That single command:

1. Verifies Node ≥ 20.
2. Runs npm install -g memex-mvp, auto-fixing EACCES by moving npm's prefix to ~/.npm-global (no sudo needed, ever).
3. Installs the auto-capture daemon (memex-sync install) with the v0.8 Brian Chesky auto-context hook into ~/.claude/settings.json (preserves existing hooks).
4. Backfills history (memex-sync scan) so memex already knows about your past sessions.
5. If claude (Claude Code CLI) is on PATH, runs claude mcp add memex --scope user -- memex to wire MCP automatically.

Idempotent — safe to re-run. To inspect the script before piping to bash: curl -fsSL https://memex.parallelclaw.ai/install.sh | less.

Prefer manual install?

npm install -g memex-mvp
memex-sync install      # macOS LaunchAgent for auto-capture

If npm install -g hits EACCES (system Node on macOS), either fix your prefix once:

mkdir -p ~/.npm-global
npm config set prefix ~/.npm-global
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.zshrc
source ~/.zshrc

Or use one-shot sudo npm install -g memex-mvp.

Want to try without installing globally?

npx memex-mvp install

Install via AI skill (Claude Code / OpenClaw)

If you'd rather have an AI agent walk you through everything, drop the install-memex skill into ~/.claude/skills/:

mkdir -p ~/.claude/skills
curl -fsSL https://raw.githubusercontent.com/parallelclaw/memex-mvp/main/skills/install-memex/SKILL.md \
  -o ~/.claude/skills/install-memex/SKILL.md

Then in Claude Code (or any Skills-aware agent) just say:

install memex

…or /install-memex. The agent handles npm install, MCP-config wiring, auto-capture daemon, and verification — ~2 minutes.

---

Connect to your MCP client

After install, point your client at memex (an alias of server.js exposed on PATH):

Claude Code

claude mcp add memex --scope user -- memex

Cursor / Cline / Continue / Zed

Add to that client's MCP config (e.g. ~/.cursor/mcp.json):

{
  "mcpServers": {
    "memex": { "command": "memex" }
  }
}

Restart the client. Try the prompt:

"Use memex_overview to show me what's in my AI memory."

If you see a snapshot of sources and recent conversations — you're done.

For a fully-automated install across all detected MCP clients, see the AI-driven install guide on the landing page (paste the prompt into any MCP-enabled agent, it'll wire everything up itself).

---

Terminal CLI (v0.7+) — query memex without MCP

The 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:

memex search "Postgres migration"          # full-text search
memex search "Q2 deck" --chat "Memex Bot"  # scope to one conversation by title
memex search "JWT" --as-of 2026-05-01      # v0.8.1: time-travel — only msgs before date
memex when "Brian Chesky"                   # v0.8.1: "when did we talk about X" — dates + chats
memex recent --limit 5                      # last 5 messages across all sources
memex list --source web                     # all saved URLs
memex get web-1582ab51a7b7                  # full content of one conversation
memex overview                              # snapshot of corpus + v0.8.1: capture streak
memex projects                              # distinct project_paths captured
memex import ~/projects/memex/result.json  # v0.10.12: ingest any file from any path
memex help                                  # full user guide (HELP.md)
memex --help                                # command reference

Ingest from any path (v0.10.12+)

memex import ~/projects/memex/result.json           # auto-detects Telegram JSON
memex import ~/Downloads/ChatExport_2026-05-18/     # Telegram HTML export directory
memex import ~/path/to/session.jsonl                # Claude Code JSONL
memex import ~/Downloads/result.json --force        # skip Telegram privacy gate
memex import some-file --format claude-jsonl        # explicit format override

For 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).

Every 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.

When 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.

---

Auto-context (v0.8+) — Claude already knows what you were doing

After 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.

# Adding/removing the hook outside the install flow:
memex hook install        # add SessionStart hook (idempotent)
memex hook uninstall      # remove only the memex entry, preserves other hooks
memex hook status         # show current state

# Inspecting what gets injected:
memex context             # dry-run the hook output for the current dir
memex context --pwd /path # for a different project
memex context --no-source telegram  # exclude a source

The hook respects existing hooks (e.g. gstack, custom user hooks) — they're preserved untouched.

Currently only Claude Code has native SessionStart hooks. For Cursor / Cline / Continue / Zed, MCP-tool-based fallback is on the v0.9.0 roadmap.

---

Save URLs into memex (v0.6+)

Once 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, …:

Save https://www.perplexity.ai/share/<id> to memex
Add this article to my memex: https://example.com/long-post

The 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.

Perplexity 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.

Memex stays 100% local — the agent fetches, memex only stores. Zero outbound calls from memex itself.

---

Telegram chats (v0.10+) — agent walks you through it

Telegram-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.

How it works:

1. The daemon watches ~/Downloads/Telegram Desktop/ in the background. No setup needed — already on after install.
2. You export a chat from Telegram Desktop (chat → ⋮ → Export chat history → HTML or JSON).
3. memex detects the export, moves it to ~/.memex/pending/ (NOT into your DB yet).
4. Your AI agent (or you in terminal) calls memex_telegram_pending — sees a numbered list with chat name, msg count, date range.
5. You pick which to import. Sensitive ones (Bank, Therapist, Tinder) — skip. memex remembers and won't ask again.
6. Future re-exports of allowed chats auto-merge. Skipped ones stay out.

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:

• Check if Telegram Desktop is installed (give you the right download link if not)
• Check the 24h post-login export-block window (tell you when you can export)
• Show the click-path in Telegram
• Wait for your export, then present the picker

Three modes: pick (default — review each export), auto (allowed chats auto-import; new ones go to pending), manual (watcher off — drop files yourself).

Terminal equivalents: memex telegram check / pending / import 1 3 5 / skip 2 / mode auto. Full reference: memex telegram --help.

v0.10.1: 4-channel proactive notification. You'll find out about pending exports from whichever channel reaches you first:

1. 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.
2. In the terminal — any memex CLI command appends a 💡 tip line when pending > 0. Throttled to once per 6h.
3. 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 <auto|claude-cli|claude-desktop|terminal|none>.
4. 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.

---

Web dashboard (v0.10.8+) — see your own memory

Opt-in, read-only local UI for browsing the corpus without any AI in the loop. Same SQLite, different surface.

memex web --open      # localhost:8765, opens in browser
memex web --port 9000 # custom port
memex web --public --token s3cret   # bind on 0.0.0.0 with bearer auth (for remote / tunnel)
memex web --help

Five pages:

Page	What it shows
/	Stats grid · sources breakdown · pending Telegram callout · recent 10 conversations
/conversations	Live FTS5 search via htmx (200ms debounce) · source-chip filters · hit counts per chat
/c/:id	Verbatim transcript in chat-bubbles · in-chat search with <mark> highlight · paged
/pending	Telegram exports awaiting decision · bulk Import / Skip checkboxes · decision history
/settings	Daemon status · DB path & size · hooks installed · TG decisions counts (read-only)

Design constraints:

• Opt-in, not always-on. memex web starts the server; Ctrl+C stops it. No daemon.
• Read-only by default. The only writes are TG import / skip on the /pending page — same privacy gate as memex telegram import.
• Localhost-only by default. Binds 127.0.0.1. Use --public --token <…> for remote access (cron-friendly: same endpoint reserved for the future multi-host sync API).
• No build step. Node raw http + tagged template literals + htmx 14KB CDN. Total client bundle: ~30KB.
• Brand-aligned. Same Inter + mint palette as memex.parallelclaw.ai.

---

What it captures

Source	How it gets in
Claude Code sessions	Auto: memex-sync watches ~/.claude/projects/
Claude Cowork	Auto: same watcher, including all subagent transcripts
Cursor IDE chats	Auto: reads Cursor's local SQLite session store
Continue / Zed	Auto: filesystem watchers per platform
Obsidian notes	Auto: per-vault markdown watcher
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 <indices>. Allow-list remembers your decisions so future re-exports auto-merge. JSON + HTML both supported. (Legacy path still works: drop into ~/.memex/inbox/.)
Telegram (live)	Run memex-bot — captures messages you send/forward to your private bot
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

All sources land in the same FTS5 corpus, searchable by one memex_search call.

---

MCP tools

Tool	What it does
memex_overview	Corpus snapshot — sources, counts, recent chats, daemon health
memex_search	Full-text search with BM25 × recency boost. Filter by date range (since_ts/until_ts), one session (conversation_id), source/project/chat
memex_recent	Most recent messages across all sources
memex_get_conversation	Transcript by conversation_id — page long sessions with offset/order (desc = freshest first); reports total
memex_list_conversations	Conversations sorted by activity, filterable by source
memex_list_projects	Distinct project paths captured (for the project filter)
memex_archive_conversation	Hide a chat from default listings (data preserved)
memex_export_markdown	Export one conversation as Markdown (for Obsidian round-trip)
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
memex_list_sources	Per-source enabled/disabled + counts
memex_status	Daemon health: PID, last capture, watched files
memex_sources_status	Which sources are captured + the exact CLI to opt out
memex_help	Returns the full user guide with concrete use cases
memex_telegram_check	v0.10+: Detect Telegram Desktop, login age (24h block), pending count, suggested next step
memex_telegram_pending	v0.10+: List exports staged for review with chat name + msg count + dates
memex_telegram_import	v0.10+: Import selected exports into memex.db (by index or title) — auto-allowlists
memex_telegram_skip	v0.10+: Mark chats as "never index" — applies to future re-exports too
memex_telegram_mode	v0.10+: Get/set capture mode: pick (default) · auto · manual

Detailed search parameters (filters, sort, format) live in HELP.md.

---

Why memex (vs. cloud memory services)

Concern	memex	Cloud memory (Mem0 / Supermemory / …)
Where your data lives	Your machine, one SQLite file	Their servers
Cost per ingested turn	0 (no LLM call on write)	$0.005+/1K tokens
Cross-AI corpus	✅ same DB for all clients	⚠️ depends on plugin coverage
Telegram ingestion	✅ first-class	❌ not supported
Verbatim storage	✅ raw text preserved	❌ usually fact-extracted
Survives if vendor blocks you	✅ your DB stays on disk	❌ data inaccessible
Offline / air-gapped	✅	❌
Trade-off	Lexical search (FTS5), not semantic	Semantic + reranker, but cloud-bound

---

Privacy

• Zero network egress during normal operation. The MCP server only listens on stdio.
• 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).
• The DB is one file at ~/.memex/data/memex.db. Back it up, encrypt it (FileVault is enough), rm it — your call.
• Source opt-out per category: memex-sync sources <name> disable keeps that source out of the corpus permanently.

See PRIVACY section in the Russian README for the full breakdown.

---

Cross-device

Experimental real-time sync (v0.11.11+). memex can now converge two or more machines' databases over the network — laptop + VPS, two VPSes via a common transit, any number of nodes — with no cloud relay. HTTP push/pull

• cursors, conflict-free via the existing UNIQUE(source, conversation_id, msg_id) constraint (append-only verbatim memory never edits, so there's nothing to merge), TLS + 256-bit bearer, durable as a systemd/LaunchAgent service, hands-off on a timer.

The right mental model. A "hub" is whichever node is reachable by the others, NOT necessarily a fancy always-on VPS. SSH access (port 22) counts as reachable — meaning every machine you can SSH into is a hub candidate. The deployed-patterns table in SYNC.md walks through four real topologies, in decreasing order of "easy":

1. VPS-as-hub on a public port — easiest when nothing blocks the port
2. VPS-as-hub via SSH tunnel — when public port is blocked
3. Mac-as-hub via reverse SSH tunnel — when the laptop is the only reachable node, via ssh -fN -R from the VPS to the Mac. No public port anywhere; sync rides on port 22 only.
4. Transit-hub via chained ssh -R — multi-node mesh where one VPS acts as a meeting point others reverse-tunnel into. Used live for a San Francisco Mac + Italy VPS + Asia VPS that no public-port plan could glue together (Asia/Europe SSH path works; Mac VPN to Asia didn't).

The simplest happy path:

export MEMEX_SYNC_EXPERIMENTAL=1
# hub (always-on machine):
memex-sync sync-server install --bind 0.0.0.0
memex-sync sync-server invite --host <public-ip>     # prints memex-pair:...
# spoke (laptop):
memex-sync sync-pair memex-pair:...                  # one paste — host+cert+token
memex-sync sync-run vps
memex-sync sync-schedule install --every 15m         # auto-sync from here

Agents can emit the pairing token from a chat phrase via the memex_sync_invite MCP tool. Full guide + wire-protocol spec: SYNC.md. Gated behind MEMEX_SYNC_EXPERIMENTAL=1; the protocol may change before it graduates to stable.

A mesh-bootstrap wizard that probes reachability and picks the right topology automatically (so you don't have to know whether you're in case 1, 2, 3, or 4) is the next big item — see Roadmap §1 in SYNC.md.

Simple alternative (no sync engine). The corpus is one SQLite file plus a small inbox directory, so any file-sync tool (iCloud Drive symlink, Syncthing, one-time scp) handles it for single-writer setups. See README.ru.md and MULTI_MACHINE.md for tested recipes.

---

Limitations (v0.5)

• 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.
• macOS-first — daemon installer registers a LaunchAgent. Linux works as a foreground process; Windows untested.
• Single user — the Telegram bot serves exactly one Telegram user_id (you).
• No webhook for the bot — long-polling only, captures buffer ~24h server-side when laptop is offline.

---

Resources

• 🏠 Landing: memex.parallelclaw.ai — the AI-driven install prompt
• 📖 HELP.md — concrete use cases + full tool reference + troubleshooting
• 🤖 bot/README.md — Telegram capture bot setup
• 🇷🇺 README.ru.md — full Russian README with deeper privacy / migration sections
• 🐛 Issues on GitHub

---

License

MIT — see LICENSE.