@bcmyguest/openmem 0.0.0-stage → 0.6.3

package/docs/quickstart.md

@@ -0,0 +1,101 @@
+# Quickstart
+
+Get from zero to a running stack in one wizard run. **Choose your memory provider** in the wizard (Hindsight by default; mem0 or Cognee if you prefer) — same CLI either way. Cloning the repo is optional; **`npx @bcmyguest/openmem`** is the usual path. For why OpenMem exists (interface layer, not a memory engine), see [Concepts](concepts.md).
+
+## Before you start
+
+| Requirement | Why |
+| --- | --- |
+| Docker + Compose v2 | Runs the stack; your user must run `docker` without sudo |
+| Node.js ≥ 20.12 | CLI and setup wizard |
+| LLM for Hindsight (default provider) | lemond, Ollama, or OpenAI-compatible — wizard wires LiteLLM |
+| git, curl | Wizard preflight |
+
+Default stack is [Hindsight](hindsight.md). Other providers: wizard or `npx @bcmyguest/openmem providers` ([provider status](provider-status.md)).
+
+## 1. Run the wizard
+
+**From npm (recommended):**
+
+```sh
+npx @bcmyguest/openmem
+```
+
+**From a git checkout** (repo directory is the stack root):
+
+```sh
+git clone https://github.com/bcmyguest/openmem.git
+cd openmem
+npm install
+npx . setup
+```
+
+The wizard asks for a memory provider, provider settings, what to index, then starts Docker and runs a smoke test.
+
+Useful variants:
+
+```sh
+npx @bcmyguest/openmem setup --dry-run     # plan only, no writes
+npx @bcmyguest/openmem configure --yes       # defaults + start, no prompts
+```
+
+Wizard dry-run (what first setup plans — no writes):
+
+![Setup dry-run: npx @bcmyguest/openmem setup --dry-run](https://bcmyguest.github.io/openmem/setup-demo.gif)
+
+## 2. Confirm it is up
+
+```sh
+npx @bcmyguest/openmem doctor
+curl -fsS http://127.0.0.1:8888/health   # Hindsight default; see wizard output for other providers
+```
+
+## 3. Wire your coding agent (optional)
+
+**Session memory:** `npx @bcmyguest/openmem install-coding-agent --yes` — unified MCP **plus** session hooks for Claude Code, Codex, OpenCode, Cursor CLI (any active provider). Optional `--hindsight-plugin` adds the upstream Hindsight plugin. Not the same as `install-mcp` alone.
+
+**`install-mcp`** merges the **`openmem` unified MCP** (`memory_add`, `memory_search`, `memory_recall`, `memory_reflect`, `memory_consolidate`, `memory_forget` on whichever provider you picked) and, when NotebookLM sync is on, the **NotebookLM MCP**:
+
+```sh
+npx @bcmyguest/openmem install-mcp --yes
+npx @bcmyguest/openmem install-mcp --yes --notebooklm   # force NotebookLM entry
+```
+
+Session hooks use the in-repo shim by default; add `--hindsight-plugin` if you also want the upstream Hindsight plugin. Optional native mem0/Cognee MCP: `install-mcp --provider-only`. Full guide: [MCP setup](mcp-setup.md).
+
+Restart Cursor Agent after MCP changes. Move memories between providers with [Portable memory (PMM)](memory-portability.md) — `switch` alone does not migrate data.
+
+## Day-2
+
+```sh
+npx @bcmyguest/openmem up
+npx @bcmyguest/openmem down
+npx @bcmyguest/openmem switch mem0 --yes
+npx @bcmyguest/openmem doctor
+```
+
+| Command | Purpose |
+| --- | --- |
+| `up` / `down` | Start or stop the stack (down keeps data volumes) |
+| `switch <id> --yes` | Change provider (no memory migration) |
+| `doctor` | Validate config without the smoke test |
+
+In a checkout, use `npx .` instead of `npx @bcmyguest/openmem`.
+
+## Where files live
+
+| Install | Stack root (compose, `.env`) |
+| --- | --- |
+| `npx @bcmyguest/openmem` | `~/.local/share/personal-memory/stack` (override: `PM_STACK_ROOT`) |
+| Git checkout | The clone directory |
+
+Secrets and index config: `~/.config/hindsight/` (and optional `~/.config/personal-memory/config.toml`).
+
+## Next
+
+- [MCP setup](mcp-setup.md) — unified `memory_*`, provider-native, NotebookLM
+- [Portable memory (PMM)](memory-portability.md) — export/import
+- [Architecture](architecture.md) — data flow, indexing, MCP by provider
+- [Index sources](index-sources.md) — git, Obsidian, notes/papers/bookmarks, feed cache
+- [Install with npx](npx-install.md) — upgrades, troubleshooting
+- [Configuration file](openmem-config.md) — declarative `config.toml`

package/docs/setup-wizard.md

@@ -0,0 +1,116 @@
+# Setup wizard
+
+The wizard is a Node program (`wizard/bin/setup.mjs`). It is exposed as:
+
+| How you run it | When |
+| --- | --- |
+| `npx @bcmyguest/openmem` / `npx @bcmyguest/openmem setup` | Normal install ([Install with npx](npx-install.md)) |
+| `npx . setup` / `npm run setup` / `./setup` | Git checkout (stack root stays in the repo) |
+
+Interactive runs use [@clack/prompts](https://github.com/bombshell-dev/clack). `--yes` and `--dry-run` skip Clack.
+
+## Stack actions
+
+Before provider questions, pick what the run should do (Clack or `PM_WIZARD_ACTION`):
+
+| Action | Flag | Behavior |
+| --- | --- | --- |
+| Configure | default | Full wizard: provider, env, index sources, start stack, optional coding-agent step |
+| Start | `--up` | Requires existing `~/.config/hindsight/wizard.conf`; starts stack and validates |
+| Stop | `--down` | `docker compose down` for the project |
+
+Non-interactive shortcuts:
+
+```sh
+npx @bcmyguest/openmem configure --yes   # setup --yes
+npx @bcmyguest/openmem up                # wizard --up (after first configure)
+npx @bcmyguest/openmem down              # wizard --down
+```
+
+## Wizard phases
+
+Configure runs these steps in order (provider hooks replace or extend some steps):
+
+| Step | Title | What happens |
+| --- | --- | --- |
+| 1 | Preflight | `git`, `curl`, `docker`, Compose v2; host UID/GID; API/control-plane ports |
+| 2 | Memory provider | Hindsight, mem0, or Cognee ([Provider status](provider-status.md)) |
+| 3 | Provider config | See table below |
+| 4 | Secrets and env | Files under `~/.config/hindsight/` (mode 600); runs `scripts/setup.mjs` for stack `.env` and `compose.override.yaml` |
+| 5 | Sources to index | Writes `~/.config/hindsight/index.yml`; lists sources with a dry indexer run |
+| 6 | NotebookLM sync | Opt-in; Google login when enabled |
+| 7 | Start the stack | Build indexer image if inputs changed; health wait; smoke retain/recall (unless `--no-smoke`) |
+| 8 | Coding-agent plugin | Optional `npx` install for detected CLIs; provider-specific MCP hints |
+| 9 | Validate memory setup | Provider checks + shared validation |
+
+The last line is `wizard: changed=N` (files and containers this run touched). An unchanged re-run prints `changed=0`.
+
+## Step 3 by provider
+
+| Provider | Step 3 asks for |
+| --- | --- |
+| Hindsight | Model backend: lemond, Ollama (host or compose profile), or custom OpenAI-compatible URL; LiteLLM routes for `memory-retain`, `memory-reflect`, `memory-consolidate` |
+| mem0 | Self-hosted REST base URL and API key file path |
+| Cognee | Loopback port and `LLM_API_KEY` for graph build |
+
+Details: [Model configuration](model-configuration.md) (Hindsight), `providers/mem0/OPERATOR.md`, `providers/cognee/OPERATOR.md`.
+
+## Where configuration lives
+
+| Path | Written by | Purpose |
+| --- | --- | --- |
+| Stack root `.env`, `.build-hash`, `compose.override.yaml` | `scripts/setup.mjs` | Compose project; indexer UID; secret-path masks |
+| `~/.config/hindsight/wizard.conf` | Wizard | Provider id, backend choice, ports |
+| `~/.config/hindsight/hindsight.env`, `litellm.env` | Setup / Hindsight hooks | Hindsight + LiteLLM secrets |
+| `~/.config/hindsight/index.yml` | Wizard step 5 | Index roots, repos, vaults; optional `notes` / `papers` / `bookmarks` / `feeds` ([index-sources.md](index-sources.md)) |
+| `~/.config/hindsight/notebooklm.yml` | Wizard step 6 | NotebookLM sync toggles |
+| `~/.config/personal-memory/config.toml` | Optional; synced on configure | Declarative overrides ([Configuration file](openmem-config.md)) |
+| `~/.hindsight/coding-agent.json` | Wizard / install-mcp | **Real file on disk** — do not symlink to the repo template |
+
+### Stack root (npx installs)
+
+When the CLI is not running from a git checkout, mutable compose files live under:
+
+```text
+${PM_STACK_ROOT:-${XDG_DATA_HOME:-~/.local/share}/personal-memory/stack}
+```
+
+Wizard code and provider hooks still run from the npm package. See [Install with npx](npx-install.md#stack-root).
+
+## Wizard flags
+
+| Flag | Effect |
+| --- | --- |
+| `--yes` / `-y` | Accept defaults; no prompts |
+| `--dry-run` | Plan only; read-only checks; no writes or containers |
+| `--no-smoke` | Skip retain/recall smoke test |
+| `--rebuild` | Rebuild indexer image even if sources unchanged |
+| `--up` / `--down` | Start or stop only (see stack actions) |
+
+Environment (common):
+
+| Variable | Meaning |
+| --- | --- |
+| `MEMORY_PROVIDER` | Default provider id |
+| `PM_BACKEND` | Hindsight backend default (`lemond`, `ollama`, `custom`) |
+| `PM_PROJECT` | Docker Compose project name |
+| `PM_STACK_ROOT` / `PM_USE_CHECKOUT` | Stack root location |
+| `HINDSIGHT_PORT`, `HINDSIGHT_CP_PORT` | Host API and control-plane ports |
+
+Run `./setup --help` in a checkout for the full list.
+
+## Indexer image builds
+
+The wizard rebuilds the indexer image only when its inputs change (Dockerfile, `compose.yaml`, copied sources). The hash is stored in `.build-hash` at the stack root. If nothing changed, it uses `up -d --no-build` so containers are not recreated unnecessarily.
+
+## Related docs
+
+| Topic | Doc |
+| --- | --- |
+| npx, stack root, upgrades | [npx-install.md](npx-install.md) |
+| `config.toml` and day-2 tasks | [openmem-config.md](openmem-config.md) |
+| Manual compose without the wizard | [manual-stack-setup.md](manual-stack-setup.md) |
+| LiteLLM routes and models | [model-configuration.md](model-configuration.md) |
+| Index sources and `index.yml` | [indexing.md](indexing.md) |
+| NotebookLM sync and MCP | [notebooklm.md](notebooklm.md) |
+| Plugins and MCP install | [coding-agents.md](coding-agents.md) |

package/docs/sources-feeds.md

@@ -0,0 +1,52 @@
+# RSS and OpenAlex feeds
+
+Configure `feeds` in `index.yml`, run sync, then the indexer watches `feeds.out_dir` as kind **feed** (`feed::*` banks).
+
+```yaml
+feeds:
+  out_dir: ~/.local/share/personal-memory/feeds
+  rss:
+    - url: https://rss.arxiv.org/rss/cs.AI
+      slug: arxiv-cs-ai
+  openalex_queries:
+    - url: https://api.openalex.org/works?search=machine%20learning&per_page=25
+      slug: openalex-ml
+```
+
+```sh
+npx @bcmyguest/openmem feed-sync
+# checkout: npm run feed-sync
+```
+
+Then ensure the stack indexer is running. Each run writes markdown files under `out_dir`; the watcher indexes new/changed files.
+
+Network use: feed-sync calls public RSS/OpenAlex URLs from the host (not from CI by default).
+
+## Cron / timer (optional)
+
+Run sync on a schedule so feeds stay fresh without manual commands:
+
+```ini
+# ~/.config/systemd/user/openmem-feed-sync.timer
+[Unit]
+Description=Refresh openmem feed cache
+
+[Timer]
+OnCalendar=hourly
+Persistent=true
+
+[Install]
+WantedBy=timers.target
+```
+
+```ini
+# ~/.config/systemd/user/openmem-feed-sync.service
+[Unit]
+Description=openmem feed-sync
+
+[Service]
+Type=oneshot
+ExecStart=/usr/bin/env npx @bcmyguest/openmem feed-sync
+```
+
+Enable with `systemctl --user enable --now openmem-feed-sync.timer`.

package/docs/sources-readwise.md

@@ -0,0 +1,23 @@
+# Readwise → indexer
+
+Export highlights from [Readwise Reader](https://readwise.io/read) or the legacy export as **Markdown**.
+
+1. Export to a directory (Readwise → Export → Markdown).
+2. Add to `notes.paths` or `papers.paths` depending on how you split reading vs research:
+
+```yaml
+notes:
+  paths:
+    - ~/Readwise/Full-Sync
+```
+
+3. Re-run indexing; chunks retain with bank `notes::full-sync` (slug from folder name).
+
+Optional stable bank id:
+
+```yaml
+banks:
+  ~/Readwise/Full-Sync: readwise::full-sync
+```
+
+For automatic sync, use Readwise’s scheduled export + the same path (filesystem watcher picks up changes).

package/docs/sources-zotero.md

@@ -0,0 +1,22 @@
+# Zotero → indexer
+
+**Assumption:** use export-to-disk first; no Zotero API key in the stack yet.
+
+1. Install [Better BibTeX](https://retorque.re/zotero-better-bibtex/) (optional) for stable cite keys.
+2. Export markdown or JSON notes to a folder, e.g. `~/Zotero/export-md`.
+3. Point `papers.paths` at that folder in `~/.config/hindsight/index.yml`:
+
+```yaml
+papers:
+  paths:
+    - ~/Zotero/export-md
+```
+
+4. Restart the indexer container or run `bin/hindsight-project-index --apply --papers ~/Zotero/export-md`.
+
+Banks default to `papers::<folder-name>` unless overridden under `banks:`:
+
+```yaml
+banks:
+  ~/Zotero/export-md: papers::zotero
+```

package/glama.json

@@ -0,0 +1,4 @@
+{
+  "$schema": "https://glama.ai/mcp/schemas/server.json",
+  "maintainers": ["bcmyguest"]
+}

package/indexer/Dockerfile

@@ -0,0 +1,38 @@
+# Project indexer: one pass at startup, then re-index each source after it stops changing.
+FROM python:3.12-slim
+
+RUN apt-get update \
+    && apt-get install -y --no-install-recommends git ca-certificates \
+    && rm -rf /var/lib/apt/lists/*
+
+# Tree-sitter grammars are prefetched here, so the runtime never downloads and can run with no network and a
+# read-only $HOME. The directory is world-readable because the container runs as the host UID.
+ENV TREE_SITTER_GRAMMAR_DIR=/opt/tree-sitter-grammars
+RUN pip install --no-cache-dir watchfiles==1.3.0 pyyaml==6.0.3 tree-sitter-language-pack==1.22.1 \
+    && python3 -c "import os; from tree_sitter_language_pack import PackConfig, download, init; \
+init(PackConfig(cache_dir=os.environ['TREE_SITTER_GRAMMAR_DIR'])); \
+download(['python', 'javascript', 'typescript', 'tsx', 'go', 'rust', 'java', 'c', 'cpp', 'csharp', 'ruby', 'lua', 'bash', 'php'])" \
+    && chmod -R a+rX /opt/tree-sitter-grammars
+
+# The compose user is the host's UID/GID, which may have no passwd entry here. Trust every repository owner, since
+# the indexer only reads them and the owner is the host user.
+RUN git config --system safe.directory '*'
+
+COPY bin/hindsight-project-index /usr/local/bin/hindsight-project-index
+COPY indexer/watch.py indexer/index_config.py indexer/code_outline.py indexer/feed_sync.py /opt/indexer/
+# Memory sinks (one module per provider). A new indexer/sinks/<name>.py needs no Dockerfile edit.
+COPY indexer/sinks/ /opt/indexer/sinks/
+# Shipped default config. index_config.py finds it at ../config/index.yml relative to itself.
+COPY config/index.yml /opt/config/index.yml
+RUN chmod 0755 /usr/local/bin/hindsight-project-index /opt/indexer/watch.py \
+    && chmod -R a+rX /opt/indexer
+
+# $HOME is bind-mounted, so ignore the host's ~/.local site-packages (they would shadow the pinned packages).
+# PYTHONPATH makes index_config, code_outline and the sinks package importable from both the indexer script and
+# watch.py.
+ENV PYTHONUNBUFFERED=1 \
+    PYTHONNOUSERSITE=1 \
+    PYTHONPATH=/opt/indexer \
+    HINDSIGHT_URL=http://hindsight:8888
+
+CMD ["python3", "/opt/indexer/watch.py"]

package/indexer/code_outline.py

@@ -0,0 +1,146 @@
+"""Compact symbol outlines for source files, parsed in-process with tree-sitter (tree-sitter-language-pack)."""
+
+import os
+import re
+from pathlib import Path
+
+from tree_sitter_language_pack import PackConfig, ProcessConfig, get_parser, init, process
+
+
+SIGNATURE_LIMIT = 160
+DOC_LIMIT = 120
+MAX_OUTLINE_LINES = 150
+MAX_IMPORTS = 60
+GRAMMAR_DIR_ENV = "TREE_SITTER_GRAMMAR_DIR"
+LANGUAGE_BY_SUFFIX = {
+    ".py": "python",
+    ".js": "javascript",
+    ".jsx": "javascript",
+    ".ts": "typescript",
+    ".tsx": "tsx",
+    ".go": "go",
+    ".rs": "rust",
+    ".java": "java",
+    ".c": "c",
+    ".h": "c",
+    ".cc": "cpp",
+    ".cpp": "cpp",
+    ".hpp": "cpp",
+    ".cs": "csharp",
+    ".rb": "ruby",
+    ".lua": "lua",
+    ".sh": "bash",
+    ".php": "php",
+}
+# The pack's structure extraction does not report imports for these grammars; match their import lines instead.
+FALLBACK_IMPORTS = {
+    "c": re.compile(r"^\s*#\s*include\b"),
+    "cpp": re.compile(r"^\s*#\s*include\b"),
+    "csharp": re.compile(r"^\s*using\s+[\w.]+\s*;"),
+    "ruby": re.compile(r"^\s*require(_relative)?\b"),
+    "lua": re.compile(r"^\s*(local\s+[\w, ]+=\s*)?require\b"),
+    "php": re.compile(r"^\s*use\s+[\w\\ ,{}]+;"),
+}
+# Decorators and attributes sit above the definition; the signature is the first line after them.
+ATTRIBUTE_PREFIXES = ("@", "#[", "[")
+DOC_QUOTES = ('"""', "'''")
+COMMENT_MARKERS = re.compile(r"^\s*(///<|///|//!|//|/\*\*|/\*!|/\*|\*|#|--)\s*")
+
+_ready = False
+
+
+def language_for(path: str) -> str | None:
+    return LANGUAGE_BY_SUFFIX.get(Path(path).suffix.lower())
+
+
+def _load(language: str) -> None:
+    """Load the grammar. Raises when it is missing, so a broken image fails the sync instead of emptying code docs."""
+    global _ready
+    if not _ready:
+        init(PackConfig(cache_dir=os.environ.get(GRAMMAR_DIR_ENV) or None))
+        _ready = True
+    get_parser(language)
+
+
+def _clip(text: str, limit: int = SIGNATURE_LIMIT) -> str:
+    return text if len(text) <= limit else text[: limit - 3] + "..."
+
+
+def _one_line(text: str) -> str:
+    return " ".join(text.split())
+
+
+def _signature(item, lines: list[str]) -> str:
+    for row in range(item.span.start_line, min(item.span.end_line, len(lines) - 1) + 1):
+        text = lines[row].strip()
+        if text and not text.startswith(ATTRIBUTE_PREFIXES):
+            return _clip(text)
+    return _clip(f"{item.kind} {item.name or ''}".strip())
+
+
+def _doc(item, lines: list[str], language: str) -> str:
+    if language == "python" and item.body_span is not None:
+        # Python docstrings are the first statement of the body; the pack does not extract them.
+        for row in range(item.body_span.start_line, min(item.body_span.start_line + 2, len(lines))):
+            text = lines[row].strip()
+            if not text.startswith(DOC_QUOTES):
+                return ""
+            cleaned = text[3:].rstrip("\"'").strip()
+            if cleaned:
+                return _clip(cleaned, DOC_LIMIT)
+        return ""
+    for raw in (item.doc_comment or "").splitlines():
+        cleaned = COMMENT_MARKERS.sub("", raw).strip().rstrip("*/").strip()
+        if cleaned:
+            return _clip(cleaned, DOC_LIMIT)
+    return ""
+
+
+def _imports(result, language: str, lines: list[str]) -> list[str]:
+    found = [_clip(_one_line(item.source)) for item in result.imports]
+    if not found and language in FALLBACK_IMPORTS:
+        found = [_clip(_one_line(line)) for line in lines if FALLBACK_IMPORTS[language].match(line)]
+    return list(dict.fromkeys(item for item in found if item))[:MAX_IMPORTS]
+
+
+def _symbol_lines(items, lines: list[str], language: str, depth: int, out: list[str], rows: set[int]) -> None:
+    indent = "  " * depth
+    for item in items:
+        if len(out) >= MAX_OUTLINE_LINES:
+            return
+        # A one-line member shares its parent's line; listing that line twice adds nothing.
+        if item.span.start_line not in rows:
+            rows.add(item.span.start_line)
+            out.append(f"{indent}- L{item.span.start_line + 1} {_signature(item, lines)}")
+            doc = _doc(item, lines, language)
+            if doc:
+                out.append(f"{indent}  doc: {doc}")
+        _symbol_lines(item.children, lines, language, depth + 1, out, rows)
+
+
+def outline(path: str, data: bytes) -> str | None:
+    """Return a text outline of one source file, or None when the suffix is unsupported or the file does not parse."""
+    language = language_for(path)
+    if language is None:
+        return None
+    try:
+        source = data.decode("utf-8")
+    except UnicodeDecodeError:
+        return None
+    _load(language)
+    try:
+        result = process(source, ProcessConfig(language=language, structure=True, imports=True, exports=False))
+    except Exception:
+        return None
+    lines = source.split("\n")
+    imports = _imports(result, language, lines)
+    symbols: list[str] = []
+    _symbol_lines(result.structure, lines, language, 0, symbols, set())
+    if not symbols and not imports:
+        return None
+    body = [f"File: {path}", f"Language: {language}"]
+    if imports:
+        body += ["Imports:"] + [f"- {item}" for item in imports]
+    if symbols:
+        body += ["Symbols:"] + symbols
+    return "\n".join(body)

package/indexer/feed_sync.py

@@ -0,0 +1,107 @@
+#!/usr/bin/env python3
+"""Fetch RSS and OpenAlex query results into markdown under feeds.out_dir for the indexer."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import re
+import sys
+import urllib.parse
+import urllib.request
+import xml.etree.ElementTree as ET
+from pathlib import Path
+
+import index_config
+
+USER_AGENT = "openmem-feed-sync/1.0"
+
+
+def slugify(name: str) -> str:
+    return re.sub(r"[^a-z0-9]+", "-", name.lower()).strip("-") or "feed"
+
+
+def fetch_bytes(url: str, timeout: int = 60) -> bytes:
+    req = urllib.request.Request(url, headers={"User-Agent": USER_AGENT})
+    with urllib.request.urlopen(req, timeout=timeout) as resp:
+        return resp.read()
+
+
+def write_markdown(out_dir: Path, bank_slug: str, title: str, body: str, source_url: str) -> Path:
+    out_dir.mkdir(parents=True, exist_ok=True)
+    digest = hashlib.sha256(source_url.encode()).hexdigest()[:12]
+    safe = slugify(title)[:60] or digest
+    path = out_dir / f"{bank_slug}--{safe}--{digest}.md"
+    text = f"---\nsource_url: {source_url}\nfeed_bank: feed::{bank_slug}\n---\n\n# {title}\n\n{body.strip()}\n"
+    path.write_text(text, encoding="utf-8")
+    return path
+
+
+def sync_rss(url: str, out_dir: Path, slug: str | None = None) -> int:
+    bank_slug = slug or slugify(urllib.parse.urlparse(url).path or "rss")
+    raw = fetch_bytes(url)
+    root = ET.fromstring(raw)
+    channel = root.find("channel") or root
+    items = channel.findall("item") if channel is not None else root.findall(".//item")
+    count = 0
+    for item in items[:50]:
+        title = (item.findtext("title") or "untitled").strip()
+        link = (item.findtext("link") or "").strip()
+        desc = (item.findtext("description") or item.findtext("{http://www.w3.org/2005/Atom}summary") or "").strip()
+        desc = re.sub(r"<[^>]+>", " ", desc)
+        if not link:
+            continue
+        write_markdown(out_dir, bank_slug, title, desc or title, link)
+        count += 1
+    return count
+
+
+def sync_openalex(query_url: str, out_dir: Path, slug: str | None = None) -> int:
+    bank_slug = slug or "openalex"
+    raw = fetch_bytes(query_url)
+    data = json.loads(raw.decode())
+    results = data.get("results") or []
+    count = 0
+    for work in results[:40]:
+        title = work.get("title") or work.get("display_name") or "work"
+        wid = work.get("id") or ""
+        abstract = work.get("abstract_inverted_index")
+        body = title
+        if isinstance(abstract, dict):
+            words = sorted(abstract.items(), key=lambda kv: kv[1][0] if kv[1] else 0)
+            body = " ".join(w for w, _ in words)
+        doi = (work.get("doi") or wid) or title
+        write_markdown(out_dir, bank_slug, title, body, str(doi))
+        count += 1
+    return count
+
+
+def run(config: index_config.Config | None = None) -> int:
+    config = config or index_config.load()
+    feeds = getattr(config, "feeds_out_dir", None)
+    if feeds is None:
+        print("feeds: nothing configured (feeds.rss / feeds.openalex_queries empty)", file=sys.stderr)
+        return 0
+    out_dir = feeds
+    total = 0
+    for entry in config.feeds_rss:
+        url = entry if isinstance(entry, str) else entry.get("url", "")
+        slug = None if isinstance(entry, str) else entry.get("slug")
+        if not url:
+            continue
+        n = sync_rss(url, out_dir, slug)
+        print(f"rss {url}: {n} items -> {out_dir}")
+        total += n
+    for entry in config.feeds_openalex_queries:
+        url = entry if isinstance(entry, str) else entry.get("url", "")
+        slug = None if isinstance(entry, str) else entry.get("slug")
+        if not url:
+            continue
+        n = sync_openalex(url, out_dir, slug)
+        print(f"openalex {url}: {n} works -> {out_dir}")
+        total += n
+    return 0 if total >= 0 else 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(run())