memcal 0.8.0__tar.gz

memcal-0.8.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-0.8.0/PKG-INFO

@@ -0,0 +1,66 @@
+Metadata-Version: 2.4
+Name: memcal
+Version: 0.8.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
+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
+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 + Calendar for AI agents**
+
+Most memory systems for agents like OpenClaw or Hermes (Mem0, Hindsight) are good at saving things like preferences and observations, but fail at personal assistant tasks, like remembering you have a dentist appointment next Friday. Memcal attempts to bridge this gap by enabling an agent to maintain its own internal calendar of your life. On top of that, a nightly fact-gathering stage will scan sources like iMessage, email, WhatsApp, iCal, and more to automatically update the agent calendar.
+
+With Memcal, you can ask an agent, “What’s my weekend looking like?” and it will remember that your friend is free for dinner Saturday night, that the nonprofit you follow is having a member day, or even that your family is coming into town...
+
+## Getting started
+
+Requires Python 3.11+, SQLite with FTS5, and one model backend (Codex by
+default; Claude Code, Antigravity, or OpenRouter also work).
+
+```bash
+git clone https://github.com/cuuush/memcal.git
+cd memcal
+./install.sh
+memcal setup
+memcal doctor
+memcal brief
+```
+
+Memcal reads sensitive personal data and sends selected source text to the
+model provider you configure — read the [privacy notes](https://cuuush.github.io/memcal/privacy/)
+before connecting real accounts.
+
+## Learn more
+
+Full guides live at **https://cuuush.github.io/memcal/**:
+
+- [Quickstart](https://cuuush.github.io/memcal/quickstart/) — install, first ingest, nightly job
+- [Sources](https://cuuush.github.io/memcal/sources/) — iMessage, WhatsApp, Slack, Telegram, Signal, email, calendar
+- [CLI](https://cuuush.github.io/memcal/clients/cli/) and [CLI reference](https://cuuush.github.io/memcal/api/cli/) — every command
+- [Integrations](https://cuuush.github.io/memcal/integrations/) — Hermes, OpenClaw, any MCP harness
+- [Hosting](https://cuuush.github.io/memcal/hosting/installation/) — configuration, scheduling, publishing
+- [Evaluation](https://cuuush.github.io/memcal/evaluation/) — how memory quality is measured
+
+Contributing: [CONTRIBUTING.md](CONTRIBUTING.md). Notable changes: [CHANGELOG.md](CHANGELOG.md).

memcal-0.8.0/README.md

@@ -0,0 +1,38 @@
+# memcal
+
+**Memory + Calendar for AI agents**
+
+Most memory systems for agents like OpenClaw or Hermes (Mem0, Hindsight) are good at saving things like preferences and observations, but fail at personal assistant tasks, like remembering you have a dentist appointment next Friday. Memcal attempts to bridge this gap by enabling an agent to maintain its own internal calendar of your life. On top of that, a nightly fact-gathering stage will scan sources like iMessage, email, WhatsApp, iCal, and more to automatically update the agent calendar.
+
+With Memcal, you can ask an agent, “What’s my weekend looking like?” and it will remember that your friend is free for dinner Saturday night, that the nonprofit you follow is having a member day, or even that your family is coming into town...
+
+## Getting started
+
+Requires Python 3.11+, SQLite with FTS5, and one model backend (Codex by
+default; Claude Code, Antigravity, or OpenRouter also work).
+
+```bash
+git clone https://github.com/cuuush/memcal.git
+cd memcal
+./install.sh
+memcal setup
+memcal doctor
+memcal brief
+```
+
+Memcal reads sensitive personal data and sends selected source text to the
+model provider you configure — read the [privacy notes](https://cuuush.github.io/memcal/privacy/)
+before connecting real accounts.
+
+## Learn more
+
+Full guides live at **https://cuuush.github.io/memcal/**:
+
+- [Quickstart](https://cuuush.github.io/memcal/quickstart/) — install, first ingest, nightly job
+- [Sources](https://cuuush.github.io/memcal/sources/) — iMessage, WhatsApp, Slack, Telegram, Signal, email, calendar
+- [CLI](https://cuuush.github.io/memcal/clients/cli/) and [CLI reference](https://cuuush.github.io/memcal/api/cli/) — every command
+- [Integrations](https://cuuush.github.io/memcal/integrations/) — Hermes, OpenClaw, any MCP harness
+- [Hosting](https://cuuush.github.io/memcal/hosting/installation/) — configuration, scheduling, publishing
+- [Evaluation](https://cuuush.github.io/memcal/evaluation/) — how memory quality is measured
+
+Contributing: [CONTRIBUTING.md](CONTRIBUTING.md). Notable changes: [CHANGELOG.md](CHANGELOG.md).

memcal-0.8.0/memcal/__init__.py

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

memcal-0.8.0/memcal/__main__.py

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

memcal-0.8.0/memcal/actions.py

@@ -0,0 +1,230 @@
+"""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 = ""
+
+    @classmethod
+    def from_row(cls, row: sqlite3.Row) -> "Action":
+        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"])
+
+    @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 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) -> 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)
+    conn.execute(
+        """INSERT INTO actions(op_id, kind, ref, verb, surface, session, fields,
+                               source_ids, source_note, based_on, at)
+           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),
+    )
+    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)