memcal 1.0.0__tar.gz

memcal-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Chris Cush
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

memcal-1.0.0/PKG-INFO

@@ -0,0 +1,104 @@
+Metadata-Version: 2.4
+Name: memcal
+Version: 1.0.0
+Summary: A calendar and a to-do list that live in context, fed by the streams you already get.
+Author-email: Chris Cush <chris@cuuush.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/cuuush/memcal
+Project-URL: Repository, https://github.com/cuuush/memcal
+Project-URL: Issues, https://github.com/cuuush/memcal/issues
+Project-URL: Documentation, https://cuuush.github.io/memcal/
+Keywords: mcp,calendar,memory,agents,openclaw,hermes,slack
+Classifier: Programming Language :: Python :: 3
+Classifier: Environment :: Console
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: POSIX :: Linux
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pytypedstream>=0.1
+Provides-Extra: docs
+Requires-Dist: mkdocs>=1.6; extra == "docs"
+Requires-Dist: mkdocs-material>=9.6; extra == "docs"
+Provides-Extra: slack
+Requires-Dist: slack_sdk>=3.27; extra == "slack"
+Provides-Extra: telegram
+Requires-Dist: telethon>=1.36; extra == "telegram"
+Provides-Extra: chat
+Requires-Dist: slack_sdk>=3.27; extra == "chat"
+Requires-Dist: telethon>=1.36; extra == "chat"
+Dynamic: license-file
+
+# memcal
+
+**Memory and calendar for AI agents**
+
+[![PyPI](https://img.shields.io/pypi/v/memcal)](https://pypi.org/project/memcal/)
+[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![Docs](https://img.shields.io/badge/docs-cuuush.github.io-brightgreen)](https://cuuush.github.io/memcal/)
+
+Memcal gives your agent a memory of your plans, conversations, and commitments. It brings together sources such as iMessage, email, WhatsApp, and calendars, then uses a nightly **Dream** pass to update events and other memories as things change.
+
+Ask “What's my weekend looking like?” and your agent can recall a possible dinner with a friend, a community event, or a family visit—even when those plans started in different conversations.
+
+![A vague plan becomes a confirmed event with participants](docs/assets/demo-chat.png)
+
+Memcal prepares a brief of the next 30 days so an agent can answer common questions without a separate lookup. The brief tells you if its token budget leaves events out. Events keep their history and evidence: a past appointment does not automatically mean you attended it.
+
+## Get started
+
+You'll need Python 3.11+, SQLite with FTS5, and a model backend. Codex is the default; Claude Code, Antigravity, Grok, OpenRouter, and OpenAI-compatible APIs are also supported.
+
+```bash
+pip install memcal
+memcal setup
+memcal doctor
+memcal brief
+```
+
+Setup walks you through your provider and sources. For Codex via OAuth, sign in with `codex login` first; setup lists available models without making an inference call. The default model is `gpt-6-luna` for Codex and `openai/gpt-6-luna` for OpenRouter. Your saved model choice takes precedence.
+
+Memcal is built first for **macOS**, where it can use Messages, Calendar, and launchd scheduling. iMessage reads the local Messages database by default and requires Full Disk Access for the process running Memcal. See [iMessage setup](docs/sources/imessage.md) for BlueBubbles and permission details. Email, MCP, and optional chat integrations also work on Linux; install Slack support with `pip install 'memcal[slack]'`.
+
+Memcal reads sensitive personal data and sends selected source text to your configured model provider. Read the [privacy notes](https://cuuush.github.io/memcal/privacy/) before connecting real accounts.
+
+For a checkout instead of PyPI:
+
+```bash
+git clone https://github.com/cuuush/memcal.git
+cd memcal
+./install.sh
+```
+
+See the [quickstart](https://cuuush.github.io/memcal/quickstart/) for your first ingest and nightly schedule.
+
+## Connect your agent
+
+Memcal works with any MCP client and has native integrations for [Hermes](https://cuuush.github.io/memcal/integrations/hermes/) and [OpenClaw](https://cuuush.github.io/memcal/integrations/openclaw/). To start the MCP server:
+
+```bash
+python3 -m memcal.mcp_server
+```
+
+See the [MCP guide](https://cuuush.github.io/memcal/clients/mcp/) for client configuration. Agents can also look beyond the brief with tools such as `memcal_list_month(month="2026-10")` and `memcal_list_days(when="2026-01-01", days=365)`.
+
+## Using Memcal
+
+- `memcal dream` collects and processes updates, then shows a summary. Add `--verbose` for details or `--dry-run` for a cost estimate without model calls.
+- `memcal review` shows recent changes and open questions. Answer a question using its displayed handle, for example `memcal answer Q12 "your answer"`.
+- `memcal open E42` shows a record, its changes, and cited source messages. Use `memcal activity E42` to see newer or uncited conversation traffic.
+- `memcal schedule install` installs the macOS scheduler; `memcal schedule status` checks it. Reinstall the schedule after changing runtime locations.
+- `memcal update` updates a checkout or pip installation from GitHub, upgrades dependencies, migrates the store, and refreshes the brief and installed scheduler. Local edits or unpublished commits stop a checkout update. Restart running UI and agent sessions afterward.
+
+Run `memcal setup --advanced` for model, brief, Dream, and publishing settings, or `memcal setup --section imessage` to revisit a section. See [configuration](docs/hosting/configuration.md) for provider and model options, including OpenAI-compatible endpoints.
+
+## How it works
+
+Memcal stores events, recurring series, todos, questions, and wiki entries in typed stores. It joins related information across sources, keeps older values in history, and applies updates using the time their evidence was said. The nightly Dream pass collects information, proposes and merges changes, and refreshes the brief. See [Memcal vs. retrieval](https://cuuush.github.io/memcal/architecture/memcal-vs-rag/) for the design.
+
+## Learn more
+
+- [Documentation](https://cuuush.github.io/memcal/) · [Quickstart](https://cuuush.github.io/memcal/quickstart/) · [Sources](https://cuuush.github.io/memcal/sources/)
+- [CLI](https://cuuush.github.io/memcal/clients/cli/) · [MCP](https://cuuush.github.io/memcal/clients/mcp/) · [Integrations](https://cuuush.github.io/memcal/integrations/)
+- [Contributing](CONTRIBUTING.md) · [Changelog](CHANGELOG.md)

memcal-1.0.0/README.md

@@ -0,0 +1,73 @@
+# memcal
+
+**Memory and calendar for AI agents**
+
+[![PyPI](https://img.shields.io/pypi/v/memcal)](https://pypi.org/project/memcal/)
+[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![Docs](https://img.shields.io/badge/docs-cuuush.github.io-brightgreen)](https://cuuush.github.io/memcal/)
+
+Memcal gives your agent a memory of your plans, conversations, and commitments. It brings together sources such as iMessage, email, WhatsApp, and calendars, then uses a nightly **Dream** pass to update events and other memories as things change.
+
+Ask “What's my weekend looking like?” and your agent can recall a possible dinner with a friend, a community event, or a family visit—even when those plans started in different conversations.
+
+![A vague plan becomes a confirmed event with participants](docs/assets/demo-chat.png)
+
+Memcal prepares a brief of the next 30 days so an agent can answer common questions without a separate lookup. The brief tells you if its token budget leaves events out. Events keep their history and evidence: a past appointment does not automatically mean you attended it.
+
+## Get started
+
+You'll need Python 3.11+, SQLite with FTS5, and a model backend. Codex is the default; Claude Code, Antigravity, Grok, OpenRouter, and OpenAI-compatible APIs are also supported.
+
+```bash
+pip install memcal
+memcal setup
+memcal doctor
+memcal brief
+```
+
+Setup walks you through your provider and sources. For Codex via OAuth, sign in with `codex login` first; setup lists available models without making an inference call. The default model is `gpt-6-luna` for Codex and `openai/gpt-6-luna` for OpenRouter. Your saved model choice takes precedence.
+
+Memcal is built first for **macOS**, where it can use Messages, Calendar, and launchd scheduling. iMessage reads the local Messages database by default and requires Full Disk Access for the process running Memcal. See [iMessage setup](docs/sources/imessage.md) for BlueBubbles and permission details. Email, MCP, and optional chat integrations also work on Linux; install Slack support with `pip install 'memcal[slack]'`.
+
+Memcal reads sensitive personal data and sends selected source text to your configured model provider. Read the [privacy notes](https://cuuush.github.io/memcal/privacy/) before connecting real accounts.
+
+For a checkout instead of PyPI:
+
+```bash
+git clone https://github.com/cuuush/memcal.git
+cd memcal
+./install.sh
+```
+
+See the [quickstart](https://cuuush.github.io/memcal/quickstart/) for your first ingest and nightly schedule.
+
+## Connect your agent
+
+Memcal works with any MCP client and has native integrations for [Hermes](https://cuuush.github.io/memcal/integrations/hermes/) and [OpenClaw](https://cuuush.github.io/memcal/integrations/openclaw/). To start the MCP server:
+
+```bash
+python3 -m memcal.mcp_server
+```
+
+See the [MCP guide](https://cuuush.github.io/memcal/clients/mcp/) for client configuration. Agents can also look beyond the brief with tools such as `memcal_list_month(month="2026-10")` and `memcal_list_days(when="2026-01-01", days=365)`.
+
+## Using Memcal
+
+- `memcal dream` collects and processes updates, then shows a summary. Add `--verbose` for details or `--dry-run` for a cost estimate without model calls.
+- `memcal review` shows recent changes and open questions. Answer a question using its displayed handle, for example `memcal answer Q12 "your answer"`.
+- `memcal open E42` shows a record, its changes, and cited source messages. Use `memcal activity E42` to see newer or uncited conversation traffic.
+- `memcal schedule install` installs the macOS scheduler; `memcal schedule status` checks it. Reinstall the schedule after changing runtime locations.
+- `memcal update` updates a checkout or pip installation from GitHub, upgrades dependencies, migrates the store, and refreshes the brief and installed scheduler. Local edits or unpublished commits stop a checkout update. Restart running UI and agent sessions afterward.
+
+Run `memcal setup --advanced` for model, brief, Dream, and publishing settings, or `memcal setup --section imessage` to revisit a section. See [configuration](docs/hosting/configuration.md) for provider and model options, including OpenAI-compatible endpoints.
+
+## How it works
+
+Memcal stores events, recurring series, todos, questions, and wiki entries in typed stores. It joins related information across sources, keeps older values in history, and applies updates using the time their evidence was said. The nightly Dream pass collects information, proposes and merges changes, and refreshes the brief. See [Memcal vs. retrieval](https://cuuush.github.io/memcal/architecture/memcal-vs-rag/) for the design.
+
+## Learn more
+
+- [Documentation](https://cuuush.github.io/memcal/) · [Quickstart](https://cuuush.github.io/memcal/quickstart/) · [Sources](https://cuuush.github.io/memcal/sources/)
+- [CLI](https://cuuush.github.io/memcal/clients/cli/) · [MCP](https://cuuush.github.io/memcal/clients/mcp/) · [Integrations](https://cuuush.github.io/memcal/integrations/)
+- [Contributing](CONTRIBUTING.md) · [Changelog](CHANGELOG.md)

memcal-1.0.0/memcal/__init__.py

@@ -0,0 +1,6 @@
+"""memcal — a calendar and a to-do list that live in context.
+
+Entry point: memcal.entrypoint:main.
+"""
+
+__version__ = "0.8.2"

memcal-1.0.0/memcal/__main__.py

@@ -0,0 +1,3 @@
+from .entrypoint import main
+
+raise SystemExit(main())

memcal-1.0.0/memcal/actions.py

@@ -0,0 +1,255 @@
+"""Completed typed actions for replay safety and nightly context.
+
+Each record identifies the operation, its stable target, changed fields, source message
+ids, and the state version it acted on. This lets a retry remain a no-op and prevents a
+nightly reread from duplicating or undoing a daytime correction. Surfaces pass `Origin`
+explicitly because concurrent sessions make global "latest message" state ambiguous.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import sqlite3
+from dataclasses import dataclass, field
+
+from . import db
+
+#: Recorded when a caller supplies no originating turn. The operation still happens; the
+#: limitation is written down rather than left for a reader to mistake for "no cause".
+NO_SOURCE_NOTE = "caller supplied no originating turn"
+
+
+@dataclass(frozen=True)
+class Origin:
+    """Where a typed write came from, and what evidence it considered.
+
+    `archive_ids` is authorship: the turn behind this call. `cited` is review:
+    activity lines the caller opened and is answering with. The two ride
+    together for provenance but only `cited` acknowledges reviewed
+    observations — a newer user question must never mark older unread source
+    messages as considered.
+    """
+
+    surface: str = "unknown"
+    #: Archive ids of the turn behind this call. Empty is allowed and recorded.
+    archive_ids: tuple[int, ...] = ()
+    #: Archive ids of opened evidence this write answers with. Validated and
+    #: reviewed at the write; unknown ids are dropped, never stored.
+    cited: tuple[int, ...] = ()
+    session: str = ""
+    note: str = ""
+    #: The caller's own idempotency key for this operation, when it has one. A client
+    #: retrying a call whose answer it never saw supplies the same key, and the retry
+    #: becomes a no-op instead of a second instruction.
+    op_id: str = ""
+
+    @classmethod
+    def of(cls, surface: str, archive_ids=None, *, cited=None, session: str = "",
+           note: str = "", op_id: str = "") -> "Origin":
+        ids = tuple(int(i) for i in (archive_ids or ()) if i)
+        cites = tuple(int(i) for i in (cited or ()) if i)
+        return cls(surface=surface or "unknown", archive_ids=ids, cited=cites,
+                   session=session, op_id=op_id,
+                   note=note or ("" if (ids or cites) else NO_SOURCE_NOTE))
+
+    @property
+    def sourced(self) -> bool:
+        return bool(self.archive_ids or self.cited)
+
+
+#: The default for a caller that has not been taught to supply context yet. Callers
+#: without source context must still work; this is what "and record that limitation"
+#: looks like in practice.
+UNKNOWN = Origin.of("unknown")
+
+
+@dataclass
+class Action:
+    op_id: str
+    kind: str
+    ref: str
+    verb: str
+    surface: str
+    fields: dict = field(default_factory=dict)
+    source_ids: list[int] = field(default_factory=list)
+    source_note: str = ""
+    based_on: str = ""
+    session: str = ""
+    at: str = ""
+    field_sources: dict = field(default_factory=dict)
+    context_source_ids: list[int] = field(default_factory=list)
+    outcome: dict = field(default_factory=dict)
+
+    @classmethod
+    def from_row(cls, row: sqlite3.Row) -> "Action":
+        keys = set(row.keys())
+        return cls(
+            op_id=row["op_id"], kind=row["kind"], ref=row["ref"], verb=row["verb"],
+            surface=row["surface"], fields=db.jload(row["fields"], {}),
+            source_ids=db.jload(row["source_ids"], []),
+            source_note=row["source_note"] or "", based_on=row["based_on"] or "",
+            session=row["session"] or "", at=row["at"],
+            field_sources=db.jload(row["field_sources"], {})
+            if "field_sources" in keys else {},
+            context_source_ids=db.jload(row["context_source_ids"], [])
+            if "context_source_ids" in keys else [],
+            outcome=db.jload(row["outcome"], {}) if "outcome" in keys else {})
+
+    @property
+    def changed(self) -> list[str]:
+        return sorted(self.fields)
+
+    def one_line(self) -> str:
+        """"11:04 · moved date 2026-09-18 → 2026-09-19" — enough to recognise it."""
+        parts = []
+        for name in self.changed:
+            pair = self.fields.get(name)
+            if isinstance(pair, (list, tuple)) and len(pair) == 2:
+                old, new = pair
+                parts.append(f"{name} {old or '(none)'} → {new or '(none)'}"
+                             if str(old) != str(new) else f"{name} {new}")
+            else:
+                parts.append(f"{name} {pair}")
+        detail = "; ".join(parts) if parts else "no field changed"
+        return f"{str(self.at)[11:16]} · {self.verb} · {detail}"
+
+
+def plan(*, kind: str, ref: str, verb: str, origin: Origin, request: dict,
+         at: str) -> str:
+    """Identify an operation from its request before state changes.
+
+    A caller key wins. Otherwise the digest covers the target, verb, supplied fields,
+    and source turn—not mutable before-values—so retries keep one identity. With no
+    attributable turn, the timestamp keeps identical unknown calls distinct.
+    """
+    if origin.op_id:
+        return str(origin.op_id)[:64]
+    seed = json.dumps({
+        "kind": kind, "ref": ref, "verb": verb,
+        "surface": origin.surface, "session": origin.session,
+        "sources": sorted(origin.archive_ids),
+        "cited": sorted(origin.cited),
+        "request": {k: request[k] for k in sorted(request)},
+        "at": "" if origin.sourced else at,
+    }, sort_keys=True, default=str)
+    return hashlib.sha1(seed.encode()).hexdigest()[:20]
+
+
+def seen(conn: sqlite3.Connection, identifier: str) -> bool:
+    """Has this exact operation already been carried out?
+
+    Called inside the transaction that is about to mutate, so the answer cannot go stale
+    between the check and the write.
+    """
+    if not identifier:
+        return False
+    return conn.execute("SELECT 1 FROM actions WHERE op_id = ? LIMIT 1",
+                        (identifier,)).fetchone() is not None
+
+
+def get(conn: sqlite3.Connection, op_id: str) -> Action | None:
+    """Load one completed operation by its idempotency key."""
+    if not op_id:
+        return None
+    row = conn.execute("SELECT * FROM actions WHERE op_id = ?", (op_id,)).fetchone()
+    return Action.from_row(row) if row else None
+
+
+def record(conn: sqlite3.Connection, *, kind: str, ref: str, verb: str,
+           origin: Origin = UNKNOWN, fields: dict | None = None,
+           based_on: str | None = None, at: str | None = None,
+           op_id: str = "", commit: bool = False,
+           field_sources: dict | None = None,
+           context_source_ids: list[int] | None = None,
+           outcome: dict | None = None) -> str:
+    """Write one completed operation. Returns its id; a repeat is a no-op.
+
+    `op_id` is the identity `plan()` computed before the change was made. Deliberately
+    never commits by default: the caller commits the state change and this record
+    together, or neither happens.
+    """
+    if not ref:
+        return ""
+    fields = {k: v for k, v in (fields or {}).items()}
+    stamp = at or db.now()
+    identifier = op_id or plan(kind=kind, ref=ref, verb=verb, origin=origin,
+                               request=fields, at=stamp)
+    fs = field_sources or {}
+    ctx = list(context_source_ids or [])
+    out = outcome or {}
+    conn.execute(
+        """INSERT INTO actions(op_id, kind, ref, verb, surface, session, fields,
+                               source_ids, source_note, based_on, at,
+                               field_sources, context_source_ids, outcome)
+           VALUES(?,?,?,?,?,?,?,?,?,?,?,?,?,?) ON CONFLICT(op_id) DO NOTHING""",
+        (identifier, kind, ref, verb, origin.surface, origin.session or None,
+         db.jdump(fields), db.jdump(list(origin.archive_ids)),
+         origin.note or (None if origin.sourced else NO_SOURCE_NOTE),
+         based_on or None, stamp,
+         db.jdump(fs), db.jdump(ctx), db.jdump(out)),
+    )
+    if commit:
+        conn.commit()
+    return identifier
+
+
+def for_refs(conn: sqlite3.Connection, kind: str, refs, *,
+             limit: int = 12) -> list[Action]:
+    """Completed operations against these targets, newest last."""
+    keys = [str(ref) for ref in refs if ref]
+    if not keys:
+        return []
+    holes = ",".join("?" for _ in keys)
+    rows = conn.execute(
+        f"SELECT * FROM actions WHERE kind = ? AND ref IN ({holes})"
+        f" ORDER BY at DESC, id DESC LIMIT ?", (kind, *keys, limit)).fetchall()
+    return [Action.from_row(row) for row in reversed(rows)]
+
+
+def for_archive(conn: sqlite3.Connection, archive_ids, *,
+                limit: int = 12) -> list[Action]:
+    """Operations whose originating turn includes any of these archive lines.
+
+    This is the half that makes a *statement* recognisable as already acted on, rather
+    than only a row recognisable as already touched.
+    """
+    wanted = {int(i) for i in (archive_ids or ()) if i}
+    if not wanted:
+        return []
+    out: list[Action] = []
+    for row in conn.execute(
+            "SELECT * FROM actions ORDER BY at DESC, id DESC LIMIT 400"):
+        action = Action.from_row(row)
+        if wanted & set(action.source_ids):
+            out.append(action)
+        if len(out) >= limit:
+            break
+    return list(reversed(out))
+
+
+def latest_for(conn: sqlite3.Connection, kind: str, ref: str) -> Action | None:
+    row = conn.execute(
+        "SELECT * FROM actions WHERE kind = ? AND ref = ? ORDER BY at DESC, id DESC"
+        " LIMIT 1", (kind, ref)).fetchone()
+    return Action.from_row(row) if row else None
+
+
+def render(actions: list[Action]) -> str:
+    """The block a bundle shows the model. Says what was done and what it was reading."""
+    if not actions:
+        return ""
+    lines = [
+        "ALREADY DONE FOR THIS CONVERSATION BY THE ASSISTANT'S TYPED TOOLS.",
+        "These changes are already in the store. A line here that only restates one of",
+        "them is not news: do not propose it again, and do not create a second row for",
+        "it. The rest of the message may still contain facts nothing has acted on.",
+    ]
+    for action in actions:
+        bits = [action.ref, action.one_line()]
+        if action.source_ids:
+            bits.append("from line(s) " + ", ".join(str(i) for i in action.source_ids))
+        elif action.source_note:
+            bits.append(f"({action.source_note})")
+        lines.append("  " + " | ".join(bits))
+    return "\n".join(lines)