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...

Instant answers: Memcal pre-renders a brief of your next 30 days into the prompt, so Hermes can answer without firing off a long, expensive lookup first. For a full calendar month, use memcal_list_month(month="2026-10"); for a year, use memcal_list_days(when="2026-01-01", days=365) (366 for a leap year). The brief reports when its token budget leaves events out.

The default backend is Codex with gpt-6-luna; OpenRouter uses openai/gpt-6-luna. Explicitly saved model choices still apply. See Configuration for the other backends and stage-model settings.

Under the hood

• Write-time recency — updates move old values to history; read time isn’t a relevance fight (memcal vs retrieval)
• Pre-rendered brief — the next 30 days are already in the prompt, so weekend / “is that still on?” questions answer right away without a slow tool round-trip
• Typed stores — events, series, todos, questions, wiki
• Multi-stream join — Slack, Messages, email, calendar, and agent chat resolve to one underlying thing
• Nightly dream pass — observe → gate → propose → merge → brief

Install

Requires Python 3.11+, SQLite with FTS5, and one model backend (Codex by default; Claude Code, Antigravity, Grok, OpenRouter, or an OpenAI-compatible API also work).

Quick start

pip install memcal
memcal setup
memcal doctor
memcal brief

Run memcal update to pull the latest code from GitHub. A checkout fast-forwards its Git upstream; a pip installation installs from the GitHub repository. Both upgrade dependencies, migrate the existing store, refresh its saved brief, and rebuild an installed scheduler and app wrapper. Checkout updates also repair the launcher. Local edits or unpublished commits stop the update so you can resolve them first. Restart running UI and agent sessions afterward.

Run memcal setup to choose your model provider, iMessage transport and BlueBubbles connection, and disabled sources. Other source credentials are optional. Use memcal setup --advanced for model tuning, brief, dream, and publishing settings. Enter keeps saved values; ? explains a setting and - resets it. The wizard shows a change summary before saving. Use memcal setup --section imessage (or provider, brief, collect, dream, merge, publish, credentials) to jump to one section. On macOS, iMessage reads the local Messages database by default and needs Full Disk Access for the process running Memcal. See iMessage setup to use BlueBubbles.

Dream diagnostics persist for CLI, web, and scheduled runs. Open a run in the web UI and expand Saved dream log for stage progress and crash tracebacks; model calls retain their prompts and replies. memcal trace <run> also prints saved errors. Logs live under ~/.memcal/calls/run-XXXX/dream.jsonl; a failure before the run opens is saved under calls/live/ and prints its path.

For a service with an OpenAI-compatible chat-completions endpoint, configure its base URL, model ID, and API key explicitly:

memcal setup --provider openai-compatible --model YOUR_MODEL \
  --base-url https://YOUR_HOST/v1 --api-key YOUR_KEY

MEMCAL_PROPOSE_OUTPUT_FLOOR can reserve more output tokens for models whose reasoning consumes the completion allowance. The default, 0, uses Memcal's calculated ceiling.

Memcal is built first for macOS — Messages, Calendar (EventKit), and launchd scheduling are the full product path. Connect those, then ask the agent what your week looks like.

Slack (pip install 'memcal[slack]') and MCP work on any machine if you want chat without the Apple sources.

From source (alternate):

git clone https://github.com/cuuush/memcal.git
cd memcal
./install.sh

Memcal reads sensitive personal data and sends selected source text to the model provider you configure — read the privacy notes before connecting real accounts.

MCP (any harness)

python3 -m memcal.mcp_server

Native plugins: Hermes · OpenClaw

Learn more

Full guides: https://cuuush.github.io/memcal/

• Quickstart — install, first ingest, nightly job
• Sources — Slack, Telegram, WhatsApp, iMessage, Signal, email, calendar, …
• CLI · MCP · Integrations
• Evaluation — how memory quality is measured

Contributing: CONTRIBUTING.md. Notable changes: CHANGELOG.md.