memex-mvp 0.5.2 → 0.5.4
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +115 -464
- package/README.ru.md +577 -0
- package/bot/README.md +6 -2
- package/package.json +2 -1
- package/skills/install-memex/README.md +58 -0
- package/skills/install-memex/SKILL.md +169 -0
package/README.md
CHANGED
|
@@ -1,542 +1,193 @@
|
|
|
1
1
|
# memex-mvp · your AI's missing memory
|
|
2
2
|
|
|
3
|
-
>
|
|
3
|
+
> **English** · [Русский](README.ru.md)
|
|
4
4
|
|
|
5
|
-
|
|
5
|
+
[](https://www.npmjs.com/package/memex-mvp)
|
|
6
|
+
[](https://www.npmjs.com/package/memex-mvp)
|
|
7
|
+
[](LICENSE)
|
|
6
8
|
|
|
7
|
-
|
|
9
|
+
> **A single store for all your AI and Telegram chats.**
|
|
8
10
|
|
|
9
|
-
|
|
11
|
+
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.
|
|
10
12
|
|
|
11
|
-
|
|
13
|
+
No cloud. No account. No data leaves your machine.
|
|
12
14
|
|
|
13
15
|
```
|
|
14
|
-
~/.memex/inbox/
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
MCP server (stdio JSON-RPC)
|
|
22
|
-
↓
|
|
23
|
-
любой клиент → 8 tool'ов:
|
|
24
|
-
• memex_overview — снэпшот корпуса + статус auto-capture
|
|
25
|
-
• memex_search — full-text поиск (с дедупом по чатам)
|
|
26
|
-
• memex_recent — последние N сообщений
|
|
27
|
-
• memex_list_conversations — список чатов по recency
|
|
28
|
-
• memex_get_conversation — полный транскрипт чата
|
|
29
|
-
• memex_archive_conversation — скрыть чат из выдачи (но не из поиска)
|
|
30
|
-
• memex_status — здоровье memex-sync daemon'а
|
|
31
|
-
• memex_list_sources — что импортировано
|
|
16
|
+
~/.memex/inbox/ ← drop chat exports here (or symlink AI session files)
|
|
17
|
+
↓ chokidar watcher
|
|
18
|
+
parser (Telegram JSON · Claude Code JSONL · Cursor SQLite · Obsidian md)
|
|
19
|
+
↓
|
|
20
|
+
SQLite + FTS5 (~/.memex/data/memex.db)
|
|
21
|
+
↓
|
|
22
|
+
MCP server → Cursor · Cline · Claude Code · Continue · Zed · Codex · …
|
|
32
23
|
```
|
|
33
24
|
|
|
34
|
-
Спроси своему агенту «помнишь как мы решили проблему с миграцией Postgres?» — он **сам** вызовет `memex_search`, найдёт релевантное и ответит с реальным контекстом.
|
|
35
|
-
|
|
36
|
-
---
|
|
37
|
-
|
|
38
|
-
## Requirements / Требования
|
|
39
|
-
|
|
40
|
-
### Обязательное (без этого memex не запустится)
|
|
41
|
-
|
|
42
|
-
- **Node.js 20.x – 24.x** (рекомендуется **22 LTS**). В репо есть `.nvmrc` со значением `22` — если у тебя `nvm`, выполни `nvm use` в директории проекта.
|
|
43
|
-
- **macOS 12+ или Linux** с inotify (Windows — только через WSL).
|
|
44
|
-
- **Xcode Command Line Tools** на macOS (`xcode-select --install`) — нужны для нативной сборки `better-sqlite3`, если для твоей Node-версии нет prebuilt binaries.
|
|
45
|
-
- **MCP-совместимый AI-клиент** для использования: Claude Code, Cursor, Cline, Continue, Zed или любой другой клиент с поддержкой MCP. Без этого memex стрит индекс, но обращаться к нему будет некому.
|
|
46
|
-
|
|
47
|
-
### Опциональное (по ситуации)
|
|
48
|
-
|
|
49
|
-
- **Telegram Desktop** — если хочешь индексировать TG-чаты. Мобильное приложение Telegram **не умеет** экспорт; нужен именно Desktop-клиент.
|
|
50
|
-
- **iCloud Drive / Syncthing** — если хочешь sync БД между несколькими своими ноутами.
|
|
51
|
-
- **Ollama / llama.cpp** — на будущее для локального LLM-extraction слоя (профильные факты). Сейчас в roadmap'е.
|
|
52
|
-
|
|
53
|
-
### Аппаратные требования (small)
|
|
54
|
-
|
|
55
|
-
- **Disk space:** ~5-30 МБ типичный корпус за год. Большие Telegram-экспорты с медиа — отдельно, до сотен МБ.
|
|
56
|
-
- **RAM:** daemon ~30 МБ, MCP-сервер ~50 МБ. Незаметно.
|
|
57
|
-
- **CPU:** на холостом ходу < 1%. Импорт сессии — миллисекунды.
|
|
58
|
-
|
|
59
|
-
### Известные ограничения
|
|
60
|
-
|
|
61
|
-
| Что **не** работает | Почему |
|
|
62
|
-
|---|---|
|
|
63
|
-
| ❌ Web-only AI (ChatGPT в браузере, Claude.ai web) | Эти сессии живут на серверах вендора, на твоём диске их нет |
|
|
64
|
-
| ❌ Мобильные AI-приложения (ChatGPT iOS, Claude Android) | Phone-data не пишется на твой компьютер |
|
|
65
|
-
| ❌ Сессии на VPS / в облаке | Memex читает локальную файловую систему |
|
|
66
|
-
| ❌ Windows напрямую | Только через WSL (chokidar на Win работает плохо без inotify-shim) |
|
|
67
|
-
| ❌ Auto-capture daemon на Linux | `npx memex-sync install` работает только на macOS (LaunchAgent). На Linux запускай daemon в foreground или сделай свой systemd unit |
|
|
68
|
-
| ❌ Mobile capture сегодня | В roadmap'е — Telegram-бот в `bot/` директории |
|
|
69
|
-
|
|
70
|
-
### Положительное «ограничение»
|
|
71
|
-
|
|
72
|
-
✅ **Internet не нужен.** Memex после установки работает полностью офлайн. Никаких phone-home, никаких API-ключей, никаких облачных зависимостей. Это feature, не bug.
|
|
73
|
-
|
|
74
|
-
> ⚠ **Node 25+ известная проблема.** На bleeding-edge Node (25.x) `better-sqlite3` ещё не имеет prebuilt binaries — fallback на компиляцию из исходников падает на macOS с `fatal error: 'climits' file not found`. Решение: `nvm install 22 && nvm use 22`, потом `npm install`.
|
|
75
|
-
|
|
76
25
|
---
|
|
77
26
|
|
|
78
|
-
##
|
|
79
|
-
|
|
80
|
-
```bash
|
|
81
|
-
git clone https://github.com/parallelclaw/memex-mvp.git
|
|
82
|
-
cd memex-mvp
|
|
83
|
-
nvm use # подхватит Node 22 из .nvmrc (если у тебя nvm)
|
|
84
|
-
bash install.sh
|
|
85
|
-
```
|
|
86
|
-
|
|
87
|
-
Скрипт создаст `~/.memex/{inbox,data}/`, поставит npm-зависимости, выведет пути для конфига Claude.
|
|
88
|
-
|
|
89
|
-
### Подключение к Claude Code
|
|
90
|
-
|
|
91
|
-
Сначала возьми **два абсолютных пути** в терминале:
|
|
92
|
-
|
|
93
|
-
```bash
|
|
94
|
-
pwd # → путь до memex-mvp (из директории memex-mvp)
|
|
95
|
-
which node # → путь до бинарника node (например /Users/you/.nvm/versions/node/v24.15.0/bin/node)
|
|
96
|
-
```
|
|
97
|
-
|
|
98
|
-
В `~/.claude/config.json` добавь, подставив оба пути:
|
|
99
|
-
|
|
100
|
-
```json
|
|
101
|
-
{
|
|
102
|
-
"mcpServers": {
|
|
103
|
-
"memex": {
|
|
104
|
-
"command": "/абсолютный/путь/до/node",
|
|
105
|
-
"args": ["/абсолютный/путь/до/memex-mvp/server.js"]
|
|
106
|
-
}
|
|
107
|
-
}
|
|
108
|
-
}
|
|
109
|
-
```
|
|
110
|
-
|
|
111
|
-
**Почему абсолютный путь к node, а не просто `"node"`?** GUI-приложения (Cursor, Cline VS Code, Claude Desktop) на macOS часто **не наследуют PATH из shell'a** (`~/.zshrc`). С `"command": "node"` MCP-сервер падает с `spawn node ENOENT` — особенно если node поставлен через nvm. Всегда используй путь из `which node`.
|
|
112
|
-
|
|
113
|
-
Перезапусти Claude Code. Готово — у тебя в session появятся `memex_*` tool'ы.
|
|
114
|
-
|
|
115
|
-
### Подключение к Cursor / Cline / Continue / Zed
|
|
116
|
-
|
|
117
|
-
Каждый клиент имеет свой `mcpServers` config (обычно в `~/.cursor/mcp.json`, `.cline/...`, и т.п.). Структура та же — `command` = абсолютный путь до node, `args` = `[путь к server.js]`. Та же ENOENT-проблема актуальна для всех GUI-MCP клиентов.
|
|
118
|
-
|
|
119
|
-
---
|
|
120
|
-
|
|
121
|
-
## Что поддерживается
|
|
122
|
-
|
|
123
|
-
| Источник | Формат | Статус |
|
|
124
|
-
|----------|--------|--------|
|
|
125
|
-
| **Claude Code** | `*.jsonl` сессии в `~/.claude/projects/` | ✅ работает (nested + flat форматы) |
|
|
126
|
-
| **Claude Cowork** | `cowork-*.jsonl` (через filename prefix), включая subagents | ✅ работает |
|
|
127
|
-
| **Cursor IDE** (Composer + Chat) | SQLite `state.vscdb` в `~/Library/Application Support/Cursor/` | ✅ работает (poll каждые 5 мин) |
|
|
128
|
-
| **Obsidian** vault notes | `.md` файлы + YAML frontmatter | ✅ работает (FSEvents, hash-based dedupe) |
|
|
129
|
-
| **Telegram** | `result.json` из Desktop export | ✅ работает |
|
|
130
|
-
| Claude.ai web export | будет в v0.3 | — |
|
|
131
|
-
| ChatGPT export | будет в v0.3 | — |
|
|
132
|
-
| Apple Notes | будет в v0.3 | — |
|
|
27
|
+
## Install in 60 seconds
|
|
133
28
|
|
|
134
|
-
|
|
135
|
-
|
|
136
|
-
|
|
137
|
-
- `code-*.jsonl` или произвольное имя → tagged как `claude-code`
|
|
138
|
-
- `cowork-*.jsonl` → tagged как `claude-cowork`
|
|
139
|
-
- `cursor-*.jsonl` → tagged как `cursor`
|
|
140
|
-
- `obsidian-*.jsonl` → tagged как `obsidian`
|
|
141
|
-
|
|
142
|
-
Это позволяет фильтровать `memex_search` по конкретной экосистеме (`source: "cursor"`, `source: "obsidian"` и т.д.).
|
|
143
|
-
|
|
144
|
-
### Cursor IDE source — особый случай
|
|
145
|
-
|
|
146
|
-
Cursor хранит историю в SQLite (`state.vscdb`), не в JSONL-файлах. memex-sync daemon **поллит** эту БД каждые 5 минут (FSEvents бессмысленно — Cursor пишет в WAL практически на каждый keystroke). При обнаружении composer'а с обновлённым `lastUpdatedAt` daemon экспортит его dialogue (без thinking-bubbles и tool-call'ов) в inbox как `cursor-<short>.jsonl`. Заголовок берётся из `composerData.name` напрямую.
|
|
147
|
-
|
|
148
|
-
Поддерживаемые ОС для Cursor: macOS, Linux, Windows (пути в `lib/parse-cursor.js`).
|
|
149
|
-
|
|
150
|
-
### Obsidian source — заметки как первоклассные сущности
|
|
151
|
-
|
|
152
|
-
memex автоматически находит Obsidian-vault'ы в стандартных местах (`~/Documents/`, `~/Obsidian/`, `~/Library/Mobile Documents/iCloud~md~obsidian/Documents/` для iCloud-синка). Vault — это любая папка с `.obsidian/` подпапкой внутри. Можно явно указать пути через env-переменную:
|
|
153
|
-
|
|
154
|
-
```bash
|
|
155
|
-
export MEMEX_OBSIDIAN_VAULTS=/path/to/vault1,/path/to/vault2
|
|
29
|
+
```sh
|
|
30
|
+
npm install -g memex-mvp
|
|
31
|
+
memex-sync install # macOS LaunchAgent for auto-capture
|
|
156
32
|
```
|
|
157
33
|
|
|
158
|
-
|
|
159
|
-
|
|
160
|
-
**Privacy**:
|
|
161
|
-
- Обнаружение vault'ов opt-in (только стандартные пути; кастомные через env var)
|
|
162
|
-
- Игнорируются: `.obsidian/`, `.trash/`, `.git/`, `.DS_Store`, `*.sync-conflict-*`
|
|
163
|
-
- Per-note opt-out через frontmatter `memex: false`
|
|
164
|
-
- Hash-based dedupe — пишем в inbox только когда содержание реально изменилось, не на каждый mtime-touch
|
|
165
|
-
|
|
166
|
-
### Bulk import за одну команду
|
|
34
|
+
If `npm install -g` hits `EACCES` (system Node on macOS), either fix your prefix once:
|
|
167
35
|
|
|
168
|
-
|
|
169
|
-
|
|
170
|
-
|
|
171
|
-
|
|
172
|
-
|
|
173
|
-
npx memex-sync scan-cursor # только Cursor
|
|
174
|
-
npx memex-sync scan-obsidian # только Obsidian vault(s)
|
|
36
|
+
```sh
|
|
37
|
+
mkdir -p ~/.npm-global
|
|
38
|
+
npm config set prefix ~/.npm-global
|
|
39
|
+
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.zshrc
|
|
40
|
+
source ~/.zshrc
|
|
175
41
|
```
|
|
176
42
|
|
|
177
|
-
|
|
178
|
-
|
|
179
|
-
### Two pieces
|
|
180
|
-
|
|
181
|
-
memex поставляется в виде **двух независимых частей:**
|
|
182
|
-
|
|
183
|
-
- **MCP server** (`server.js`) — пассивная база знаний, всегда доступна после `npm install`. Отдаёт 8 tool'ов любому MCP-агенту.
|
|
184
|
-
- **memex-sync** (`ingest.js`) — **опциональный** фоновый daemon. Watch'ит `~/.claude/projects/` (Code) и `~/Library/Application Support/Claude/local-agent-mode-sessions/` (Cowork) через FSEvents и автоматически добавляет новые сессии в память в реальном времени.
|
|
185
|
-
|
|
186
|
-
> **Без memex-sync память замёрзла** на момент последнего ручного импорта. **С ним** — каждая новая сессия становится searchable за ~1.5 секунды.
|
|
43
|
+
Or use one-shot `sudo npm install -g memex-mvp`.
|
|
187
44
|
|
|
188
|
-
|
|
45
|
+
**Want to try without installing globally?**
|
|
189
46
|
|
|
190
|
-
|
|
191
|
-
|
|
192
|
-
```bash
|
|
193
|
-
npx memex-sync install
|
|
47
|
+
```sh
|
|
48
|
+
npx memex-mvp install
|
|
194
49
|
```
|
|
195
50
|
|
|
196
|
-
|
|
197
|
-
|
|
198
|
-
```bash
|
|
199
|
-
npx memex-sync status # три состояния: installed / running / watching
|
|
200
|
-
npx memex-sync logs # tail -f лог в реальном времени
|
|
201
|
-
npx memex-sync uninstall # снять с автозапуска (БД остаётся)
|
|
202
|
-
```
|
|
203
|
-
|
|
204
|
-
Без `install` daemon можно гонять и в foreground'е (для отладки):
|
|
205
|
-
|
|
206
|
-
```bash
|
|
207
|
-
npx memex-sync # = serve, в foreground
|
|
208
|
-
```
|
|
209
|
-
|
|
210
|
-
### Что под капотом
|
|
211
|
-
|
|
212
|
-
- chokidar (FSEvents на macOS, inotify на Linux) на обе source-директории
|
|
213
|
-
- Per-file state в `~/.memex/data/ingest-state.json` (sha1 первых 256B + size + mtime) — повторный запуск пропускает неизменённые файлы
|
|
214
|
-
- Safety rescan каждые 30 минут — ловит пропущенные FSEvents после sleep/lid-close
|
|
215
|
-
- Atomic writes (temp + rename) в `~/.memex/inbox/` — никаких частичных JSONL
|
|
216
|
-
- Idempotent: новые сообщения идут через UNIQUE(msg_id), дубли отсекаются на уровне БД
|
|
217
|
-
- LaunchAgent работает с `LowPriorityIO=true`, `Nice=5` — не мешает основной работе ноута
|
|
218
|
-
|
|
219
|
-
memex MCP server и memex-sync — два независимых процесса. MCP server отвечает агентам, memex-sync кормит inbox. Связи нет, кроме общей файловой системы.
|
|
220
|
-
|
|
221
|
-
### Управление источниками
|
|
222
|
-
|
|
223
|
-
По умолчанию memex-sync **собирает всё что находит** на машине: Claude Code, Cowork, Cursor, Obsidian (auto-detect). Это удобно для quick-start, но любой источник можно отключить через CLI без удаления daemon'а:
|
|
224
|
-
|
|
225
|
-
```bash
|
|
226
|
-
npx memex-sync sources # показать что сейчас включено
|
|
227
|
-
npx memex-sync sources cursor disable # выключить cursor
|
|
228
|
-
npx memex-sync sources cursor enable # вернуть
|
|
229
|
-
npx memex-sync vault add /path/to/MyVault # явный список Obsidian-vault'ов
|
|
230
|
-
npx memex-sync vault remove /path # убрать
|
|
231
|
-
npx memex-sync restart # применить изменения
|
|
232
|
-
```
|
|
233
|
-
|
|
234
|
-
Конфиг живёт в `~/.memex/config.json`. Файла нет → сборка по дефолту. Как только что-то изменено через CLI — файл создаётся, daemon его уважает.
|
|
235
|
-
|
|
236
|
-
Privacy: agent через `memex_sources_status` сам показывает что именно отслеживается, и **никогда не выключает источники сам** — это всегда команда от пользователя.
|
|
237
|
-
|
|
238
|
-
### Подсказка для агента
|
|
239
|
-
|
|
240
|
-
Если ты подключил memex к Claude Code/Cursor/Cline и каждый раз когда вызываешь `memex_overview` видишь сверху ⚪ или 🔴 — это значит auto-capture не включён. Агент сам это увидит и предложит юзеру команду `npx memex-sync install`. Это та самая «один раз и забыл» механика — без README-чтения.
|
|
241
|
-
|
|
242
|
-
---
|
|
243
|
-
|
|
244
|
-
## Между устройствами / Across devices
|
|
245
|
-
|
|
246
|
-
### По-русски
|
|
247
|
-
|
|
248
|
-
Memex живёт на одной машине: daemon ловит локальные файлы, SQLite строится локально, MCP отдаёт локально.
|
|
249
|
-
|
|
250
|
-
Три паттерна для multi-device сегодня:
|
|
251
|
-
|
|
252
|
-
1. **Синк SQLite-файла.** `~/.memex/data/memex.db` — обычный файл. Реплицируй через iCloud / Syncthing / rsync / git-annex. Daemon пишет на основной машине; остальные читают тот же файл через свой локальный memex MCP-сервер. Один writer, много readers.
|
|
253
|
-
2. **Memex на каждом устройстве независимо.** Установи memex отдельно на каждый ноут. Каждый строит свой корпус. Нет синка, нет конфликтов — но память не унифицирована.
|
|
254
|
-
3. **Mobile через Telegram-бот** *(в roadmap'е, код написан в `bot/`).* Пересылаешь сообщения в @memex_bot с телефона → бот пишет JSON в `~/.memex/inbox/` основной машины → индексируется автоматически.
|
|
51
|
+
### Install via AI skill (Claude Code / OpenClaw)
|
|
255
52
|
|
|
256
|
-
|
|
257
|
-
|
|
258
|
-
# Option A — symlink ~/.memex/data в iCloud Drive
|
|
259
|
-
mv ~/.memex/data ~/Library/Mobile\ Documents/com~apple~CloudDocs/memex/data
|
|
260
|
-
ln -s ~/Library/Mobile\ Documents/com~apple~CloudDocs/memex/data ~/.memex/data
|
|
53
|
+
If you'd rather have an AI agent walk you through everything, drop the
|
|
54
|
+
[install-memex skill](skills/install-memex/) into `~/.claude/skills/`:
|
|
261
55
|
|
|
262
|
-
|
|
263
|
-
|
|
56
|
+
```sh
|
|
57
|
+
mkdir -p ~/.claude/skills
|
|
58
|
+
curl -fsSL https://raw.githubusercontent.com/parallelclaw/memex-mvp/main/skills/install-memex/SKILL.md \
|
|
59
|
+
-o ~/.claude/skills/install-memex/SKILL.md
|
|
264
60
|
```
|
|
265
61
|
|
|
266
|
-
|
|
62
|
+
Then in Claude Code (or any Skills-aware agent) just say:
|
|
267
63
|
|
|
268
|
-
|
|
64
|
+
> install memex
|
|
269
65
|
|
|
270
|
-
|
|
271
|
-
|
|
272
|
-
Memex lives on one machine: daemon catches local files, SQLite builds locally, MCP serves locally.
|
|
273
|
-
|
|
274
|
-
Three patterns for multi-device today:
|
|
275
|
-
|
|
276
|
-
1. **Sync the SQLite file.** `~/.memex/data/memex.db` is a regular file. Replicate via iCloud / Syncthing / rsync / git-annex. Daemon writes on your primary machine; other machines read the same file through their local memex MCP server. One writer, many readers.
|
|
277
|
-
2. **Memex on each device independently.** Install memex separately on each laptop. Each builds its own corpus. No sync, no conflicts — but memory isn't unified.
|
|
278
|
-
3. **Mobile via Telegram bot** *(roadmap, code drafted in `bot/`).* Forward messages or write thoughts to @memex_bot from your phone → bot writes JSON to `~/.memex/inbox/` on your primary machine → indexed automatically.
|
|
279
|
-
|
|
280
|
-
iCloud setup on macOS: same commands as in the Russian section above (paths are language-agnostic).
|
|
281
|
-
|
|
282
|
-
⚠ **One writer only.** Run the auto-capture daemon (`memex-sync`) on exactly one machine. Other devices read the synced file through their local memex MCP server — they should not run the daemon on the same shared DB. Concurrent writers via filesystem sync can corrupt the WAL.
|
|
283
|
-
|
|
284
|
-
For 3 detailed patterns with Syncthing/rsync examples — see [MULTI_MACHINE.md](MULTI_MACHINE.md).
|
|
66
|
+
…or `/install-memex`. The agent handles `npm install`, MCP-config wiring,
|
|
67
|
+
auto-capture daemon, and verification — ~2 minutes.
|
|
285
68
|
|
|
286
69
|
---
|
|
287
70
|
|
|
288
|
-
##
|
|
289
|
-
|
|
290
|
-
> **Не то же самое что sync.** Это **разовый перенос** всей истории со старого ноута на новый — например при покупке нового мака. Sync — это паттерн в секции «Между устройствами» выше, когда два ноута постоянно делят одну БД через iCloud / Syncthing.
|
|
291
|
-
|
|
292
|
-
### По-русски
|
|
293
|
-
|
|
294
|
-
memex.db — обычный SQLite-файл, переезжает как любой документ.
|
|
295
|
-
|
|
296
|
-
**На старом ноуте:**
|
|
71
|
+
## Connect to your MCP client
|
|
297
72
|
|
|
298
|
-
|
|
299
|
-
# 1. Останови daemon чтобы не было активной записи
|
|
300
|
-
launchctl unload ~/Library/LaunchAgents/com.parallelclaw.memex.sync.plist 2>/dev/null
|
|
73
|
+
After install, point your client at `memex` (an alias of `server.js` exposed on `PATH`):
|
|
301
74
|
|
|
302
|
-
|
|
303
|
-
sqlite3 ~/.memex/data/memex.db "PRAGMA wal_checkpoint(TRUNCATE)"
|
|
75
|
+
### Claude Code
|
|
304
76
|
|
|
305
|
-
|
|
306
|
-
|
|
77
|
+
```sh
|
|
78
|
+
claude mcp add memex --scope user -- memex
|
|
307
79
|
```
|
|
308
80
|
|
|
309
|
-
|
|
310
|
-
|
|
311
|
-
**На новом ноуте:**
|
|
312
|
-
|
|
313
|
-
```bash
|
|
314
|
-
# 1. Установи memex как при первой установке
|
|
315
|
-
git clone https://github.com/parallelclaw/memex-mvp
|
|
316
|
-
cd memex-mvp && npm install
|
|
317
|
-
|
|
318
|
-
# 2. Положи DB-файл
|
|
319
|
-
mkdir -p ~/.memex/data
|
|
320
|
-
cp /path/to/memex-backup.db ~/.memex/data/memex.db
|
|
321
|
-
|
|
322
|
-
# 3. Пропиши MCP-конфиг с абсолютным путём к node (см. секцию "Подключение к Claude Code")
|
|
323
|
-
|
|
324
|
-
# 4. Перезапусти Cursor / Claude Code и вызови memex_overview
|
|
325
|
-
```
|
|
326
|
-
|
|
327
|
-
**Что переедет:** все разговоры, FTS5-индекс, Telegram-экспорты, conversation IDs. Поиск работает сразу.
|
|
328
|
-
|
|
329
|
-
**Что НЕ переедет автоматически:**
|
|
330
|
-
- Новые Claude Code / Cursor сессии нового ноута — это уже файлы нового ноута. Решение: `npx memex-sync install` на новом — daemon начнёт ловить новые сессии и добавлять их в ту же БД.
|
|
331
|
-
- `project_path` в существующих записях содержит **старые пути** (`/Users/oldname/...`). Memex не сломается, но `memex_list_projects` покажет старые пути. При необходимости — `UPDATE conversations SET project_path = REPLACE(...)` руками.
|
|
332
|
-
|
|
333
|
-
### In English
|
|
334
|
-
|
|
335
|
-
memex.db is a regular SQLite file — moves like any document.
|
|
81
|
+
### Cursor / Cline / Continue / Zed
|
|
336
82
|
|
|
337
|
-
|
|
83
|
+
Add to that client's MCP config (e.g. `~/.cursor/mcp.json`):
|
|
338
84
|
|
|
339
|
-
```
|
|
340
|
-
|
|
341
|
-
|
|
342
|
-
|
|
343
|
-
|
|
344
|
-
|
|
345
|
-
|
|
346
|
-
# 3. Copy ONE file (AirDrop / scp / iCloud / external USB)
|
|
347
|
-
cp ~/.memex/data/memex.db ~/Desktop/memex-backup.db
|
|
348
|
-
```
|
|
349
|
-
|
|
350
|
-
⚠ Copy **only `memex.db`** — do NOT copy `memex.db-wal`, `memex.db-shm` (transient, unneeded after checkpoint), and do NOT copy `~/.memex/data/ingest-state.json` (machine-specific — it contains paths and fingerprints from the old laptop).
|
|
351
|
-
|
|
352
|
-
**On the new laptop:**
|
|
353
|
-
|
|
354
|
-
```bash
|
|
355
|
-
# 1. Install memex like a first-time install
|
|
356
|
-
git clone https://github.com/parallelclaw/memex-mvp
|
|
357
|
-
cd memex-mvp && npm install
|
|
358
|
-
|
|
359
|
-
# 2. Place the DB file
|
|
360
|
-
mkdir -p ~/.memex/data
|
|
361
|
-
cp /path/to/memex-backup.db ~/.memex/data/memex.db
|
|
362
|
-
|
|
363
|
-
# 3. Wire MCP config with absolute path to node (see "Connecting to Claude Code" above)
|
|
364
|
-
|
|
365
|
-
# 4. Restart Cursor / Claude Code and call memex_overview
|
|
85
|
+
```json
|
|
86
|
+
{
|
|
87
|
+
"mcpServers": {
|
|
88
|
+
"memex": { "command": "memex" }
|
|
89
|
+
}
|
|
90
|
+
}
|
|
366
91
|
```
|
|
367
92
|
|
|
368
|
-
|
|
369
|
-
|
|
370
|
-
**What does NOT auto-transfer:**
|
|
371
|
-
- New Claude Code / Cursor sessions on the new laptop — those are new files on the new machine. Solution: run `npx memex-sync install` on the new laptop — the daemon will start catching new sessions and adding them to the same DB.
|
|
372
|
-
- `project_path` in existing rows still contains **old paths** (`/Users/oldname/...`). Memex won't break, but `memex_list_projects` will show old paths. If needed — `UPDATE conversations SET project_path = REPLACE(...)` manually.
|
|
373
|
-
|
|
374
|
-
---
|
|
375
|
-
|
|
376
|
-
## Приватность и безопасность / Privacy & Security
|
|
377
|
-
|
|
378
|
-
### По-русски
|
|
93
|
+
Restart the client. Try the prompt:
|
|
379
94
|
|
|
380
|
-
|
|
95
|
+
> *"Use memex_overview to show me what's in my AI memory."*
|
|
381
96
|
|
|
382
|
-
|
|
97
|
+
If you see a snapshot of sources and recent conversations — you're done.
|
|
383
98
|
|
|
384
|
-
|
|
385
|
-
|
|
386
|
-
📦 **Не добавляет риск — концентрирует.** Твоя AI-история **уже** на диске в plain text — Claude Code JSONL, Cursor `state.vscdb`, Cowork session files, Obsidian `.md`, Telegram local DB. Memex консолидирует их в один SQLite-файл. Те же данные, в одном месте вместо пяти. Attack surface не растёт — растёт видимость.
|
|
387
|
-
|
|
388
|
-
🛡️ **Топ-рекомендация: FileVault.** На macOS: `System Settings → Privacy & Security → FileVault → Turn On`. Шифрует весь диск AES-256 на уровне OS. Без твоего пароля диск нечитаем — закрывает ~80% реалистичных угроз (украденный ноут, кража backup, malware без root). На Linux то же делает LUKS. Сделай это **прежде** чем волноваться про app-level шифрование.
|
|
389
|
-
|
|
390
|
-
### In English
|
|
391
|
-
|
|
392
|
-
One file with all your AI conversations — sounds scarier than it is.
|
|
393
|
-
|
|
394
|
-
✅ **What memex does:** Lives only on your machine, never phones home, no API keys, no network access. OS-level file permissions — readable only by your user.
|
|
395
|
-
|
|
396
|
-
❌ **What it doesn't:** Doesn't encrypt the DB file, doesn't redact secrets you pasted into AI chats, no password on memex itself.
|
|
397
|
-
|
|
398
|
-
📦 **Doesn't add risk — concentrates it.** Your AI history is **already** on disk in plain text — Claude Code JSONL, Cursor `state.vscdb`, Cowork session files, Obsidian `.md`, Telegram local DB. Memex consolidates them into one SQLite file. Same data, one place instead of five. Attack surface doesn't grow — visibility does.
|
|
399
|
-
|
|
400
|
-
🛡️ **Top recommendation: FileVault.** On macOS: `System Settings → Privacy & Security → FileVault → Turn On`. Encrypts the entire disk with AES-256 at the OS level. Without your password, the disk is unreadable — closes ~80% of realistic threats (stolen laptop, stolen backup, non-root malware). On Linux: LUKS does the same. Do this **before** worrying about app-level encryption.
|
|
99
|
+
For 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).
|
|
401
100
|
|
|
402
101
|
---
|
|
403
102
|
|
|
404
|
-
##
|
|
405
|
-
|
|
406
|
-
1. Telegram **Desktop** (mobile не умеет export)
|
|
407
|
-
2. Чат → меню → **Export chat history**
|
|
408
|
-
3. **Format: JSON** (не HTML)
|
|
409
|
-
4. **Path:** `~/.memex/inbox/`
|
|
410
|
-
5. Готово. Memex подхватит автоматически.
|
|
411
|
-
|
|
412
|
-
---
|
|
103
|
+
## What it captures
|
|
413
104
|
|
|
414
|
-
|
|
105
|
+
| Source | How it gets in |
|
|
106
|
+
|-----------------------|----------------------------------------------------------------|
|
|
107
|
+
| Claude Code sessions | Auto: `memex-sync` watches `~/.claude/projects/` |
|
|
108
|
+
| Claude Cowork | Auto: same watcher, including all subagent transcripts |
|
|
109
|
+
| Cursor IDE chats | Auto: reads Cursor's local SQLite session store |
|
|
110
|
+
| Continue / Zed | Auto: filesystem watchers per platform |
|
|
111
|
+
| Obsidian notes | Auto: per-vault markdown watcher |
|
|
112
|
+
| Telegram exports | Manual: drop `result.json` (Telegram Desktop) into `~/.memex/inbox/` |
|
|
113
|
+
| Telegram (live) | Run [`memex-bot`](bot/README.md) — captures messages you send/forward to your private bot |
|
|
415
114
|
|
|
416
|
-
|
|
417
|
-
|
|
418
|
-
---
|
|
419
|
-
|
|
420
|
-
## Проверь что работает
|
|
421
|
-
|
|
422
|
-
В Claude Code/Cursor/Cline напиши:
|
|
423
|
-
|
|
424
|
-
```
|
|
425
|
-
Используй memex_list_sources — что у меня в локальной памяти?
|
|
426
|
-
```
|
|
427
|
-
|
|
428
|
-
Должен ответить чем-то вроде:
|
|
429
|
-
|
|
430
|
-
```
|
|
431
|
-
Total messages: 15021
|
|
432
|
-
Sources:
|
|
433
|
-
• telegram — 13640 messages, 3 chat(s)
|
|
434
|
-
• claude-code — 1381 messages, 16 chat(s)
|
|
435
|
-
```
|
|
436
|
-
|
|
437
|
-
Дальше пробуй настоящие запросы:
|
|
438
|
-
|
|
439
|
-
```
|
|
440
|
-
Помнишь как мы обсуждали бизнес-модели для арбитража?
|
|
441
|
-
Найди мою сессию про SberBusiness структуру.
|
|
442
|
-
Что было в апреле про создание YC-презентации?
|
|
443
|
-
```
|
|
444
|
-
|
|
445
|
-
Агент сам вызовет `memex_search`, отдаст реальные совпадения с conversation_id и timestamps.
|
|
115
|
+
All sources land in the same FTS5 corpus, searchable by one `memex_search` call.
|
|
446
116
|
|
|
447
117
|
---
|
|
448
118
|
|
|
449
119
|
## MCP tools
|
|
450
120
|
|
|
451
|
-
|
|
452
|
-
|
|
453
|
-
|
|
454
|
-
|
|
455
|
-
|
|
456
|
-
|
|
457
|
-
|
|
458
|
-
|
|
459
|
-
|
|
460
|
-
|
|
121
|
+
| Tool | What it does |
|
|
122
|
+
|-------------------------------|---------------------------------------------------------------------------|
|
|
123
|
+
| `memex_overview` | Corpus snapshot — sources, counts, recent chats, daemon health |
|
|
124
|
+
| `memex_search` | Full-text search with BM25 × recency boost |
|
|
125
|
+
| `memex_recent` | Most recent messages across all sources |
|
|
126
|
+
| `memex_get_conversation` | Full transcript by `conversation_id` |
|
|
127
|
+
| `memex_list_conversations` | Conversations sorted by activity, filterable by source |
|
|
128
|
+
| `memex_list_projects` | Distinct project paths captured (for the `project` filter) |
|
|
129
|
+
| `memex_archive_conversation` | Hide a chat from default listings (data preserved) |
|
|
130
|
+
| `memex_export_markdown` | Export one conversation as Markdown (for Obsidian round-trip) |
|
|
131
|
+
| `memex_list_sources` | Per-source enabled/disabled + counts |
|
|
132
|
+
| `memex_status` | Daemon health: PID, last capture, watched files |
|
|
133
|
+
| `memex_sources_status` | Which sources are captured + the exact CLI to opt out |
|
|
134
|
+
| `memex_help` | Returns the full user guide with concrete use cases |
|
|
461
135
|
|
|
462
|
-
|
|
136
|
+
Detailed search parameters (filters, sort, format) live in [HELP.md](HELP.md).
|
|
463
137
|
|
|
464
|
-
|
|
465
|
-
|
|
466
|
-
### `memex_recent(limit?, source?, include_archived?, format?)`
|
|
467
|
-
Последние N сообщений по timestamp.
|
|
468
|
-
|
|
469
|
-
### `memex_list_conversations(limit?, source?, since_ts?, include_archived?, format?)`
|
|
470
|
-
Список чатов отсортированных по последней активности (most recent first). Каждая запись — `conversation_id`, источник, заголовок, диапазон дат и кол-во сообщений. Удобно, когда хочется быстро увидеть какие у тебя вообще разговоры с конкретным ботом или внутри одного источника, прежде чем вытаскивать полный транскрипт.
|
|
471
|
-
|
|
472
|
-
Архивные чаты скрыты по дефолту, помечены 🗄️ если включены через `include_archived: true`.
|
|
473
|
-
|
|
474
|
-
### `memex_get_conversation(conversation_id, limit?, format?)`
|
|
475
|
-
Полный transcript одного чата.
|
|
138
|
+
---
|
|
476
139
|
|
|
477
|
-
|
|
478
|
-
Заархивировать (или восстановить) чат. Архивный чат остаётся в индексе и доступен для поиска через `include_archived: true`, но не засоряет дефолтную выдачу `memex_list_conversations` / `memex_search`. Передай `archive: false` чтобы расколоть.
|
|
140
|
+
## Why memex (vs. cloud memory services)
|
|
479
141
|
|
|
480
|
-
|
|
481
|
-
|
|
142
|
+
| Concern | memex | Cloud memory (Mem0 / Supermemory / …) |
|
|
143
|
+
|-------------------------------|------------------------------------|---------------------------------------|
|
|
144
|
+
| Where your data lives | Your machine, one SQLite file | Their servers |
|
|
145
|
+
| Cost per ingested turn | 0 (no LLM call on write) | $0.005+/1K tokens |
|
|
146
|
+
| Cross-AI corpus | ✅ same DB for all clients | ⚠️ depends on plugin coverage |
|
|
147
|
+
| Telegram ingestion | ✅ first-class | ❌ not supported |
|
|
148
|
+
| Verbatim storage | ✅ raw text preserved | ❌ usually fact-extracted |
|
|
149
|
+
| Survives if vendor blocks you | ✅ your DB stays on disk | ❌ data inaccessible |
|
|
150
|
+
| Offline / air-gapped | ✅ | ❌ |
|
|
151
|
+
| Trade-off | Lexical search (FTS5), not semantic | Semantic + reranker, but cloud-bound |
|
|
482
152
|
|
|
483
153
|
---
|
|
484
154
|
|
|
485
|
-
##
|
|
155
|
+
## Privacy
|
|
486
156
|
|
|
487
|
-
|
|
488
|
-
|
|
489
|
-
|
|
490
|
-
|
|
491
|
-
├── lib/parse.js ← shared dialogue parser (used by both)
|
|
492
|
-
├── package.json ← 3 dependencies (mcp-sdk, better-sqlite3, chokidar)
|
|
493
|
-
├── install.sh ← создаёт ~/.memex/, npm install, печатает config
|
|
494
|
-
└── test/parser.test.js ← unit-тесты парсера (13 кейсов)
|
|
495
|
-
|
|
496
|
-
~/.memex/
|
|
497
|
-
├── inbox/ ← drop-zone, chokidar watching
|
|
498
|
-
├── data/
|
|
499
|
-
│ ├── memex.db ← SQLite с FTS5 (3 таблицы: messages, messages_fts, conversations)
|
|
500
|
-
│ ├── memex.log ← server log
|
|
501
|
-
│ └── conversations/ ← обработанные оригиналы (telegram/, claude-code/)
|
|
502
|
-
```
|
|
157
|
+
- **Zero network egress** during normal operation. The MCP server only listens on stdio.
|
|
158
|
+
- **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).
|
|
159
|
+
- **The DB is one file** at `~/.memex/data/memex.db`. Back it up, encrypt it (FileVault is enough), `rm` it — your call.
|
|
160
|
+
- **Source opt-out per category**: `memex-sync sources <name> disable` keeps that source out of the corpus permanently.
|
|
503
161
|
|
|
504
|
-
|
|
505
|
-
|
|
506
|
-
- `messages` — `(source, conversation_id, msg_id, role, sender, text, ts, metadata)` с UNIQUE на `(source, conversation_id, msg_id)` для дедупликации
|
|
507
|
-
- `messages_fts` — FTS5 виртуальная таблица, токенизатор `unicode61 remove_diacritics` (русский + английский, case-insensitive)
|
|
508
|
-
- `conversations` — агрегаты per-чат (first_ts, last_ts, message_count)
|
|
162
|
+
See [PRIVACY section in the Russian README](README.ru.md#приватность-и-безопасность--privacy--security) for the full breakdown.
|
|
509
163
|
|
|
510
164
|
---
|
|
511
165
|
|
|
512
|
-
##
|
|
513
|
-
|
|
514
|
-
- 🟡 Поиск keyword-based — нет semantic similarity. «арбитраж» найдёт «арбитраж», но не «монетизация трафика»
|
|
515
|
-
- 🟡 Manual import (кладёшь файл в inbox) — нет автоматического pull
|
|
516
|
-
- 🟡 Single-device — нет cross-machine sync
|
|
517
|
-
- 🟡 Plaintext SQLite — нет encryption-at-rest
|
|
518
|
-
- 🟡 ID-based dedupe требует стабильного `id` у сообщений; memex-sync (и claude-backup feed-memex для совместимости) генерируют sha1-hash из `role|timestamp|text[:200]` для гарантии
|
|
166
|
+
## Cross-device
|
|
519
167
|
|
|
520
|
-
|
|
168
|
+
memex 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.
|
|
521
169
|
|
|
522
170
|
---
|
|
523
171
|
|
|
524
|
-
##
|
|
172
|
+
## Limitations (v0.5)
|
|
525
173
|
|
|
526
|
-
- **
|
|
527
|
-
- **
|
|
528
|
-
- **
|
|
529
|
-
- **
|
|
530
|
-
- **v1.0** — Personal embedding adapter, behavioral routing rules
|
|
174
|
+
- **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.
|
|
175
|
+
- **macOS-first** — daemon installer registers a LaunchAgent. Linux works as a foreground process; Windows untested.
|
|
176
|
+
- **Single user** — the Telegram bot serves exactly one Telegram user_id (you).
|
|
177
|
+
- **No webhook for the bot** — long-polling only, captures buffer ~24h server-side when laptop is offline.
|
|
531
178
|
|
|
532
179
|
---
|
|
533
180
|
|
|
534
|
-
##
|
|
181
|
+
## Resources
|
|
535
182
|
|
|
536
|
-
-
|
|
183
|
+
- 🏠 Landing: [memex.parallelclaw.ai](https://memex.parallelclaw.ai) — the AI-driven install prompt
|
|
184
|
+
- 📖 [HELP.md](HELP.md) — concrete use cases + full tool reference + troubleshooting
|
|
185
|
+
- 🤖 [bot/README.md](bot/README.md) — Telegram capture bot setup
|
|
186
|
+
- 🇷🇺 [README.ru.md](README.ru.md) — full Russian README with deeper privacy / migration sections
|
|
187
|
+
- 🐛 [Issues](https://github.com/parallelclaw/memex-mvp/issues) on GitHub
|
|
537
188
|
|
|
538
189
|
---
|
|
539
190
|
|
|
540
|
-
##
|
|
191
|
+
## License
|
|
541
192
|
|
|
542
|
-
MIT —
|
|
193
|
+
MIT — see [LICENSE](LICENSE).
|