memex-chats 0.1.0__tar.gz

memex_chats-0.1.0/.env.example

@@ -0,0 +1,46 @@
+# Copy to .env and adjust values. .env is in .gitignore.
+
+# Embeddings backend. Default: fastembed (zero-config, ONNX model embedded,
+# downloads itself the first time). Alternative: ollama (requires a local
+# Ollama instance running).
+MEMEX_EMBED_BACKEND=fastembed
+
+# Model name. If unset, each backend uses its default:
+# - fastembed: nomic-ai/nomic-embed-text-v1.5-Q (~130 MB quantized)
+# - ollama: nomic-embed-text
+# MEMEX_EMBED_MODEL=nomic-ai/nomic-embed-text-v1.5
+
+# Only used if MEMEX_EMBED_BACKEND=ollama
+OLLAMA_HOST=http://localhost:11434
+
+# SQLite database path (default: ./data/memex.db)
+MEMEX_DB_PATH=./data/memex.db
+
+# Directory where you keep official Claude.ai exports
+MEMEX_EXPORTS_DIR=./data/exports
+
+# Approximate chunk size in tokens (default: 500)
+MEMEX_CHUNK_SIZE=500
+
+# Overlap between chunks in tokens (default: 50)
+MEMEX_CHUNK_OVERLAP=50
+
+# Log level: DEBUG, INFO, WARNING, ERROR
+MEMEX_LOG_LEVEL=INFO
+
+# On-demand auto-summaries with Claude Haiku (opt-in). Requires the extra
+# `summaries`: `uv sync --extra summaries`. When ON, summaries are generated
+# lazily by `search_chats` for top-3 results without a cached summary, in
+# parallel. Off by default to avoid surprise API calls.
+MEMEX_SUMMARY_ENABLED=false
+
+# Anthropic model for summary generation. Default: Haiku (cheap, fast).
+# MEMEX_SUMMARY_MODEL=claude-haiku-4-5-20251001
+
+# Max tokens for the generated summary. Default 200 (~3 sentences).
+# MEMEX_SUMMARY_MAX_TOKENS=200
+
+# Anthropic API key. If MEMEX_SUMMARY_ENABLED=true and this is missing or
+# invalid, the search returns the matching chats without a summary and logs
+# a warning per chat. The search itself never aborts.
+# ANTHROPIC_API_KEY=sk-ant-...

memex_chats-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,40 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v3
+        with:
+          enable-cache: true
+
+      - name: Set up Python
+        run: uv python install 3.12
+
+      - name: Install dependencies
+        run: uv sync --extra dev
+
+      - name: Lint (ruff check)
+        run: uv run ruff check src tests
+
+      - name: Format check (ruff format)
+        run: uv run ruff format --check src tests
+
+      - name: Type check (mypy)
+        run: uv run mypy src/memex/core src/memex/config.py src/memex/transports
+
+      - name: Unit tests
+        run: uv run pytest tests/unit -q

memex_chats-0.1.0/.gitignore

@@ -0,0 +1,78 @@
+# Datos personales y secretos
+# Todo lo que esté acá NUNCA debe ir al repo público
+data/
+*.zip
+*.db
+*.db-journal
+*.db-shm
+*.db-wal
+.env
+.env.*
+!.env.example
+
+# Documento de contexto interno (handoff doc, no es para usuarios)
+MEMEX.md
+
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+*.egg-info/
+*.egg
+build/
+dist/
+.eggs/
+
+# Entornos virtuales
+.venv/
+venv/
+env/
+ENV/
+
+# uv
+.uv/
+
+# Testing y coverage
+.pytest_cache/
+.coverage
+.coverage.*
+htmlcov/
+.tox/
+.nox/
+coverage.xml
+*.cover
+
+# Type checking
+.mypy_cache/
+.pyre/
+.pytype/
+.ruff_cache/
+
+# IDEs y editores
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+.DS_Store
+Thumbs.db
+
+# Logs
+*.log
+logs/
+
+# Notebooks scratch
+.ipynb_checkpoints/
+
+# Memoria local de Claude Code (si llega a aparecer en el working dir)
+.claude/
+
+# MCP config local (path absoluto, específico de tu máquina). El snippet de
+# ejemplo va en el README; cada dev crea el suyo.
+.mcp.json
+
+# Handoff doc entre sesiones de trabajo. Es contexto interno (qué estábamos
+# haciendo, qué falta, decisiones abiertas), no para usuarios del repo.
+handoff.md

