{"id":47871406,"url":"https://github.com/zackbrooks84/continuum","last_synced_at":"2026-04-04T00:52:59.106Z","repository":{"id":346416149,"uuid":"1189868760","full_name":"zackbrooks84/continuum","owner":"zackbrooks84","description":"Async task queue + persistent memory for AI agents. Never lose context between sessions. Works with Claude Code, Remote Control, and Claude.ai web.","archived":false,"fork":false,"pushed_at":"2026-03-27T15:50:02.000Z","size":296,"stargazers_count":18,"open_issues_count":0,"forks_count":3,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-04T00:52:57.357Z","etag":null,"topics":["ai-agents","automation","claude","claude-code","context-persistence","continuity","llm","mcp","memory","python"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/zackbrooks84.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-03-23T18:43:30.000Z","updated_at":"2026-03-28T21:37:48.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/zackbrooks84/continuum","commit_stats":null,"previous_names":["zackbrooks84/continuum"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/zackbrooks84/continuum","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zackbrooks84%2Fcontinuum","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zackbrooks84%2Fcontinuum/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zackbrooks84%2Fcontinuum/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zackbrooks84%2Fcontinuum/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/zackbrooks84","download_url":"https://codeload.github.com/zackbrooks84/continuum/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zackbrooks84%2Fcontinuum/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31383635,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-03T23:20:52.058Z","status":"ssl_error","status_checked_at":"2026-04-03T23:20:51.675Z","response_time":107,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-agents","automation","claude","claude-code","context-persistence","continuity","llm","mcp","memory","python"],"created_at":"2026-04-04T00:52:58.234Z","updated_at":"2026-04-04T00:52:59.085Z","avatar_url":"https://github.com/zackbrooks84.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Continuum\n\n**Async task queue + persistent memory for AI agents.**\n\n[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://python.org)\n[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)\n[![Version](https://img.shields.io/badge/version-0.1.0-orange.svg)]()\n\n\u003e Tired of re-explaining your project every session? Continuum remembers everything, runs tasks while you sleep, and picks up exactly where you left off.\n\u003e \n\n\n---\n\n## Three Patterns: 90% of Use Cases\n\n| Pattern | When | Command |\n|---------|------|---------|\n| **Smart Resume** | Start of every session | `smart_resume(\"myapp\")` |\n| **Run + Remember** | Queue work with auto-checkpoint | `push_and_checkpoint(\"pytest\", project=\"myapp\")` |\n| **Full Automation** | Set it and forget it | `auto_mode(True, \"myapp\")` |\n\n**Lost?** Call `quickstart()` — returns a live guide from the running server.\n\n---\n\n## The Problem It Solves\n\nAlmost every new session starts cold unless some form of memory is enabled. You re-explain the project, re-describe what broke, re-list what not to try. Meanwhile, long-running tasks block your context window when they could be running in the background.\n\n**Continuum fixes both.** Persistent memory across sessions. Detached task execution with auto-checkpointing. Works with Claude Code Remote Control and Dispatch out of the box.\n\n\n---\n\n## 30-Second Flow\n\n```python\n# Session 1 — queue work and save state\npush_and_checkpoint(\"pytest tests/ -x\", project=\"myapp\", auto_checkpoint=True)\n# → task runs in background daemon\n# → output becomes structured findings automatically\n\n# Session 2 (days later) — one call reloads everything\nsmart_resume(\"myapp\")\n# → finds 3 relevant checkpoints, auto-expands to full detail\n# → {goal, status, findings, dead_ends, next_steps, decisions}\n# → pick up exactly where you left off\n```\n\n---\n\n## Install \u0026 Setup\n\n```bash\npip install continuum\n\ncontinuum setup          # create ~/.continuum, start daemon\ncontinuum status         # verify everything is running\n```\n\n**Requirements:** Python 3.11+, no cloud accounts, no API keys required.\n\n---\n\n## MCP Setup (Claude Code)\n\nAdd to your `.mcp.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"continuum\": {\n      \"type\": \"stdio\",\n      \"command\": \"uv\",\n      \"args\": [\"run\", \"--project\", \"/path/to/continuum\", \"python\", \"-m\", \"continuum.mcp_server\"]\n    }\n  }\n}\n```\n\nOr with plain Python:\n\n```json\n{\n  \"mcpServers\": {\n    \"continuum\": {\n      \"type\": \"stdio\",\n      \"command\": \"python\",\n      \"args\": [\"-m\", \"continuum.mcp_server\"]\n    }\n  }\n}\n```\n\nRestart Claude Code. All 35+ tools load automatically.\n\n---\n\n## Remote for Claude.ai Web\n\nUse the same memory and tools from **Claude.ai** via Custom Connectors — no second install, same DB.\n\n**3 steps:**\n\n```bash\n# 1. Start the remote server\ncontinuum remote start --port 8766\n\n# 2. Expose it publicly with Cloudflare Tunnel (free, no interstitial)\ncloudflared tunnel --url http://localhost:8766\n\n# 3. Add to Claude.ai → Settings → Integrations → Add custom integration\n#    URL:   https://xxxx.trycloudflare.com/mcp\n#    (leave OAuth fields blank — handled automatically)\n```\n\nThat's it. `north_star()`, `remember_me()`, `smart_resume()` — all available on Claude.ai web instantly.\n\n```bash\ncontinuum remote status   # check if running\ncontinuum remote token    # show/regenerate your bearer token\n```\n\n\u003e **Verify the connection:** `curl https://xxxx.trycloudflare.com/health` → `{\"status\":\"ok\",\"version\":\"0.1.0\"}`\n\u003e\n\u003e **Note:** The tunnel URL changes on each restart. For a stable URL, use a named Cloudflare tunnel with a fixed subdomain.\n\n---\n\n## Core Features\n\n- **Auto-Observe** — every tool call silently captured as an observation; background daemon compresses batches into checkpoints automatically. No manual `checkpoint()` required.\n- **3-Layer Memory Search** — FTS5 full-text search → timeline slice → full detail. Search first, expand only what you need. ~95% token savings vs loading full history.\n- **Smart Resume** — automatic depth selection: 1–3 hits → full detail, 4–10 → timeline + top 2, 10+ → compact summaries. One call replaces three.\n- **Project File Sync** — every checkpoint writes `MEMORY.md`, `DECISIONS.md`, `TASKS.md` to your project dir automatically. Git-friendly, diffs cleanly, human-readable.\n- **Notifications** — get a Telegram/Discord/Slack message the moment a background task completes. Works perfectly with Remote Control — push a task, walk away, get pinged.\n- **Token Guard** — `token_watch()` monitors context budget live; auto-checkpoints at 80% so you never lose state mid-session.\n- **Claude Dispatch** — queue headless `claude --print` sessions as background tasks. Claude works autonomously while you're away; output becomes a checkpoint automatically.\n- **Pattern Learning** — after 5+ similar decisions, surfaces a suggested tag and standing rule via `pattern_suggestions()`. The agent learns your habits.\n- **Cross-Agent Handoffs** — `cross_agent_handoff(project, target_agent=\"gpt\")` exports context formatted for ChatGPT, Gemini, or any other agent.\n- **Personal AI OS** — `north_star()` returns a unified \u003c500 token briefing: who you are, how Claude works with you, active projects, current state. `remember_me()` and `remember_this()` teach the system your preferences and rules — persists forever.\n- **Claude.ai Web Bridge** — remote HTTP server with bearer auth bridges your local DB to Claude.ai Custom Connectors. Same memory, same tools, both interfaces.\n\n---\n\n## MCP Tools\n\n### Task Queue\n| Tool | Description |\n|------|-------------|\n| `forge_push(command, project)` | Queue a shell command to run in the background |\n| `forge_status(task_id)` | Check task status |\n| `forge_result(task_id)` | Get full task output |\n| `forge_cancel(task_id)` | Cancel a pending task |\n| `forge_list(project, status)` | List tasks with optional filters |\n| `push_and_checkpoint(command, project)` | Run task + auto-save findings as checkpoint |\n\n### Memory \u0026 Continuity\n| Tool | Description |\n|------|-------------|\n| `smart_resume(project, query)` | **[CORE]** 3-tier retrieval with auto depth selection |\n| `checkpoint(project, ...)` | **[CORE]** Save structured project state |\n| `handoff(project)` | **[CORE]** Generate compact resume briefing (\u003c1k tokens) |\n| `remember()` | Sub-400 token briefing of all active projects |\n| `memory_search(query)` | FTS5 search across all checkpoints |\n| `memory_timeline(checkpoint_id)` | Chronological slice around a checkpoint |\n| `memory_get(ids)` | Full detail for specific checkpoint IDs |\n| `sync_files(project, output_dir)` | Write MEMORY/DECISIONS/TASKS.md to project dir |\n\n### Personal AI OS\n| Tool | Description |\n|------|-------------|\n| `north_star()` | **[CORE]** Unified \u003c500 token session briefing — who you are + how Claude works + active projects |\n| `remember_me(key, value, category)` | Store a fact about you — bio, preferences, rules, technical style |\n| `recall_me(query, category)` | Retrieve your facts via FTS search or category filter |\n| `remember_this(key, value, category)` | Store a behavioral protocol or constraint for Claude |\n| `recall_this(query)` | Retrieve Claude's protocols |\n| `forget(key, memory_type)` | Delete a memory permanently |\n\n### Automation \u0026 Extras\n| Tool | Description |\n|------|-------------|\n| `auto_mode(enabled, project)` | **[CORE]** Activate all layers at once |\n| `quickstart()` | **[CORE]** Get a live guide — call this first if lost |\n| `observe_control(action, project)` | Toggle/check auto-observe |\n| `token_watch(project, threshold)` | Monitor context budget with auto-checkpoint |\n| `notify_configure(project, ...)` | Set up Telegram/Discord/Slack/webhook alerts |\n| `notify_complete(task_id, summary)` | Fire a notification manually |\n| `export_handoff(project)` | Export handoff as portable markdown |\n| `import_web_handoff(md_string)` | Import a handoff pasted from web/Claude.ai |\n| `cross_agent_handoff(project, target)` | Format context for GPT/Gemini/generic agents |\n| `pattern_suggestions(project)` | Surface recurring decision patterns |\n\n---\n\n## CLI Cheat Sheet\n\n```bash\n# Setup\ncontinuum setup                          # init + start daemon\n\n# Task queue\ncontinuum push 'pytest tests/'           # queue a task\ncontinuum push 'npm run build' \\\n  --project myapp \\\n  --auto-checkpoint                      # auto-save findings on complete\ncontinuum status                         # dashboard view\ncontinuum list --project myapp           # filter by project\ncontinuum result \u003ctask-id\u003e               # full output\ncontinuum cancel \u003ctask-id\u003e\n\n# Checkpoints  (checkpoint and cp are identical)\ncontinuum checkpoint myapp \\\n  --task \"Fixing auth bug\" \\\n  --goal \"JWT tokens expire correctly\" \\\n  --finding \"Token refresh broken on mobile\" \\\n  --dead-end \"Tried extending TTL — breaks tests\" \\\n  --next \"Patch refresh endpoint\"\n\ncontinuum resume myapp                   # load briefing for new session\ncontinuum log myapp                      # list recent checkpoints\n\n# Automation\ncontinuum observe on myapp               # start auto-observe\ncontinuum observe status\ncontinuum sync myapp                     # write MEMORY/DECISIONS/TASKS.md\n\n# Daemon\ncontinuum daemon start\ncontinuum daemon stop\ncontinuum daemon status\n```\n\n---\n\n## Benchmarking\n\nInstall dev dependencies (including `pytest-benchmark`):\n\n```bash\npython -m pip install -e \".[dev]\" pytest-benchmark\n```\n\nRun benchmarks (saves results automatically, sorted by mean):\n\n```bash\npytest tests/test_benchmark_mcp.py --benchmark-only --benchmark-autosave --benchmark-sort=mean\n```\n\nCompare against a saved baseline:\n\n```bash\npytest tests/test_benchmark_mcp.py --benchmark-only --benchmark-compare\n```\n\nHow to read results:\n\n- **mean**: average latency across all benchmark rounds; useful for overall cost.\n- **median**: middle latency; less sensitive to occasional outliers.\n- **stddev**: variability; lower values generally indicate more stable timing.\n\n---\n\n## Architecture\n\nOne SQLite database at `~/.continuum/continuum.db`. A background daemon handles task execution, observation compression, and notification dispatch. The MCP server exposes all 35+ tools over stdio. A remote HTTP server bridges your local DB to Claude.ai Custom Connectors. No cloud, no accounts — everything stays on your machine.\n\n```\ncontinuum/\n├── models.py         # Pydantic: Task, Checkpoint, Handoff, UserMemory, AgentMemory, Decision\n├── db.py             # SQLite + FTS5 full-text search + user/agent memory tables\n├── runner.py         # Task executor with auto-checkpoint + notifications\n├── daemon.py         # Background process: task runner + observer thread\n├── observer.py       # Passive capture + rule/Claude Haiku compression\n├── handoff.py        # Compact briefing generator\n├── sync_files.py     # Renders MEMORY.md / DECISIONS.md / TASKS.md\n├── notify.py         # Telegram, Discord, Slack, webhook dispatcher\n├── remote_server.py  # HTTP remote server for Claude.ai Custom Connectors\n├── mcp_server.py     # FastMCP server — all 35+ tools\n├── ui/server.py      # Local web dashboard (continuum ui)\n└── cli.py            # Click CLI\n```\n\n---\n\n## Roadmap\n\n- [x] **Web UI** — local dashboard: `continuum ui` → opens at `http://localhost:8765`\n- [ ] **Team sync** — optional encrypted checkpoint sharing across machines\n- [ ] **Plugin hooks** — custom compression and notification handlers\n\n---\n\n## License\n\nMIT © 2026 Zack Brooks\n\n**Made for people who actually ship with AI agents.**\n\n*If you're tired of re-explaining your project every session; star this repo. You'll use it every day.*\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzackbrooks84%2Fcontinuum","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fzackbrooks84%2Fcontinuum","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzackbrooks84%2Fcontinuum/lists"}