Skip to content

Personal AI, On Personal Devices

Python

feat: add iMessage connector reading from macOS Messages database

krypticmouse506bcd88bd70
diff --git a/src/openjarvis/connectors/__init__.py b/src/openjarvis/connectors/__init__.py
index 6d9bfb53..4baaf5d9 100644
--- a/src/openjarvis/connectors/__init__.py
+++ b/src/openjarvis/connectors/__init__.py
@@ -37,3 +37,8 @@ try:
import openjarvis.connectors.gcontacts # noqa: F401
except ImportError:
pass
+
+try:
+ import openjarvis.connectors.imessage # noqa: F401
+except ImportError:
+ pass
diff --git a/src/openjarvis/connectors/imessage.py b/src/openjarvis/connectors/imessage.py
new file mode 100644
index 00000000..bc73c08a
--- /dev/null
+++ b/src/openjarvis/connectors/imessage.py
@@ -0,0 +1,286 @@
+"""iMessage connector — reads directly from the macOS Messages SQLite database.
+
+No API calls, no OAuth. The connector opens ``~/Library/Messages/chat.db``
+in read-only mode and yields one :class:`Document` per message that has
+non-NULL text.
+
+Requires **Full Disk Access** granted to the terminal / app in
+System Settings → Privacy & Security → Full Disk Access.
+
+Timestamp notes
+---------------
+The iMessage database stores timestamps as nanoseconds since the Apple
+epoch of 2001-01-01 00:00:00 UTC. Conversion formula::
+
+ dt = datetime(2001, 1, 1, tzinfo=utc) + timedelta(seconds=apple_ns / 1_000_000_000)
+"""
+
+from __future__ import annotations
+
+import sqlite3
+from datetime import datetime, timedelta, timezone
+from pathlib import Path
+from typing import Dict, Iterator, List, Optional, Tuple
+
+from openjarvis.connectors._stubs import BaseConnector, Document, SyncStatus
+from openjarvis.core.registry import ConnectorRegistry
+from openjarvis.tools._stubs import ToolSpec
+
+# ---------------------------------------------------------------------------
+# Constants
+# ---------------------------------------------------------------------------
+
+_DEFAULT_DB_PATH = Path.home() / "Library" / "Messages" / "chat.db"
+
+# Apple epoch: 2001-01-01 00:00:00 UTC
+_APPLE_EPOCH = datetime(2001, 1, 1, tzinfo=timezone.utc)
+
+
+# ---------------------------------------------------------------------------
+# Timestamp helper
+# ---------------------------------------------------------------------------
+
+
+def _apple_ts_to_datetime(apple_ns: int) -> datetime:
+ """Convert an Apple nanosecond timestamp to a UTC :class:`datetime`.
+
+ Parameters
+ ----------
+ apple_ns:
+ Nanoseconds since 2001-01-01 00:00:00 UTC.
+
+ Returns
+ -------
+ datetime
+ UTC-aware datetime.
+ """
+ seconds = apple_ns / 1_000_000_000
+ return _APPLE_EPOCH + timedelta(seconds=seconds)
+
+
+# ---------------------------------------------------------------------------
+# IMessageConnector
+# ---------------------------------------------------------------------------
+
+
[email protected]("imessage")
+class IMessageConnector(BaseConnector):
+ """Connector that reads messages from the macOS Messages SQLite database.
+
+ Parameters
+ ----------
+ db_path:
+ Path to ``chat.db``. Defaults to
+ ``~/Library/Messages/chat.db``.
+ """
+
+ connector_id = "imessage"
+ display_name = "iMessage"
+ auth_type = "local"
+
+ def __init__(self, db_path: str = "") -> None:
+ self._db_path: Path = Path(db_path) if db_path else _DEFAULT_DB_PATH
+ self._connected: bool = False
+ self._items_synced: int = 0
+ self._items_total: int = 0
+ self._last_sync: Optional[datetime] = None
+
+ # ------------------------------------------------------------------
+ # BaseConnector interface
+ # ------------------------------------------------------------------
+
+ def is_connected(self) -> bool:
+ """Return ``True`` if the chat.db file exists at the configured path."""
+ return self._db_path.exists()
+
+ def disconnect(self) -> None:
+ """Mark the connector as disconnected."""
+ self._connected = False
+
+ def sync(
+ self,
+ *,
+ since: Optional[datetime] = None,
+ cursor: Optional[str] = None, # noqa: ARG002
+ ) -> Iterator[Document]:
+ """Read messages from chat.db and yield one :class:`Document` each.
+
+ Parameters
+ ----------
+ since:
+ If provided, skip messages whose timestamp is before this
+ datetime.
+ cursor:
+ Not used for this local connector (included for API
+ compatibility).
+
+ Yields
+ ------
+ Document
+ One document per message with non-NULL text.
+ """
+ db_path = str(self._db_path)
+
+ try:
+ conn = sqlite3.connect(f"file:{db_path}?mode=ro", uri=True)
+ except sqlite3.OperationalError:
+ return
+
+ try:
+ # ------------------------------------------------------------------
+ # 1. Build handle_id → identifier map
+ # ------------------------------------------------------------------
+ handle_map: Dict[int, str] = {}
+ for row in conn.execute("SELECT ROWID, id FROM handle"):
+ handle_map[row[0]] = row[1]
+
+ # ------------------------------------------------------------------
+ # 2. Build message_id → chat_id map
+ # ------------------------------------------------------------------
+ msg_to_chat: Dict[int, int] = {}
+ for row in conn.execute(
+ "SELECT message_id, chat_id FROM chat_message_join"
+ ):
+ msg_to_chat[row[0]] = row[1]
+
+ # ------------------------------------------------------------------
+ # 3. Build chat_id → {identifier, display_name} map
+ # ------------------------------------------------------------------
+ chat_map: Dict[int, Tuple[str, str]] = {}
+ for row in conn.execute(
+ "SELECT ROWID, chat_identifier, display_name FROM chat"
+ ):
+ chat_id: int = row[0]
+ chat_identifier: str = row[1] or ""
+ display_name: str = row[2] or chat_identifier
+ chat_map[chat_id] = (chat_identifier, display_name)
+
+ # ------------------------------------------------------------------
+ # 4. Query messages with non-NULL text
+ # ------------------------------------------------------------------
+ rows = conn.execute(
+ "SELECT ROWID, text, handle_id, date, is_from_me "
+ "FROM message "
+ "WHERE text IS NOT NULL "
+ "ORDER BY date ASC"
+ ).fetchall()
+
+ self._items_total = len(rows)
+ synced = 0
+
+ for row in rows:
+ rowid: int = row[0]
+ text: str = row[1]
+ handle_id: int = row[2] or 0
+ apple_ts: int = row[3] or 0
+ is_from_me: int = row[4] or 0
+
+ # Convert timestamp
+ timestamp = _apple_ts_to_datetime(apple_ts)
+
+ # Apply since filter
+ if since is not None:
+ since_utc = since
+ if since_utc.tzinfo is None:
+ since_utc = since_utc.replace(tzinfo=timezone.utc)
+ if timestamp < since_utc:
+ continue
+
+ # Determine author
+ if is_from_me:
+ author = "me"
+ else:
+ author = handle_map.get(handle_id, "unknown")
+
+ # Determine chat name / title
+ chat_id = msg_to_chat.get(rowid)
+ if chat_id is not None and chat_id in chat_map:
+ _chat_identifier, chat_name = chat_map[chat_id]
+ else:
+ # Fall back to the handle identifier
+ chat_name = handle_map.get(handle_id, "")
+
+ doc = Document(
+ doc_id=f"imessage:{rowid}",
+ source="imessage",
+ doc_type="message",
+ content=text,
+ title=chat_name,
+ author=author,
+ timestamp=timestamp,
+ )
+ synced += 1
+ yield doc
+
+ self._items_synced = synced
+ self._last_sync = datetime.now(tz=timezone.utc)
+
+ finally:
+ conn.close()
+
+ def sync_status(self) -> SyncStatus:
+ """Return sync progress from the most recent :meth:`sync` call."""
+ return SyncStatus(
+ state="idle",
+ items_synced=self._items_synced,
+ items_total=self._items_total,
+ last_sync=self._last_sync,
+ )
+
+ # ------------------------------------------------------------------
+ # MCP tools
+ # ------------------------------------------------------------------
+
+ def mcp_tools(self) -> List[ToolSpec]:
+ """Expose two MCP tool specs for real-time iMessage queries."""
+ return [
+ ToolSpec(
+ name="imessage_search_messages",
+ description=(
+ "Search iMessage messages by keyword or contact. "
+ "Returns matching messages with sender and timestamp."
+ ),
+ parameters={
+ "type": "object",
+ "properties": {
+ "query": {
+ "type": "string",
+ "description": "Search query string",
+ },
+ "max_results": {
+ "type": "integer",
+ "description": "Maximum number of messages to return",
+ "default": 20,
+ },
+ },
+ "required": ["query"],
+ },
+ category="knowledge",
+ ),
+ ToolSpec(
+ name="imessage_get_conversation",
+ description=(
+ "Retrieve the full message history for a specific iMessage "
+ "conversation by contact phone number or email address."
+ ),
+ parameters={
+ "type": "object",
+ "properties": {
+ "contact": {
+ "type": "string",
+ "description": (
+ "Phone number or email address of the contact "
+ "(e.g. '+15550100' or '[email protected]')"
+ ),
+ },
+ "max_results": {
+ "type": "integer",
+ "description": "Maximum number of messages to return",
+ "default": 50,
+ },
+ },
+ "required": ["contact"],
+ },
+ category="knowledge",
+ ),
+ ]
diff --git a/tests/connectors/test_imessage.py b/tests/connectors/test_imessage.py
new file mode 100644
index 00000000..4b8fb687
--- /dev/null
+++ b/tests/connectors/test_imessage.py
@@ -0,0 +1,202 @@
+"""Tests for IMessageConnector — local macOS Messages database connector.
+
+All tests use a temporary SQLite database that mimics the real chat.db schema.
+No actual macOS Messages database is required.
+"""
+
+from __future__ import annotations
+
+import sqlite3
+from pathlib import Path
+from typing import List
+
+import pytest
+
+from openjarvis.connectors._stubs import Document
+from openjarvis.core.registry import ConnectorRegistry
+
+# ---------------------------------------------------------------------------
+# Helper: create a fake chat.db
+# ---------------------------------------------------------------------------
+
+
+def _create_fake_chat_db(db_path: Path) -> None:
+ """Populate a SQLite file with the iMessage chat.db schema and sample rows."""
+ conn = sqlite3.connect(str(db_path))
+ conn.executescript(
+ "CREATE TABLE handle (ROWID INTEGER PRIMARY KEY, id TEXT NOT NULL);"
+ "CREATE TABLE chat ("
+ " ROWID INTEGER PRIMARY KEY,"
+ " chat_identifier TEXT NOT NULL,"
+ " display_name TEXT"
+ ");"
+ "CREATE TABLE message ("
+ " ROWID INTEGER PRIMARY KEY,"
+ " text TEXT,"
+ " handle_id INTEGER,"
+ " date INTEGER,"
+ " is_from_me INTEGER DEFAULT 0,"
+ " cache_roomnames TEXT"
+ ");"
+ "CREATE TABLE chat_message_join ("
+ " chat_id INTEGER,"
+ " message_id INTEGER"
+ ");"
+ "INSERT INTO handle VALUES (1, '+15550100');"
+ "INSERT INTO handle VALUES (2, '[email protected]');"
+ "INSERT INTO chat VALUES (1, '+15550100', 'Alice');"
+ "INSERT INTO chat VALUES (2, 'chat123', 'Team Group');"
+ "INSERT INTO message VALUES ("
+ " 1, 'Hey, are we meeting tomorrow?',"
+ " 1, 700000000000000000, 0, NULL"
+ ");"
+ "INSERT INTO message VALUES ("
+ " 2, 'Yes at 3pm!', 1, 700000060000000000, 1, NULL"
+ ");"
+ "INSERT INTO message VALUES ("
+ " 3, 'Group message about project',"
+ " 2, 700000120000000000, 0, 'chat123'"
+ ");"
+ "INSERT INTO chat_message_join VALUES (1, 1);"
+ "INSERT INTO chat_message_join VALUES (1, 2);"
+ "INSERT INTO chat_message_join VALUES (2, 3);"
+ )
+ conn.commit()
+ conn.close()
+
+
+# ---------------------------------------------------------------------------
+# Fixtures
+# ---------------------------------------------------------------------------
+
+
+def fake_db(tmp_path: Path) -> Path:
+ """Return path to a populated fake chat.db."""
+ db_path = tmp_path / "chat.db"
+ _create_fake_chat_db(db_path)
+ return db_path
+
+
+def connector(fake_db: Path):
+ """IMessageConnector pointing at the fake DB."""
+ from openjarvis.connectors.imessage import IMessageConnector # noqa: PLC0415
+
+ return IMessageConnector(db_path=str(fake_db))
+
+
+# ---------------------------------------------------------------------------
+# Test 1 — is_connected returns True when db_path exists
+# ---------------------------------------------------------------------------
+
+
+def test_is_connected(connector) -> None:
+ """is_connected() returns True when chat.db exists at the configured path."""
+ assert connector.is_connected() is True
+
+
+# ---------------------------------------------------------------------------
+# Test 2 — is_connected returns False for a missing file
+# ---------------------------------------------------------------------------
+
+
+def test_not_connected_missing_db() -> None:
+ """is_connected() returns False when the database file does not exist."""
+ from openjarvis.connectors.imessage import IMessageConnector # noqa: PLC0415
+
+ conn = IMessageConnector(db_path="/nonexistent/path/chat.db")
+ assert conn.is_connected() is False
+
+
+# ---------------------------------------------------------------------------
+# Test 3 — sync yields all 3 messages with correct source and doc_type
+# ---------------------------------------------------------------------------
+
+
+def test_sync_yields_messages(connector) -> None:
+ """sync() yields one Document per non-NULL message (3 total)."""
+ docs: List[Document] = list(connector.sync())
+ assert len(docs) == 3
+ for doc in docs:
+ assert doc.source == "imessage"
+ assert doc.doc_type == "message"
+
+
+# ---------------------------------------------------------------------------
+# Test 4 — sync_message_content checks specific text is present
+# ---------------------------------------------------------------------------
+
+
+def test_sync_message_content(connector) -> None:
+ """sync() surfaces the exact message text in each Document's content."""
+ docs: List[Document] = list(connector.sync())
+ contents = {d.content for d in docs}
+ assert "Hey, are we meeting tomorrow?" in contents
+ assert "Yes at 3pm!" in contents
+ assert "Group message about project" in contents
+
+
+# ---------------------------------------------------------------------------
+# Test 5 — sync sets author to handle identifier for received messages
+# ---------------------------------------------------------------------------
+
+
+def test_sync_sets_author(connector) -> None:
+ """Received messages use the handle identifier; sent messages use 'me'."""
+ docs: List[Document] = list(connector.sync())
+
+ # Message 1 is received from handle +15550100
+ msg1 = next(d for d in docs if d.doc_id == "imessage:1")
+ assert msg1.author == "+15550100"
+
+ # Message 2 is sent by me
+ msg2 = next(d for d in docs if d.doc_id == "imessage:2")
+ assert msg2.author == "me"
+
+ # Message 3 is received from handle [email protected]
+ msg3 = next(d for d in docs if d.doc_id == "imessage:3")
+ assert msg3.author == "[email protected]"
+
+
+# ---------------------------------------------------------------------------
+# Test 6 — disconnect sets connected flag to False
+# ---------------------------------------------------------------------------
+
+
+def test_disconnect(connector) -> None:
+ """disconnect() marks the connector as disconnected."""
+ # Initially the DB file exists, so is_connected is True
+ assert connector.is_connected() is True
+ connector.disconnect()
+ # _connected flag is cleared; is_connected still checks file existence
+ assert connector._connected is False
+
+
+# ---------------------------------------------------------------------------
+# Test 7 — mcp_tools returns exactly 2 tool specs
+# ---------------------------------------------------------------------------
+
+
+def test_mcp_tools(connector) -> None:
+ """mcp_tools() returns exactly 2 tools with the expected names."""
+ tools = connector.mcp_tools()
+ names = {t.name for t in tools}
+ assert len(tools) == 2
+ assert "imessage_search_messages" in names
+ assert "imessage_get_conversation" in names
+
+
+# ---------------------------------------------------------------------------
+# Test 8 — ConnectorRegistry contains "imessage" after import
+# ---------------------------------------------------------------------------
+
+
+def test_registry() -> None:
+ """IMessageConnector is registered and retrievable via ConnectorRegistry."""
+ from openjarvis.connectors.imessage import IMessageConnector # noqa: PLC0415
+
+ ConnectorRegistry.register_value("imessage", IMessageConnector)
+ assert ConnectorRegistry.contains("imessage")
+ cls = ConnectorRegistry.get("imessage")
+ assert cls.connector_id == "imessage"