memex-mvp 0.6.1 → 0.8.1

package/HELP.md

@@ -293,6 +293,84 @@ Memex по дефолту сортирует по **релевантности**
 
 ---
 
+## 💻 Терминальный CLI (v0.7+) — когда MCP не работает
+
+Если MCP-интеграция не подцепилась к твоему агенту (или ты в агенте без MCP-поддержки, но с shell-доступом) — у memex есть **terminal-режим** на том же бинаре. Один пакет, два режима.
+
+```bash
+memex search "Postgres миграция"                  # FTS5 поиск
+memex search "Q2 deck" --chat "Memex Bot"         # фильтр по title чата
+memex search "auth" --source claude-code --limit 5 --sort date_desc
+memex search "JWT" --as-of 2026-05-01             # time-travel (v0.8.1+) — только до даты
+
+memex when "Brian Chesky"                          # «когда мы об этом говорили»
+memex when "JWT decision" --limit 5                #  → chronological list of chats, без snippets
+
+memex recent --limit 5                             # последние сообщения
+memex recent --source telegram
+
+memex list                                         # все conversations
+memex list --source web                            # только сохранённые URL'ы
+
+memex get web-1582ab51a7b7                         # полный контент conversation
+
+memex overview                                     # snapshot корпуса (+ capture streak v0.8.1+)
+memex projects                                     # уникальные project_paths
+memex help                                         # эта инструкция в терминале
+memex --help                                       # справка по командам
+memex --version
+```
+
+**Все query-команды поддерживают `--json`** для пайпов и скриптов:
+
+```bash
+memex search "TODO" --json | jq '.results[].snippet'
+memex list --source telegram --json | jq -r '.conversations[].title'
+memex get web-1582ab51a7b7 --json > backup.json
+```
+
+**БД открывается read-only** — безопасно запускать пока daemon-writer работает.
+
+**Когда использовать CLI вместо MCP:**
+
+- MCP-интеграция в твоём агенте не подключилась → `memex overview` подтвердит что сам memex здоров, проблема в MCP-config'е клиента
+- Агент без MCP-поддержки (OpenCode + Kimi, любые CLI-only агенты), но с shell-доступом
+- Shell-скрипты / автоматизация
+- Дебаг: «вижу ли я свою историю напрямую?»
+
+**`memex` (без аргументов)** — это MCP stdio-сервер. Это поведение по умолчанию для Claude Code / Cursor / Cline через их MCP-config'и. CLI-команды активируются только при наличии распознанного subcommand'a.
+
+---
+
+## 🪄 Auto-context (v0.8+) — Brian Chesky moment
+
+Magic-фича. Когда ты открываешь Claude Code в проекте, Claude **сам** инжектит 500-1500 токенов контекста про этот проект — что ты делал недавно, какие conversations касались темы. Ты ещё ничего не спросил, а AI **уже знает**.
+
+**Технически:** SessionStart hook в `~/.claude/settings.json`. При старте каждой Claude Code сессии хук вызывает `memex context` → memex выдаёт markdown summary → Claude получает его как system message _до_ твоего первого вопроса.
+
+**Установка:** во время `memex-sync install` будет промпт `[Y/n]` — соглашайся (Y по default'у). Или установи позже:
+
+```bash
+memex hook install         # добавить хук
+memex hook uninstall       # удалить (только memex-запись, другие хуки сохраняются)
+memex hook status          # узнать текущее состояние
+```
+
+**Посмотреть что будет инжектиться** (dry-run в текущей директории):
+
+```bash
+memex context              # markdown как для хука
+memex context --json       # структурированный
+memex context --no-source telegram   # исключить telegram (privacy)
+memex context --freshness-days 30    # только последние 30 дней
+```
+
+**Privacy:** хук ничего не отправляет наружу — это локальная инъекция в локальную Claude-сессию. Но в context могут попасть фрагменты из любых indexed sources (включая Telegram). Чтобы исключить — добавь `--no-source telegram` в команду хука (правится в `~/.claude/settings.json`).
+
+**Где это пока не работает:** Cursor, Cline, Continue, Zed — у них нет native SessionStart hook'а. Fallback через MCP-tool — в roadmap v0.9.0. Сейчас auto-context работает только в **Claude Code и OpenClaw**.
+
+---
+
 ## Если что-то не работает
 
 ### Поиск пустой

package/README.md

@@ -100,6 +100,52 @@ For a fully-automated install across all detected MCP clients, see [the AI-drive
 
 ---
 
+## Terminal CLI (v0.7+) — query memex without MCP
+
+The same `memex` binary that runs as an MCP server also has a terminal mode for direct queries. Useful when MCP isn't wired up, when you want to pipe results into shell scripts, or when debugging MCP-config issues:
+
+```sh
+memex search "Postgres migration"          # full-text search
+memex search "Q2 deck" --chat "Memex Bot"  # scope to one conversation by title
+memex search "JWT" --as-of 2026-05-01      # v0.8.1: time-travel — only msgs before date
+memex when "Brian Chesky"                   # v0.8.1: "when did we talk about X" — dates + chats
+memex recent --limit 5                      # last 5 messages across all sources
+memex list --source web                     # all saved URLs
+memex get web-1582ab51a7b7                  # full content of one conversation
+memex overview                              # snapshot of corpus + v0.8.1: capture streak
+memex projects                              # distinct project_paths captured
+memex help                                  # full user guide (HELP.md)
+memex --help                                # command reference
+```
+
+Every query supports `--json` for machine-readable output: `memex search foo --json | jq '.results[].snippet'`. The DB is opened **read-only** — safe to run while `memex-sync` daemon is writing.
+
+When called **without arguments** (`memex`), the binary still runs as an MCP stdio server (the way Claude Code / Cursor / Cline launch it). CLI mode and MCP mode are the same package — no extra install.
+
+---
+
+## Auto-context (v0.8+) — Claude already knows what you were doing
+
+After `memex-sync install`, you're prompted to enable **auto-context**. When yes, memex adds a SessionStart hook to `~/.claude/settings.json` so that **every time you open Claude Code in a project**, Claude gets injected with ~500-1500 tokens of relevant context — what you did recently in this project, which conversations touched it, which related topics came up. No prompts. No tool calls. Just memory.
+
+```sh
+# Adding/removing the hook outside the install flow:
+memex hook install        # add SessionStart hook (idempotent)
+memex hook uninstall      # remove only the memex entry, preserves other hooks
+memex hook status         # show current state
+
+# Inspecting what gets injected:
+memex context             # dry-run the hook output for the current dir
+memex context --pwd /path # for a different project
+memex context --no-source telegram  # exclude a source
+```
+
+The hook respects existing hooks (e.g. `gstack`, custom user hooks) — they're preserved untouched.
+
+**Currently only Claude Code has native SessionStart hooks.** For Cursor / Cline / Continue / Zed, MCP-tool-based fallback is on the v0.9.0 roadmap.
+
+---
+
 ## Save URLs into memex (v0.6+)
 
 Once memex is installed, any MCP-aware agent can also save **web pages, AI chat shares, and pasted text** into your memex memory — searchable from any other AI chat later. In Claude Code, Cursor, Cline, …:

package/README.ru.md

@@ -136,6 +136,54 @@ curl -fsSL https://raw.githubusercontent.com/parallelclaw/memex-mvp/main/skills/
 
 Полное руководство и edge cases (private Perplexity, paywall, login-walls): [HELP.md §8](HELP.md).
 
+### Терминальный CLI (v0.7+) — запросы к memex без MCP
+
+Тот же бинарь `memex`, который работает как MCP-сервер, имеет **terminal-режим** для прямых запросов. Полезно когда MCP не настроен, когда хочешь пайпить результаты в shell-скрипты, или дебажить MCP-конфиг:
+
+```bash
+memex search "Postgres миграция"            # полнотекстовый поиск
+memex search "Q2 deck" --chat "Memex Bot"   # сузить до конкретного чата по title
+memex search "JWT" --as-of 2026-05-01       # v0.8.1: time-travel — только до даты
+memex when "Brian Chesky"                    # v0.8.1: «когда мы это обсуждали» — даты + чаты
+memex recent --limit 5                       # последние 5 сообщений из всех источников
+memex list --source web                      # все сохранённые URL'ы
+memex get web-1582ab51a7b7                   # полный контент одной conversation
+memex overview                               # snapshot корпуса + v0.8.1: capture streak
+memex projects                               # уникальные project_paths
+memex help                                   # полное руководство (HELP.md)
+memex --help                                 # справка по командам
+```
+
+У каждого query-subcommand'a есть `--json` для machine-readable вывода: `memex search foo --json | jq '.results[].snippet'`. БД открывается **read-only** — безопасно запускать пока daemon пишет.
+
+При запуске **без аргументов** (`memex`) бинарь по-прежнему работает как MCP stdio server (как и вызывают его Claude Code / Cursor / Cline из своих конфигов). CLI-режим и MCP-режим — один и тот же пакет, без дополнительной установки.
+
+**Использовать CLI, когда:**
+- MCP-интеграция не подцепилась к твоему агенту → `memex overview` подтвердит что сам memex здоров
+- Агент без MCP-поддержки, но с shell-доступом
+- Хочешь пайпить результаты: `memex search foo --json | jq ...`
+- Хочешь сдампить полный transcript в stdout для context'a
+
+### Auto-context (v0.8+) — Claude уже знает что ты делал
+
+После `memex-sync install` появляется промпт про **auto-context**. Если согласишься — memex добавит SessionStart хук в `~/.claude/settings.json`. Когда ты потом открываешь Claude Code в каком-то проекте, Claude **сам подгружает 500-1500 токенов контекста** про этот проект — что ты делал недавно, какие conversations его касались, какие связанные темы всплывали. Никаких вопросов, никаких tool-call'ов, просто Claude **знает**.
+
+```bash
+# Добавить/удалить хук вне install-flow:
+memex hook install        # добавить SessionStart хук (idempotent)
+memex hook uninstall      # удалить только memex-запись, остальные хуки не трогает
+memex hook status         # показать текущее состояние
+
+# Посмотреть что будет инжектиться:
+memex context             # dry-run для текущей директории
+memex context --pwd /path # для другого проекта
+memex context --no-source telegram  # исключить источник
+```
+
+Хук **сохраняет существующие хуки** (gstack, твои кастомные) — добавляет только свою запись.
+
+**Сейчас native SessionStart есть только в Claude Code.** Для Cursor / Cline / Continue / Zed fallback через MCP-tool — в roadmap v0.9.0.
+
 ### Подключение к Claude Code
 
 Сначала возьми **два абсолютных пути** в терминале:

package/ingest.js

@@ -61,6 +61,8 @@ import {
   vaultSlug,
   shouldSkipPath,
 } from './lib/parse-obsidian.js';
+import { installHook as installSessionStartHook } from './lib/hook/install.js';
+import { createInterface } from 'node:readline';
 import {
   CONFIG_PATH,
   KNOWN_SOURCES,
@@ -137,7 +139,12 @@ if (subcommand && subcommand !== '--help' && subcommand.startsWith('-') === fals
     console.error(`usage: memex-sync [install|uninstall|status|logs|serve]`);
     process.exit(2);
   }
-  handler();
+  // Handlers may be sync (most) or async (cmdInstall after v0.8 — needs readline
+  // for the auto-context prompt). Promise.resolve() normalises both.
+  Promise.resolve(handler()).catch((e) => {
+    console.error(`error in ${subcommand}: ${e.stack || e.message}`);
+    process.exit(1);
+  });
   // CLI handlers either exit themselves or fall through to daemon mode (cmdServe)
 } else if (subcommand === '--help' || subcommand === '-h') {
   console.log(`memex-sync — auto-capture daemon for memex memory
@@ -185,7 +192,7 @@ paths:
 
 // -------------------- CLI command handlers --------------------
 
-function cmdInstall() {
+async function cmdInstall() {
   if (platform() !== 'darwin') {
     console.error('install: macOS-only for now (LaunchAgent). Linux systemd-user support pending.');
     console.error('on Linux you can run: nohup memex-sync &');
@@ -243,6 +250,18 @@ function cmdInstall() {
   console.log(`  log:   ${LOG_PATH}`);
   console.log('');
 
+  // ── Auto-context prompt (v0.8+) ─────────────────────────────────────
+  // Bundle Claude Code SessionStart hook install into the same flow
+  // the user is already running. Single [Y/n] beats a separate command
+  // they'd never remember.
+  //
+  // Honor non-interactive flags / env for CI:
+  //   --auto-context yes    explicit opt-in
+  //   --auto-context no     explicit opt-out
+  //   --yes / -y            accept all defaults (yes)
+  //   $MEMEX_AUTO_CONTEXT=yes|no   env override
+  await maybeInstallAutoContextHook();
+
   // Show what daemon will actually capture, based on current config.
   const cfg = loadConfig();
   console.log('memex-sync will capture from these sources:');
@@ -277,6 +296,97 @@ function cmdInstall() {
   process.exit(0);
 }
 
+// ──────────────────────────────────────────────────────────────────
+// Auto-context hook prompt — bundled into `memex-sync install` so the
+// user doesn't need to remember an extra `memex hook install` step.
+//
+// Decision priority:
+//   1. CLI flag --auto-context=yes|no  (explicit)
+//   2. CLI flag --yes / -y             (accept all defaults: yes)
+//   3. env MEMEX_AUTO_CONTEXT=yes|no    (for CI / scripts)
+//   4. Interactive [Y/n] prompt        (TTY only)
+//   5. Default: SKIP if no TTY (don't hang on stdin in non-TTY contexts)
+async function maybeInstallAutoContextHook() {
+  const argv = process.argv.slice(3); // drop ["node", "ingest.js", "install"]
+
+  // Parse flags
+  let explicit = null; // 'yes' | 'no' | null
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--auto-context') {
+      const v = (argv[++i] || '').toLowerCase();
+      if (v === 'yes' || v === 'y' || v === 'true') explicit = 'yes';
+      else if (v === 'no' || v === 'n' || v === 'false') explicit = 'no';
+    } else if (a === '--auto-context=yes') explicit = 'yes';
+    else if (a === '--auto-context=no') explicit = 'no';
+    else if (a === '--yes' || a === '-y') explicit = 'yes';
+  }
+
+  // Env fallback
+  if (explicit === null) {
+    const env = (process.env.MEMEX_AUTO_CONTEXT || '').toLowerCase();
+    if (env === 'yes' || env === 'y' || env === 'true' || env === '1') explicit = 'yes';
+    else if (env === 'no' || env === 'n' || env === 'false' || env === '0') explicit = 'no';
+  }
+
+  // Interactive prompt as last resort
+  if (explicit === null) {
+    if (!process.stdin.isTTY) {
+      // Non-interactive (CI, scripts, install-skill flows that don't pipe stdin):
+      // skip silently. User can run `memex hook install` later.
+      console.log('Auto-context hook: skipped (non-interactive). Enable with: memex hook install');
+      console.log('');
+      return;
+    }
+    explicit = await promptYesNo(
+      `Auto-context (Brian Chesky mode):\n` +
+      `  When you open Claude Code in a project, memex can inject 500-1500 tokens\n` +
+      `  of relevant context so Claude knows what you were doing — without you\n` +
+      `  having to ask. Adds a SessionStart hook to ~/.claude/settings.json.\n` +
+      `  Other hooks (e.g. gstack) are preserved.\n\n` +
+      `  Enable?`,
+      'yes' // default Y
+    );
+  }
+
+  if (explicit !== 'yes') {
+    console.log('Auto-context hook: skipped. Enable later with: memex hook install');
+    console.log('');
+    return;
+  }
+
+  const r = installSessionStartHook();
+  if (r.error) {
+    console.log(`Auto-context hook: ✗ ${r.error}`);
+    console.log('  (memex-sync daemon still works — only the auto-context hook failed)');
+    console.log('');
+    return;
+  }
+  if (r.alreadyPresent) {
+    console.log('Auto-context hook: already installed (no-op).');
+  } else {
+    console.log('Auto-context hook: ✓ installed.');
+    console.log(`  settings: ${r.settingsPath}`);
+    console.log(`  command:  ${r.command}`);
+    console.log('  Restart Claude Code (Cmd+Q + reopen) to activate.');
+  }
+  console.log('');
+}
+
+function promptYesNo(question, defaultAnswer) {
+  return new Promise((resolve) => {
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    const suffix = defaultAnswer === 'yes' ? ' [Y/n] ' : ' [y/N] ';
+    rl.question(question + suffix, (answer) => {
+      rl.close();
+      const v = (answer || '').trim().toLowerCase();
+      if (v === 'y' || v === 'yes') resolve('yes');
+      else if (v === 'n' || v === 'no') resolve('no');
+      else resolve(defaultAnswer); // empty enter → default
+    });
+  });
+}
+
 function cmdUninstall() {
   if (platform() !== 'darwin') {
     console.error('uninstall: macOS-only for now.');