agentic-task-system

ats is an MCP server and CLI that keeps AI-agent context in the task systems you already maintain — TickTick, Taskmaster, Beads, Obsidian, Notion, GitHub, Airtable, Google, or several at once through the composite adapter. It retrieves relevant tasks, notes, decisions, and runbooks with provenance, then can write results back when the active adapter supports writes. Works with Claude Code, Claude Desktop, Cursor, and any MCP client.

Adapter, not migration. Your task app, repository, or vault remains authoritative. ATS maps that source into a common task contract; optional caches and vector indexes improve retrieval but never become a second record that people must edit. It is task-first: the task is the spine, while supporting material such as GitHub issues and Notion specs is retrieved as context behind it.

npm install -g @reneza/ats-cli @reneza/ats-adapter-ticktick
ats config use ticktick
ats auth login
ats find "deployment runbook"

Architecture and trust boundaries

ATS separates the authoritative record from the retrieval machinery around it:

AI client or operator
        |
        | local stdio, or token-gated HTTP when self-hosted
        v
ATS CLI / MCP server
        |
        +-- Core: task contract, links, lifecycle, ledger, events
        +-- Retrieval: keyword + native + optional dense branches -> RRF
        |
        v
Adapter boundary (auth, mapping, reads, patch-style writes)
        |
        +-- TickTick / Notion / GitHub / Airtable / Google
        +-- Obsidian / Taskmaster / Beads / OKF files
        |
        +-- derived retrieval state
            corpus cache + optional Qdrant/Ollama index

• The backend remains authoritative. ATS does not ask users to edit a duplicate memory database. Writes go through the active adapter, which owns backend-specific authentication, field mapping, and deep links.

• Retrieval state is derived, not canonical. Core keeps a five-minute corpus cache by default. Dense retrieval is optional: adapters can provide embeddings, and the TickTick reference adapter can use Qdrant plus Ollama. Without vectors, keyword and adapter-native branches still run.

• Credentials stay at the adapter boundary. A composite adapter delegates authentication to each child and stores no additional cross-source credential. Its children still execute inside one ATS process; this is routing separation, not process isolation. Local stdio does not expose an MCP port. The hosted blueprint adds a bearer-token gateway, private Qdrant/Ollama services, and a separate public demo backend for the optional operator deck.

• Core reports the failures it can see. Retrieval branches and top-level composite corpus failures return degraded and warnings. Known omission paths inside adapter fallbacks are called out under Tradeoffs and limits.

• State changes are traceable. Results carry source provenance; find --explain exposes RRF contributions; writes use patch semantics, and supported writes can retain before-images for undo.

The corpus cache can contain full task records; the query log contains search text; the action ledger can contain write before-images; and Qdrant payloads can contain task text and metadata in addition to embeddings. ATS does not apply application-level encryption or runtime redaction to these copies. Scope host access, backups, retention, and deployment to the sensitivity of the underlying task systems. See retrieval, state integrity, and the deployment guide for the exact behavior.

Deployment choices

“No migration” means no second source of truth. It does not mean zero derived storage.

Related MCP server: Sovereign Universal Memory MCP

How it compares

ATS is a good fit when operational context already lives in task systems or connected work tools and agents need ranked, traceable retrieval across them. If clean Markdown is already the complete source of truth and whole-file loading stays small, a file-native workflow may be simpler.

What you get

• A two-way bus. The agent reads the task fields an adapter provides; where the adapter supports writes, it writes results back where you'll see them.

• First-fetch relevance. Capability-driven branches — keyword and adapter-native search, plus dense retrieval when available — are RRF-fused with provenance to reduce repeated search-and-refine loops.

• Durable typed links. One agent attaches a decision / depends-on / output / supersedes link; a later agent in a fresh context receives it via ats context. The handoff lives in the task app, not a chat log.

• Execution context. ats intent captures outcome/why/done-when; ats lifecycle keeps stale context from steering current work; ats security records scoped allow/deny decisions for cooperating clients; ats ledger records what an agent did and whether the task advanced; ats promote turns exploration into a committed goal; ats hierarchy evaluate checks local work still supports its parent.

• Bounded events. ats events watch --json emits deterministic task.created/updated/completed/... NDJSON, spooled 0600 with pending/ack recovery and stable dedup IDs. ATS only emits observations — a consumer still evaluates intent, validity, and security before acting.

• Task graph for agents. Tasks become structured nodes with proof, writeback, review, lifecycle, and link edges instead of free-form memory text; see docs/task-graph-for-agents.md.

• Session-index handoff. Coding-agent session browsers can keep raw transcript analytics while ATS stores the durable task-linked summary; see docs/agent-session-index.md.

ATS-managed execution metadata can be encoded in the task body, with typed links under ## Related and consulted sources under ## References. Managed helpers are designed to preserve human-authored rows and links, but a direct content update can replace the complete body; callers should read first, write the smallest intended change, and verify the result. npm run prove:intent runs a deterministic synthetic proof of the execution-context path.

