OpenPull analysis: component breakdown and improvement tracking

[dandaka]

Source

Analysis from OpenPull — an automated repo review.

Already Addressed

• Add CI — GitHub Actions workflow added (ci: add GitHub Actions workflow for tests and type checking #2)
• Telegram subprocess timeout — Fixed in fix: add timeout to Telegram Python subprocess #5
• WhatsApp auth issues — Fixed in fix: WhatsApp auth - command injection, wrong endpoint, 422 handling #1

Easy Wins (Remaining)

• Add Linux support — README and setup assumes Homebrew SQLite (macOS). The sqlite-vec dependency may already work cross-platform — verify and document Linux setup to unblock non-Mac contributors.
• WhatsApp connector docs — WhatsApp connector exists (src/connectors/whatsapp.ts, docker-compose.waha.yml) but README lacks setup docs. Write a getting-started section for WAHA.
• Telegram connector integration tests — The Python subprocess bridge (tg_sync.py) via JSONL streaming is fragile. Add integration tests or a mock-mode for CI.

Red Flags (Remaining)

• Discord selfbot risk — Discord connector uses a user token pattern (raw Authorization header, no Bot prefix). Using a user token (selfbot) violates Discord ToS and can get accounts banned. Should either switch to bot token or document the risk clearly.
• No database migration system — Schema changes will silently break existing databases for users who git pull. Need a migration strategy.
• AGPL-3.0 implications — Worth flagging in CONTRIBUTING.md or README that network-deployed forks must open-source modifications.

Code Quality Notes

Overall: good

Strengths:

• Rate-limit backoff with Retry-After headers
• Snowflake-based cursor pagination
• Contact deduplication cache
• JSONL streaming for Telegram bulk sync
• Hybrid FTS5 + vector search with RRF merging and FTS fallback
• Parameterized SQL throughout (no string interpolation)
• FTS sanitizer handles special characters correctly

Weaknesses:

• SQL queries in separate queries.ts (harder to audit)
• No migration system (see red flag above)

What Makes It Unique

Local-first + AI agent tool exposure is genuinely differentiated vs cloud-based alternatives (Rewind, Mem). The hybrid FTS5+vector search with RRF merging and graceful FTS fallback is more sophisticated than most projects in this space.