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 · …
One-line install (recommended):
curl -fsSL https://memex.parallelclaw.ai/install.sh | bashThat single command:
- Verifies Node ≥ 20.
- Runs
npm install -g memex-mvp, auto-fixingEACCESby moving npm's prefix to~/.npm-global(nosudoneeded, ever). - Installs the auto-capture daemon (
memex-sync install) with the v0.8 Brian Chesky auto-context hook into~/.claude/settings.json(preserves existing hooks). - Backfills history (
memex-sync scan) so memex already knows about your past sessions. - If
claude(Claude Code CLI) is on PATH, runsclaude mcp add memex --scope user -- memexto 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-captureIf 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 ~/.zshrcOr use one-shot sudo npm install -g memex-mvp.
Want to try without installing globally?
npx memex-mvp installIf 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.mdThen 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.
After install, point your client at memex (an alias of server.js exposed on PATH):
claude mcp add memex --scope user -- memexAdd 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).
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 referencememex 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 overrideFor 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.
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 sourceThe 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.
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-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:
- The daemon watches
~/Downloads/Telegram Desktop/in the background. No setup needed — already on after install. - You export a chat from Telegram Desktop (chat → ⋮ → Export chat history → HTML or JSON).
- memex detects the export, moves it to
~/.memex/pending/(NOT into your DB yet). - Your AI agent (or you in terminal) calls
memex_telegram_pending— sees a numbered list with chat name, msg count, date range. - You pick which to import. Sensitive ones (Bank, Therapist, Tinder) — skip. memex remembers and won't ask again.
- 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:
- In the AI agent (active session) —
memex_search/memex_recent/memex_overviewtool responses include atelegram_pendingfield with chat names. Agent surfaces it as a natural aside. - In the terminal — any
memexCLI command appends a 💡 tip line when pending > 0. Throttled to once per 6h. - macOS native notification (opt-in) — daemon fires a banner when a new export is staged.
memex telegram notifications onto enable. Default OFF for lock-screen privacy; add--show-titlesif you want chat names in the banner. v0.10.4+ clickable: ifterminal-notifieris 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 withmemex telegram pendingqueued. Override priority viamemex telegram notifications target <auto|claude-cli|claude-desktop|terminal|none>. - Brian Chesky hook (next Claude Code session) —
memex contextinjection includes a "🆕 N exports awaiting review" block with chat names. Claude leads with the question before you type anything.
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 --helpFive 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 webstarts the server; Ctrl+C stops it. No daemon. - Read-only by default. The only writes are TG import / skip on the
/pendingpage — same privacy gate asmemex 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.
| 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.
| Tool | What it does |
|---|---|
memex_overview |
Corpus snapshot — sources, counts, recent chats, daemon health |
memex_search |
Full-text search with BM25 × recency boost |
memex_recent |
Most recent messages across all sources |
memex_get_conversation |
Full transcript by conversation_id |
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.
| 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 | |
| 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 |
- 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),rmit — your call. - Source opt-out per category:
memex-sync sources <name> disablekeeps that source out of the corpus permanently.
See PRIVACY section in the Russian README for the full breakdown.
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":
- VPS-as-hub on a public port — easiest when nothing blocks the port
- VPS-as-hub via SSH tunnel — when public port is blocked
- Mac-as-hub via reverse SSH tunnel — when the laptop is the only
reachable node, via
ssh -fN -Rfrom the VPS to the Mac. No public port anywhere; sync rides on port 22 only. - 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 hereAgents 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.
- 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.
- 🏠 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
MIT — see LICENSE.