Minimal adapter-neutral workflow

1. Select and verify an adapter: ats config use <adapter>, authenticate as its README describes, then run ats doctor.

2. Retrieve the working set: ats find "deployment runbook" --json ranks the branches available from that adapter and retains provenance.

3. Inspect the authoritative item and its context: ats context <project> <task> uses the common adapter contract and does not require an adapter-specific notes layer.

4. Attach durable execution context: ats intent set <project> <task> --outcome "..." --done-when "a,b" and ats link add <src-project> <src-task> <dst-project> <dst-task> --type depends-on.

5. Verify the assembled handoff: rerun ats context <project> <task> to read back linked decisions, dependencies, proof, lifecycle state, and relevant retrieval results.

6. Write through the adapter or source app, then read back. Keep the authoritative backend current so the next agent receives durable state rather than a chat-only handoff.

Deploy it yourself

The optional operator deck is a static phone-oriented web app deployable to Cloudflare Pages. The supplied Render blueprint builds the MCP gateway/server plus private Qdrant and Ollama services.

After deploy, copy the auto-generated ATS_MCP_TOKEN from the ats-mcp service's Environment tab, point your MCP client at https://<your-mcp-url>/mcp with header Authorization: Bearer <ATS_MCP_TOKEN>, and set TICKTICK_ACCESS_TOKEN to read your real tasks. Prefer your own machine or a VPS? Same pieces as plain Docker containers — see the deploy guide.

Available adapters

Backend connectors let an agent reach Notion, GitHub, and task systems, but access alone does not provide one ranked answer to a question such as "what do I know about the auth migration?" ATS adds a common retrieval layer: the composite adapter combines installed child corpora, namespaces their project IDs, unions supported native-search results, and lets Core rank the available branches with provenance. Each child reads its own credentials, but all configured children execute in the same ATS process.

Per-adapter auth and mapping live in each package's README. PRs welcome — scaffold and verify against the contract:

ats adapter new linear              # writes a contract-complete skeleton
ats adapter test ./ats-adapter-linear   # pass/fail/skip per contract check

Tradeoffs and limits

• Freshness is adapter-dependent. Core's corpus cache has a five-minute default TTL. Backend sync behavior, pagination, and inclusion of completed work vary by adapter; ATS does not promise universal real-time reads.

• Dense retrieval adds infrastructure. Qdrant and Ollama can improve semantic recall, but they add indexing, persistence, resource, and backup work. Baseline find still returns keyword/native results when vectors are unavailable, although an attempted vector branch can make the response degraded; vector-only hybrid and similar operations still require that infrastructure.

• The common contract is intentionally small. The adapter interface defines six storage methods plus authentication lifecycle hooks, while practical write coverage, richer fields, and native search vary. Check the adapter README before assuming parity across backends.

• Degraded results are still partial results. ATS reports failed or timed-out Core branches and top-level composite child corpus failures, but the caller must decide whether partial context is acceptable. Current gaps remain: per-project failures inside a composite fallback fetch, child native-search failures, and some TickTick project fetch failures can be omitted without reaching warnings.

• Composite search is not semantic deduplication. ats dedup is a separate analysis command. Fusion currently keys identity by task ID, so backends that emit the same task ID can collide even though their project IDs are namespaced.

• The hosted blueprint is a reference deployment, not a managed service. One bearer token grants the full MCP tool surface; the blueprint does not provide per-user or per-tool scopes, multi-tenant RBAC, high availability, or an SLA.

• Hosted ATS runtime state is ephemeral by default. The blueprint persists Qdrant and Ollama, but does not mount a disk for ats-mcp; its cache, query log, action ledger and undo before-images, event spool, and vector-sync metadata disappear on a restart or redeploy.

• Events are observations, not authorization. ats events watch can report task changes, but a consumer must still evaluate intent, validity, and security before taking an external action.

• ATS policy is not a sandbox or automatic write interceptor. ats security check is an application-level decision point for cooperating clients; ordinary create/update calls do not invoke it automatically, and it does not intercept shell, filesystem, network, model, or secret access outside ATS.

Verification and operational evidence

• CI runs the full repository gate on Node 20 and 22: lint, public-claim checks, PII checks, unit tests, adapter and intent proofs, and the progress benchmark.

• The publish-safety gate scans both the repository surface and npm package tarballs for secrets, personal paths, configured personal-data patterns, and locally configured denylist terms. It protects publication surfaces; it is not runtime redaction or data-loss prevention between adapters.

• State-integrity tests and conventions cover patch-style writes, preservation of unknown fields, explicit store-to-Task mapping, result provenance, and explainable RRF contributions.

• Retrieval behavior documents Core's branches, the corpus cache, time budgets, graceful branch failure, usage logging, and what affects latency.

These gates verify repository behavior; they are not a production availability or security certification.

CLI surface

# Lifecycle
ats init [adapter]                  # select an adapter and run a health check
ats config use <adapter>            # switch the active adapter
ats auth login                      # delegate login to the active adapter
ats doctor                          # inspect adapter and service health

