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