agentic-task-system

Your task manager is the best agent memory you're not using.

ats is an MCP server and CLI that gives your AI agent memory from the task system you already use — TickTick, Taskmaster, Beads, Obsidian, Notion, GitHub, Airtable, Google, or all at once via the composite adapter. It fuses retrieval across adapters with Reciprocal Rank Fusion (RRF) and layers on portable intent, typed task links, lifecycle validity, scoped access, an action ledger, and bounded task events. Works with Claude Code, Claude Desktop, Cursor, and any MCP client.

Adapter, not migration. Most "agent memory" projects build a new store that drifts the moment you stop feeding it. But you already curate a knowledge base by hand every day — your task app. ATS makes that context agent-native without re-homing a single note. It's task-first: the task is the spine; supporting docs (GitHub issues, Notion specs) fuse in as context behind it — not a second-brain/PKM tool.

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

The operator deck: the agent proposes the next best action across your tools — approve, reject, or send it back, with a thumb.

One ats find across GitHub + Notion + TickTick, ranked by RRF. Your connectors give the agent access; this is the semantic layer that lands the first query on the right answer.

How it compares

Andrej Karpathy's LLM Wiki idea is right about the destination, wrong about the starting line: almost nobody's knowledge lives in clean markdown — it lives in the task app they've used for years. ATS closes that gap with pluggable storage adapters.

What you get

• A two-way bus. The agent reads a task's title, body, tags, dates, and checklist; it writes results back where you'll see them.
• First-fetch relevance. Parallel hybrid retrieval (dense + sparse + keyword, RRF-fused, with provenance) collapses "search → refine → search again" into one fetch.
• 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 scopes actions and audits allow/deny; 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.
• Curated at write time. Every item is hung on a "trunk" (a theme like writing, client-work) the moment it's captured, so retrieval has structure to grab.

Metadata lives in flat YAML frontmatter on the task body, typed links in ## Related, consulted sources in ## References. Writes are add-only — ATS never drops a row or link a human added. npm run prove:intent runs a deterministic synthetic proof of the full path.

Walkthrough: from a task pile to the next action

Three tags steer everything — do: (agent or you), type: (build/research/review), effort: (S/M/L):

1. Capture into the system you already use.
2. Tag each task do: / type: / effort:.
3. Link dependencies: ats link add <task> <blocker> --type depends-on.
4. Let bd ready pick the unblocked frontier — you never scan the backlog.
5. Do it, then close. Closing recomputes the frontier; the next right thing surfaces on its own.

Deploy it yourself

The operator deck (phone app) runs free on Cloudflare Pages; the backend runs on Render — one click builds the MCP server plus a private search memory (Qdrant) and embedding engine (Ollama).

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.

Adapter interface

Six methods. Implement them and you have an adapter:

interface KnowledgeAdapter {
  listProjects(): Promise<Project[]>
  listTasksInProject(projectId: string): Promise<Task[]>
  getTask(projectId: string, taskId: string): Promise<Task>
  createTask(input: TaskInput): Promise<Task>
  updateTask(projectId: string, taskId: string, patch: TaskPatch): Promise<Task>
  urlFor(ref: { projectId: string, taskId: string }): string
}

Optional (Core falls back if absent): searchByQuery? (native search), bulkFetch? (single-call corpus refresh), embeddings? (adapter-supplied). Without embeddings(), Core still gives ranked keyword retrieval; with it, dense+sparse hybrid and similarity. Full spec: docs/adapter-interface.md.

Available adapters

Every vendor ships an MCP connector now, so your agent can reach Notion, GitHub, and your task app — but not retrieve ("what do I know about the auth migration?", ranked across all of them). That's the layer ATS adds: hybrid RRF ranking, one query across every source (the composite adapter fuses them into one deduped list), top-k instead of token dumps, and the credential stays scoped inside the adapter.

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

ats adapter new linear              # writes ats-adapter-linear/ (six stubs)
ats adapter test ./ats-adapter-linear   # pass/fail/skip per contract check

CLI surface

# Lifecycle
ats init|config use|auth login|doctor <adapter>   # setup, switch, auth, health check

# Retrieval  (any read command takes --json for piping to jq / agents)
ats find <query> [--explain]       # parallel + RRF + provenance — DEFAULT
ats open|url <id-or-title>         # deep link / paste-ready cross-reference
ats get <id-or-title> [--extract raw|json|yaml]
ats links <project> <task>         # resolve deep-links in a task body
ats hybrid <query> | ats similar <id>   # when embeddings exist

# 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|evaluate <project> <task>
ats lifecycle set <project> <task> --status active --valid-until 2026-12-31
ats link add|remove <src-proj> <src-task> <dst-proj> <dst-task> --type decision
ats graph|context <project> <task>
ats ledger record <project> <task> --action release.verified --advanced true
ats security set|check <project> <task>
ats events snapshot|watch|pending|ack   # NDJSON observations; never launches agents

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

Use it from Claude Code, Claude Desktop, Cursor (MCP)

@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, context_for_task, record_action, poll_task_events, and more). For Claude Code this is persistent memory between sessions with no new database — the agent recalls runbooks, decisions, and project state from the task app you already keep current.

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

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

Quickstart (TickTick adapter)

ats config use ticktick
ats auth login          # prints the OAuth URL and next command

# (optional) semantic / hybrid retrieval via local qdrant + ollama:
docker run -d --name qdrant -p 6333:6333 qdrant/qdrant
docker run -d --name ollama -p 11434:11434 ollama/ollama
docker exec ollama ollama pull nomic-embed-text
ats sync vector

ats find "ffmpeg commands"

The TickTick cache adapter refreshes directly through TickTick OpenAPI; ats cache sync preserves Inbox addressing and the last good file on any project failure.

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 holds the line where agent systems fail: writes round-trip without lossy re-encoding, the store → Task mapping is contract-tested, and every result carries its provenance (sources, find --explain). A publish-safety gate (check-no-pii.mjs) fails the build if personal data could leak into a package. Full note: docs/state-integrity.md.

Versioning & license

v0.6 — portable intent, exploration promotion, goal hierarchy + conflict evaluation, bounded task events, workflow-progress evaluation, Taskmaster and Beads adapters. See CHANGELOG.md. MIT.

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