Metadata-Version: 2.4
Name: memcal
Version: 0.8.2
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 + 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/)

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

![Vague “Maya thing” → confirmed plan + who’s in](docs/assets/demo-chat.png)

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](docs/hosting/configuration.md)
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](https://cuuush.github.io/memcal/architecture/memcal-vs-rag/))
- **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

```bash
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](docs/sources/imessage.md) 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:

```bash
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):

```bash
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](https://cuuush.github.io/memcal/privacy/) before connecting real accounts.

## MCP (any harness)

```bash
python3 -m memcal.mcp_server
```

Native plugins: [Hermes](https://cuuush.github.io/memcal/integrations/hermes/) · [OpenClaw](https://cuuush.github.io/memcal/integrations/openclaw/)

## Learn more

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

- [Quickstart](https://cuuush.github.io/memcal/quickstart/) — install, first ingest, nightly job
- [Sources](https://cuuush.github.io/memcal/sources/) — Slack, Telegram, WhatsApp, iMessage, Signal, email, calendar, …
- [CLI](https://cuuush.github.io/memcal/clients/cli/) · [MCP](https://cuuush.github.io/memcal/clients/mcp/) · [Integrations](https://cuuush.github.io/memcal/integrations/)
- [Evaluation](https://cuuush.github.io/memcal/evaluation/) — how memory quality is measured

Contributing: [CONTRIBUTING.md](CONTRIBUTING.md). Notable changes: [CHANGELOG.md](CHANGELOG.md).