memex_chats-0.1.0/.python-version

@@ -0,0 +1 @@
+3.13

memex_chats-0.1.0/CHANGELOG.md

@@ -0,0 +1,133 @@
+# Changelog
+
+All notable changes to Memex are documented here.
+
+Format based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). The project follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html). `0.1.0` is the first alpha release; before it the project lived in `0.0.x`.
+
+## [Unreleased]
+
+### Added (Phase 5 packaging, 2026-05-25)
+- `memex doctor` diagnostic command. Checks Python version, database existence + schema version, embedder instantiability, live-capture server reachability, summarizer configuration (only if enabled), registered repos count, and indexed corpus count. Reports OK / WARN / FAIL per check, exits non-zero only on FAIL. 4 new unit tests.
+- `memex install-service` cross-platform autostart dispatcher. Detects host OS and delegates: Windows runs the existing Scheduled Task installer, Linux writes a new systemd user unit (`~/.config/systemd/user/memex-serve.service`) and starts it via `systemctl --user`. macOS prints manual instructions (launchd integration deferred to 0.2.0). 6 new unit tests covering the dispatch logic with mocked `platform.system` and `subprocess.run`.
+- New `scripts/install-autostart.sh` for Linux. Subcommands `install`, `uninstall`, `status`. Resolves `uv` lazily at install time, falls back to PATH lookup if `uv` is not absolute. Auto-creates `~/.local/state/memex/` for logs.
+- `chrome-extension/WEB_STORE_CHECKLIST.md`: full Web Store submission playbook (developer account, privacy policy URL, asset sizes, listing copy, permissions justification, post-approval checklist).
+
+### Changed
+- Package renamed from `memex` to `memex-chats` for PyPI publication. Both `memex` and `memex-mcp` are already taken on PyPI by unrelated projects (the latter was claimed the same day we attempted to publish). The CLI entry points stay `memex` and `memex-mcp`, so `.mcp.json` configs do not change. `Development Status` classifier bumped from `Pre-Alpha` to `Alpha`. Added `Operating System :: OS Independent` classifier. New `[project.urls]` section with Homepage / Repository / Issues / Changelog links.
+- README quickstart restructured: "install from PyPI" is now the recommended path (option A), source install is option B. Diagnostics section added linking `memex doctor`. Autostart section unified across Windows + Linux + macOS placeholder.
+- Chrome extension manifest description translated to English (was the last Spanish string in the extension).
+
+## [0.1.0] - 2026-05-24
+
+Phase 3 closed: quality pass on retrieval. All four feature sub-tasks shipped and audited.
+
+### Added
+- Optional auto-summary generation per chat, powered by Claude Haiku via the Anthropic API. Opt-in by setting `MEMEX_SUMMARY_ENABLED=true` and `ANTHROPIC_API_KEY`. Summaries are generated lazily when `search_chats` returns a chat that does not have one cached: up to 3 in parallel per call (`ThreadPoolExecutor`), silent fail per chat if the API errors. The summary is stored in `conversations.summary` and persists, so subsequent searches hit cache and do not pay the API again.
+- `core/summaries/` module: `Summarizer` ABC, `AnthropicSummarizer` (real backend, lazy import of the SDK), `FakeSummarizer` (deterministic, used in tests), `get_default_summarizer()` factory that returns `None` when the feature flag is off.
+- `conversations.content_hash` column (SHA-256 hex of canonical text). The pipeline computes and persists it on every ingest. Lets the lazy summarizer (and future consumers) detect content changes so a stale summary can be invalidated.
+- `repo.get_conversation_text(uuid)` reconstructs the canonical message stream of a chat (same format the chunker uses); `repo.update_conversation_summary(uuid, text)` patches only the summary field without touching the rest of the row.
+- `anthropic>=0.40` as a new optional dependency: install with `uv sync --extra summaries`.
+- Additive schema migration (`_apply_additive_migrations` in `db.py`) so existing local databases gain `content_hash` without a reset.
+- `stdio.search_chats` resolves the summarizer once per process via `get_default_summarizer()` and passes it through.
+- 24 new unit tests covering `FakeSummarizer`, the factory, `AnthropicSummarizer` error paths, the lazy wire in `tools.search_chats` (no-summarizer path, generation for missing summaries, cache reuse, cap at 3, persistence to DB, per-chat silent fail), pipeline `content_hash` persistence, cached-summary preservation across same-content reingests, and the additive schema migration on a legacy database.
+
+### Changed
+- `_ingest_conversation` computes the canonical text and `content_hash` before inserting; if the chat already exists with the same hash and a cached summary, the summary is preserved across the upsert (the parser's `summary` field would otherwise overwrite a lazy-generated one).
+- `tools.get_chat` defaults lowered to fit comfortably inside the Claude Code MCP token budget: `messages_limit` 20 → 10, per-message text cap 3000 → 1500 chars. Worst-case response ~17k chars (was ~62k, which occasionally exceeded the client limit and triggered the "result saved to file" fallback). Hard max `messages_limit=100` unchanged; callers needing more detail can opt in explicitly. Docstrings updated so Claude paginates with `messages_offset=10` on long chats.
+- `ROADMAP.md` and `DEVLOG.md` translated to English (previously Spanish, kept as internal journal). README note about Spanish internal docs removed.
+
+### Added (chat ↔ repo association, Phase 3 sub-task 2)
+- New `repos` and `chat_repos` tables (many-to-many with `source ∈ {'auto', 'manual'}`, `confidence`, cascade FKs on both ends).
+- New `core/repos/` module:
+  - `keys.py`: `normalize_path`, `normalize_remote` (SCP/HTTPS git URLs), `canonical_repo_key` (prefers remote over path).
+  - `discovery.py`: `parse_repo(path)` reads `.git/config` and `pyproject.toml`/`package.json`/`Cargo.toml`; produces a `RepoInfo`. `ChatRepoAssociation` dataclass for joined rows.
+  - `matcher.py`: `match_text(text, repos, threshold)` returns `Match(repo_key, confidence)` per repo with four signals (remote URL 1.0, path 0.9, manifest name 0.8, display name 0.5; highest wins per repo).
+- Storage helpers in `core/storage/repo.py`: `insert_repo`, `get_repo`, `list_repos`, `delete_repo`, `associate_chat_repo` (refuses to overwrite `manual` with `auto`), `dissociate_chat_repo`, `list_repos_for_conversation` (joined, hydrated), `list_conversations_for_repo`.
+- Pipeline auto-scan at ingest: `_ingest_conversation` runs the matcher against all registered repos after persisting the conv and upserts `source='auto'` associations. No-op when no repos are registered.
+- CLI: new `memex repos` sub-app (`add`, `list`, `remove`, `scan`) and top-level `memex tag` / `memex untag` for manual overrides.
+- `tools.search_chats(query, ..., repo=...)` accepts a path / git remote URL / canonical key. Resolves it via `_resolve_repo_key`, then `_apply_repo_boost` lowers the distance of associated hits by `REPO_BOOST_WEIGHT (0.3) * confidence` and re-sorts. Oversamples candidates (×5) when boosting so chats just outside the top-N can surface. Unregistered repo argument short-circuits with an actionable error pointing at `memex repos add`.
+- `stdio.search_chats` MCP wrapper exposes `repo` to Claude Code; docstring instructs it to pass the cwd when working inside a repo.
+- 65 new unit tests across keys (21), discovery (11), matcher (15), storage helpers (18), pipeline auto-scan (4), CLI (15), and search boost / resolve (7).
+
+### Added (SessionStart hook + find_related, Phase 3 sub-tasks 3 and 4)
+- `memex session-context` CLI command. Auto-detects the active repo from cwd (new `find_repo_root` walks up looking for `.git`, handles both directory and gitlink-file forms used by worktrees). Resolves to a registered repo, prints a short Markdown blob with up to N associated chats (manual first, then auto by confidence). Designed to be wired into Claude Code's `SessionStart` hook in `.claude/settings.json`. Silent no-op when no `.git`, repo not registered, or no associations (diagnostics go to stderr).
+- `_resolve_repo_key` extracted from `transports/tools.py` to new `core/repos/resolve.py`. Single source of truth shared by `search_chats(repo=...)`, `find_related(repo=...)`, and the new session-context command.
+- `find_related(context, limit, repo)` MCP tool: takes free-form text and returns semantically similar chats via pure vector search. Capped at `FIND_RELATED_MAX_INPUT_CHARS=4000` chars to bound embedder latency. Same repo-boost mechanic as `search_chats`. Wired into `stdio.py` as the 4th MCP tool with docstring guiding Claude when to prefer it over `search_chats`.
+- 16 new unit tests: 5 for the session-context CLI (no-git, unregistered, no-associations, prints associated, limit respected), 4 for `find_repo_root`, 7 for `find_related` (empty context, shape, truncation, limit clamp, unknown repo, boost reorders, embedder error).
+
+## [0.0.2] - 2026-05-20
+
+Phase 2 closed. Live capture + hybrid search work end-to-end. First public-facing polish (badges, screenshot, CONTRIBUTING, CHANGELOG, CI). Windows autostart as preview of Phase 5. Closing audit applied, 3 important fixes + 4 minor fixes landed in this release.
+
+### Added
+- CI workflow on GitHub Actions (`ruff check`, `ruff format --check`, `mypy`, unit tests). Read-only permissions, 10 min job timeout.
+- `CONTRIBUTING.md` with local setup, code style, and PR workflow.
+- This `CHANGELOG.md`.
+- Badges in the README: CI status, License MIT, Python 3.12+.
+- "Session memory check" screenshot in the README, embedded as end-to-end demo of the live capture + recall flow.
+- Chrome extension icons (16/32/48/128 PNG + SVG source under `chrome-extension/icons/`). Manifest declares them both top-level (`icons`) and in `action.default_icon` so the toolbar and the extension page render the brand instead of the gray placeholder.
+- Tests for `memex serve` CLI (CliRunner mocking `uvicorn.run` and `connect_and_init`) and for ingest rollback when the embedder fails mid-batch (closes two audit follow-ups from 2026-05-19).
+- Windows autostart for the HTTP server (Phase 5 preview): `scripts/install-autostart.ps1` registers a Scheduled Task running `uv run memex serve` at log on, with `LogonType S4U` (no window, independent from the shell that triggered it) and auto-restart on failure. Manage with `-Install` / `-Uninstall` / `-Status`. Logs to `%LOCALAPPDATA%\Memex\serve.log`. The cross-platform formal version (`memex install-service` with systemd / launchd backends) stays on the Phase 5 roadmap.
+
+### Changed
+- README translated fully to English. `ROADMAP.md` and `DEVLOG.md` remain in Spanish (internal journal).
+- `ruff format` applied across `src/` and `tests/` (16 files reformatted, semantics unchanged). The check is now back in CI.
+- Comment in `transports/http_ingest.py::_get_conn` rewritten to accurately describe the threading model and the future invariant for background tasks.
+
+### Fixed
+- `scripts/_run-server.ps1`: log file no longer has mixed encoding. The previous version used `Out-File -Encoding utf8` for the banner line plus `*>> $LogFile` for the server output, but PowerShell 5.1's `*>>` defaults to UTF-16 LE, garbling the file. Now uses `2>&1 | Out-File -Encoding utf8` for consistent UTF-8.
+- `chrome-extension/src/popup.js`: replaced `innerHTML` with DOM API (`createElement` + `textContent`) when rendering recent error entries. Defense-in-depth even though the only data source is the local server.
+- `scripts/install-autostart.ps1`: `New-Item -Force -ItemType Directory` instead of `Test-Path` + `New-Item`. Consistent with the wrapper script and removes a theoretical race between check and create.
+- Removed em dashes used as connectors (project rule) in `popup.js` (`"—"` placeholder and `— ${fmtAgo()}` separator).
+
+## Phase 2 (in progress)
+
+Goal: live capture from claude.ai + hybrid search good enough that Claude Code actually finds the right chat.
+
+### Added
+- Hybrid search (`hybrid` mode) combining vector search and FTS5 BM25 via Reciprocal Rank Fusion. Default for `search_chats`. Fixes the "Amarok" case where lexical-only beats semantic-only on proper nouns.
+- `search_chats(mode=...)` parameter accepting `hybrid`, `semantic`, `lexical`.
+- `memex reindex-fts` CLI command to populate FTS5 index on databases created before hybrid landed.
+- Local HTTP ingest server (`memex serve`) on `127.0.0.1:5777` for live capture.
+- Chrome extension (MV3) that captures conversations from claude.ai and posts them to the local server.
+- `fastembed` embedder as the new zero-config default (130 MB quantized ONNX model). Ollama moved to opt-in via `MEMEX_EMBED_BACKEND=ollama` and the `[ollama]` extra.
+
+### Changed
+- `ollama` dependency moved to `[project.optional-dependencies]` under the `ollama` extra. Install with `uv pip install -e .[ollama]` if needed.
+- `starlette>=0.40` and `uvicorn>=0.30` promoted to direct dependencies (no longer relying on transitive resolution through `fastmcp`).
+- `cli/main.py` no longer hardcodes "embedder: Ollama"; it reports the active backend (`settings.embed_backend`) and the model name reported by the embedder instance.
+- Chrome extension popup readable in dark mode.
+- Chrome extension `inject.js` uses `window.location.origin` as `postMessage` target instead of `"*"`, preventing other page-world scripts on claude.ai from intercepting captured chat JSON.
+- Chrome extension `manifest.json` adds an explicit CSP (`script-src 'self'; connect-src 'self' http://127.0.0.1:5777 http://localhost:5777`).
+
+### Fixed
+- `transports/stdio.py` no longer leaks raw exception messages to MCP clients; it returns `Error interno ({Type})` and logs the detail server-side.
+- Ollama embedder catches `httpx.ConnectError`, `ConnectTimeout`, `ReadTimeout`, `RemoteProtocolError` explicitly before falling back to substring matching.
+- `_to_iso` in `storage/repo.py` uses `strftime` instead of `replace("+00:00", "Z")`; robust to non-UTC zones.
+- `tools.search_chats(mode="lexical")` raises a clear error when the query sanitizes to empty (previously returned `[]` silently).
+- Chrome extension `background.js` retries 3 times with backoff (2s, 8s) on network errors, covering the case where fastembed downloads the model on first ingest and the server takes 30-60s to respond.
+
+### Removed
+- Empty `src/memex/core/retrieval/` directory.
+- `pytest-cov` from dev dependencies (was not used in CI or docs).
+
+## Phase 1 (closed)
+
+Goal: ingestion pipeline + storage + first MCP tools working end-to-end.
+
+### Added
+- `core/ingest/` pipeline parsing the official Claude.ai export (`conversations.json`, `users/*/design_chats/*.json`, `memories.json`) into Project, Conversation, Message, Chunk models.
+- `core/storage/` over SQLite + sqlite-vec with FTS5 enabled.
+- `core/embeddings/` with Embedder ABC, Ollama implementation, and `FakeEmbedder` for tests.
+- MCP server (`memex-mcp`) over stdio with `search_chats`, `get_chat`, `list_recent_chats`.
+- CLI (`memex`) with `ingest`, `search`, `stats` commands.
+
+## Phase 0 (closed)
+
+Goal: project scaffold + decisions of record.
+
+### Added
+- Initial pyproject.toml, uv setup, package layout (`src/memex/`).
+- Pydantic settings (`config.py`).
+- Test infrastructure (pytest, asyncio mode, `not integration` marker).
+- `CLAUDE.md`, `ROADMAP.md`, `DEVLOG.md` for project context.

memex_chats-0.1.0/CLAUDE.md

@@ -0,0 +1,113 @@
+# CLAUDE.md
+
+Context and rules for any Claude Code instance working in this repo (including parallel worktrees).
+
+## Project idea in one line
+
+The context Claude.ai has should also be available to Claude Code. Everything else (storage, embeddings, MCP, capture) is plumbing to get there.
+
+Full detail in [README.md](README.md) and [ROADMAP.md](ROADMAP.md).
+
+## Working rules (apply ALWAYS)
+
+1. **Read the code before and after editing.** Before so you do not break anything, after to verify what ended up there.
+2. **Keep README, ROADMAP, and DEVLOG in sync with every relevant change.** Update them in the same iteration as the code.
+3. **Review the code you just wrote for bugs** before closing the task.
+4. **When closing each ROADMAP phase, audit the whole project** for bugs, obsolete code, and vulnerabilities. Deliver a written report.
+5. **Plan before coding.** No writing code without a clear plan.
+6. **If there are real doubts, ask.** Do not assume.
+7. **Code and plans designed to scale.** Clear separation of responsibilities (pure core, swappable transport, embedder and storage behind interfaces).
+8. **No em dashes as connectors.** Use commas, periods, parentheses. Applies to docs, commits, code, and replies to the user.
+9. **No Claude shoutouts in commits.** No `Co-Authored-By`, no AI footers. Commits signed only by the human author.
+10. **Apply these rules in every iteration.**
+
+## Stack
+
+- Python 3.12+, package manager [uv](https://docs.astral.sh/uv/).
+- [FastMCP](https://github.com/jlowin/fastmcp) for the MCP server (supports stdio and SSE/HTTP).
+- SQLite + [sqlite-vec](https://github.com/asg017/sqlite-vec) for storage and vector search.
+- [fastembed](https://github.com/qdrant/fastembed) by default (zero-config, embedded ONNX) or optional [Ollama](https://ollama.com) with `nomic-embed-text`. Backend configurable via `MEMEX_EMBED_BACKEND`.
+- `pydantic` + `pydantic-settings` for config and models.
+- `typer` + `rich` for CLI.
+- `pytest`, `ruff`, `mypy` for test/lint/typecheck.
+
+## Architecture
+
+```
+src/memex/
+├── config.py            ← settings with pydantic-settings (DONE)
+├── core/                ← pure library, no transport
+│   ├── models.py        ← Project, Conversation, Message, Chunk, SearchHit
+│   ├── storage/         ← SQLite + sqlite-vec + FTS5 (schema, db, repo)
+│   └── ingest/          ← parsers + chunker + pipeline (content_renderer, chunker, claude_export, pipeline)
+├── core/embeddings/     ← factory + interfaces
+│   ├── base.py          ← Embedder ABC + EmbedderError + l2_normalize
+│   ├── fastembed_embedder.py  ← default (ONNX, zero-config)
+│   ├── ollama.py        ← optional (extra `ollama`)
+│   ├── fake.py          ← deterministic FakeEmbedder for tests
+│   └── __init__.py      ← get_default_embedder() factory based on MEMEX_EMBED_BACKEND
+├── core/summaries/      ← LLM summarizer (Phase 3)
+│   ├── base.py          ← Summarizer ABC + SummarizerError
+│   ├── anthropic_summarizer.py  ← real backend, lazy SDK import
+│   ├── fake.py          ← deterministic FakeSummarizer for tests
+│   └── __init__.py      ← get_default_summarizer() factory, returns None if disabled
+├── transports/          ← MCP bindings + local HTTP
+│   ├── tools.py         ← pure logic of the 3 MCP tools
+│   ├── stdio.py         ← stdio MCP entrypoint with FastMCP (memex-mcp)
+│   ├── http_ingest.py   ← local HTTP server for live capture (Starlette)
+│   └── http.py          ← SSE/HTTP remote MCP (TBD, Phase 4)  ← does not exist yet
+└── cli/                 ← CLI with typer (ingest, search, stats, serve, reindex-fts)
+```
+
+**Dependency rule:** `core/` does not import from `transports/` or `cli/`. Arrows point inward.
+
+**State as of 2026-05-23 (Phase 3 in progress):**
+- Phases 0, 1, and 2 closed with audit. Phase 3 first sub-task closed: on-demand auto-summaries via Claude Haiku (opt-in, lazy at first `search_chats`, persisted).
+- `vector_search`, `text_search`, and `hybrid_search` live in `core/storage/repo.py`. The `core/retrieval/` directory was removed (it was empty); if retrieval logic grows (re-ranking, complex filters), it gets recreated with real content.
+- `transports/http.py` does not exist yet; Phase 4 adds it when the remote MCP is built. Live capture uses `transports/http_ingest.py` (a different local server, not the MCP).
+
+## Common commands
+
+```bash
+uv sync                       # install deps + create .venv
+uv sync --extra summaries     # also install anthropic SDK (for the optional summaries feature)
+uv run pytest                 # tests (-m 'not integration' to skip integration)
+uv run ruff check src tests   # lint
+uv run ruff format src tests  # format
+uv run mypy src/memex/core    # type check (strict in core)
+uv run memex --help           # CLI (ingest, search, stats, serve, reindex-fts)
+uv run memex-mcp              # stdio MCP server (for Claude Code / Desktop)
+uv run memex serve            # local HTTP server for live capture from Chrome ext
+```
+
+## Multi-Claude with git worktrees
+
+To run several Claudes in parallel on independent tasks:
+
+```bash
+git worktree add ../Memex-ingest feature/ingest
+git worktree add ../Memex-embed  feature/embeddings
+git worktree add ../Memex-store  feature/storage
+```
+
+Each worktree is a separate folder with its own branch and its own `.venv` (uv isolates on its own). They converge to the same `.git`. Each Claude works without stepping on files, and at merge time all changes land in the same repo.
+
+**Limits:** worktrees do not see each other until merge. Better to split by independent module, not by cross-cutting feature. The coordinator is the human (or a "lead" Claude on `main`).
+
+## Sensitive data
+
+Everything in `data/` is personal and NEVER goes to the repo (already excluded by `.gitignore`):
+- `data/exports/*.zip`: Claude.ai exports with real conversations.
+- `data/memex.db`: SQLite database with indexed chats.
+
+The `MEMEX.md` file is also in `.gitignore` because it is an internal context document (SyncChat handoff), not for users.
+
+## Commit conventions
+
+- Clear messages, imperative mood, English or Spanish (whichever is consistent within the message).
+- No `Co-Authored-By: Claude...`. No AI footers. No `Generated with Claude Code`.
+- One commit per logical unit of change.
+
+## Persistent memory
+
+There is project memory at `C:\Users\dioni\.claude\projects\d--Dionisio-Memex\memory\`. It contains workflow rules, user context, setup decisions. Read it at the start of each session.

memex_chats-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,83 @@
+# Contributing to Memex
+
+Thanks for taking a look. Memex is pre-alpha, runs from source, and the roadmap is driven by a single user-facing goal: give Claude Code the same context Claude.ai already has. Phases and close criteria live in [ROADMAP.md](ROADMAP.md); the project journal in [DEVLOG.md](DEVLOG.md).
+
+## Scope of contributions
+
+Welcome:
+
+- Bug reports with reproducible steps.
+- Discussion on tool API shape (`search_chats`, `get_chat`, `list_recent_chats`) and how Claude actually uses them in practice.
+- Improvements to the live capture path (Chrome extension + HTTP ingest server) for sites or flows that break.
+- Better embedders, retrievers, or chunking, with benchmarks.
+
+Out of scope for now:
+
+- Packaging for distribution (Phase 5 work, owned).
+- UI other than the Chrome extension.
+- Provider integrations beyond Claude.ai (focus first).
+
+If something is unclear, open an issue before writing code. Saves time on both sides.
+
+## Local setup
+
+Requirements: Python 3.12+ and [uv](https://docs.astral.sh/uv/).
+
+```bash
+git clone https://github.com/dioniipereyraa/memex
+cd memex
+uv sync --extra dev
+```
+
+The `dev` extra brings pytest, ruff, mypy, and `ollama` (Python client, used by the optional Ollama backend).
+
+## Running checks locally
+
+The same checks CI runs:
+
+```bash
+uv run ruff check src tests
+uv run ruff format --check src tests
+uv run mypy src/memex/core src/memex/config.py src/memex/transports
+uv run pytest tests/unit -q
+```
+
+Integration tests live under `tests/integration/` and need external services (Ollama). Run with:
+
+```bash
+uv run pytest tests/integration -q
+```
+
+Skipped by default in CI.
+
+## Code style
+
+- **No em dashes (`—`) as connectors.** Use commas, periods, parentheses. Applies to docs, commits, code, and PR descriptions.
+- **No AI footers in commits.** No `Co-Authored-By: Claude...`, no `Generated with ...`. Commits signed by the human author.
+- **Imperative mood in commit messages.** Spanish or English, pick one per message and stay consistent.
+- **Read before you edit, read after.** Verify what you wrote landed as intended.
+- **Plan before you code.** No stream-of-consciousness implementations.
+- **Architecture rule:** `core/` does not import from `transports/` or `cli/`. Dependencies point inward.
+
+## Pull request workflow
+
+1. Branch off `main`. Conventional names like `feat/...`, `fix/...`, `docs/...`, `chore/...`.
+2. Make the change, with tests when it is testable. Match existing test style (see `tests/unit/` for examples).
+3. Run all local checks (lint, format, mypy, tests). CI runs the same set; if it is green locally, it should be green there.
+4. Open a PR with a description that explains the *why*, not just the *what*. The diff already shows the what.
+5. Update `DEVLOG.md` if the change is non-trivial (new feature, behavior change, architecture decision). Skip for pure refactors or test additions.
+
+## Reporting bugs
+
+Open an issue with:
+
+- What you expected.
+- What happened instead.
+- Steps to reproduce (the smaller the better).
+- Output of `memex stats` and `uv run python -V` if relevant.
+
+If it involves the Chrome extension, include the extension version and browser version.
+
+## License
+
+By contributing, you agree your contribution is licensed under the [MIT License](LICENSE) of the project.