# Retrieval  (any read command takes --json for piping to jq / agents)
ats find <query> [--explain]       # parallel + RRF + provenance — DEFAULT
ats open <project> <task>          # open any adapter item by explicit ids
ats context <project> <task>       # task + valid linked/retrieved context
ats link list <project> <task>     # list portable typed links
ats hybrid <query>                 # dense+sparse retrieval when embeddings exist
ats similar <id>                   # related items when embeddings exist

# Notes-layer shortcuts (currently TickTick and Obsidian)
ats get <id-or-title> [--extract raw|json|yaml]
ats url <id-or-title>              # paste-ready note cross-reference
ats links <project> <task>         # resolve deep-links in a note body

# Authoring
ats create "<title>" [--content ..][--project <id>]
ats update <project> <task> [--content ..][--title ..]

# Agent execution context (portable across adapters)
ats intent set <project> <task> --outcome ".." --done-when "a,b"
ats promote <src-proj> <src-task> <target-proj> --outcome ".." --done-when "a,b"
ats hierarchy set <project> <task> --kind task
ats hierarchy evaluate <project> <task>
ats lifecycle set <project> <task> --status active --valid-until 2026-12-31
ats link add <src-proj> <src-task> <dst-proj> <dst-task> --type decision
ats graph <project> <task>
ats context <project> <task>
ats ledger record <project> <task> --action release.verified --advanced true
ats security set <project> <task> --trust trusted --allow-actions read --allow-resources task:self
ats security check <project> <task> --action read --resource task:self --reason "load context"
ats events watch --json            # NDJSON observations; never launches agents

# Ops
ats bench run
ats bench score
ats bench progress --json
ats bench analyze-usage --days 7
npm run prove:intent
npm run prove:taskmaster
npm run prove:beads
npm run prove:progress

Use it from any MCP client (Claude Code, Claude Desktop, Cursor, Windsurf, OpenCode)

@reneza/ats-mcp exposes the active adapter as a tool set spanning retrieval, CRUD, and execution context (find, get_task, create_task, set_task_intent, add_task_link, resolve_task_links, context_for_task, record_action, undo_write, poll_task_events, and more). For Claude Code this provides persistent context between sessions without replacing the task system as the source of truth; optional caches and vector indexes remain derived retrieval state.

ATS speaks MCP over stdio, so any client that can launch a stdio MCP server works. Only the config file and the wrapper key differ; the binary (ats-mcp) and its ATS_ADAPTER env are the same everywhere.

# Claude Code
claude mcp add ats -e ATS_ADAPTER=@reneza/ats-adapter-ticktick -- ats-mcp

// Claude Desktop / Cursor / Windsurf — identical `mcpServers` shape
{
  "mcpServers": {
    "ats": { "command": "ats-mcp", "env": { "ATS_ADAPTER": "@reneza/ats-adapter-ticktick" } }
  }
}

// OpenCode (opencode.json) — local stdio server, note `command` is an array
{
  "mcp": {
    "ats": {
      "type": "local",
      "command": ["ats-mcp"],
      "environment": { "ATS_ADAPTER": "@reneza/ats-adapter-ticktick" },
      "enabled": true
    }
  }
}

Install the binary on PATH first (npm i -g @reneza/ats-cli), or use an absolute path to ats-mcp if your client does not inherit your shell PATH.

Conventions

• Wiki project. A designated project (default Permanent Notes) holds durable knowledge; others hold ephemeral tasks.

• Agent-data notes = a note whose body has a fenced json / yaml block, extracted via ats get <title> --extract json.

• Cross-references = adapter-native deep links — generate with ats url <title>, don't hand-write.

• Full pattern: docs/wiki-conventions.md.

State integrity

ATS tests managed metadata rewrites for preservation of human-authored fields, requires explicit store-to-Task mapping, and carries result provenance (sources, find --explain). Coverage and raw-update behavior remain adapter-specific. A publication-safety gate (check-no-pii.mjs) fails the build when covered personal-data patterns appear in repository or package surfaces. Full note: docs/state-integrity.md.

For the agent-side operating model, see docs/task-graph-for-agents.md: task text is the human projection, but the execution layer needs structured links, proof commands, review requirements, and writeback targets.

Working on ATS

Contributions welcome — bug fixes and especially new adapters under packages/adapter-*. See CONTRIBUTING.md for the dev setup and adapter pattern, and AGENTS.md if you drive a coding agent over the repo. Working on the source, pi-codegraph gives your agent a call-graph of the monorepo — the adapter pattern and the blast radius of a core change — so it stops re-reading the whole tree each session.

Releases and license

v0.10.0 added partial-retrieval reporting, optional reranking, usage observability, duplicate/contradiction detection, and reactive OAuth refresh. v0.9.0 added reversible writes, forward/dangling links, Obsidian path hardening, and verified stdio configuration for more clients. Full history: CHANGELOG.md.

MIT. See LICENSE.

If ATS is useful, consider a ⭐ — it helps others find it.