agentic-task-system

<p align="center">
  <img src="assets/logo.png" alt="Agentic Task System" width="420" />
</p>

<p align="center"><strong>Your task manager is the best agent memory you're not using.</strong></p>

<p align="center">
  <a href="https://www.npmjs.com/package/@reneza/ats-cli"><img src="https://img.shields.io/npm/v/@reneza/ats-cli?logo=npm&label=%40reneza%2Fats-cli&color=A855F7" alt="npm version" /></a>
  <a href="https://github.com/renezander030/agentic-task-system/actions/workflows/ci.yml"><img src="https://github.com/renezander030/agentic-task-system/actions/workflows/ci.yml/badge.svg" alt="CI" /></a>
  <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-3b82f6" alt="MIT license" /></a>
  <img src="https://img.shields.io/badge/PRs-welcome-7C5CFF" alt="PRs welcome" />
</p>

`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](packages/adapter-composite/). 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.

**Two layers, one CLI: tasks and a knowledge graph.** The task layer is record-based on purpose — every entry lives in one backend's projects and fields, and that backend stays authoritative. A record-based layer structurally cannot hold the other thing agents accumulate: durable knowledge **written from any source, about mixed subjects, into one space**. The knowledge-graph layer — **`ats kg`** (kg = knowledge graph) — is ATS's answer to exactly that: subject–predicate–object facts with provenance and temporal validity, proposed by agents from anywhere (a call, a task, a repo, a chat), ratified by a human, and queried in one place no matter which backend the surrounding work lives in. The built-in store is embedded and dependency-free. For a dedicated graph engine, the recommended pairing is **[Graphiti](https://github.com/getzep/graphiti) as the graph database server** and **[LadybugDB](https://github.com/LadybugDB) as the embedded graph database**: `ats kg export --cypher` emits a LadybugDB-loadable script (`--dialect neo4j|falkordb` for the server engines, re-runnable), and `ats kg export --graphiti` emits episode JSONL with the provenance record for a Graphiti ingest pipeline.

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

<p align="center">
  <img src="assets/demo-fusion.gif" alt="ats find — one query fused across GitHub, Notion, and TickTick, ranked by RRF" width="760" />
  <br><em>One <code>ats find</code> across <strong>GitHub + Notion + TickTick</strong>. ATS ranks the available retrieval branches with RRF and retains result provenance.</em>
</p>

## Architecture and trust boundaries

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

```text
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](#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](docs/retrieval.md), [state integrity](docs/state-integrity.md), and the [deployment guide](deploy/README.md) for the exact behavior.

### Deployment choices

| Mode | Retrieval | Trust and operations boundary |
| --- | --- | --- |
| **Local stdio** | Keyword/native retrieval by default; dense retrieval only when the adapter provides it | The MCP endpoint is not network-exposed. Adapter calls may still reach their source systems; credentials and cache files stay on the machine running ATS. |
| **Composite adapter** | One combined child corpus; Core ranks keyword and unioned native-search branches, with RRF across those available branches. The composite does not currently expose child vector search. | Each child owns its auth and mapping but runs in the same ATS process. A top-level child corpus failure is reported as degraded; see the known fallback gaps below. |
| **Hosted blueprint** | Keyword/native retrieval plus private Qdrant/Ollama services | A bearer-token MCP gateway and separate optional operator-deck backend are public; Qdrant and Ollama stay on the private service network. Qdrant/Ollama have disks, while `ats-mcp` runtime files are ephemeral by default. You operate token rotation, persistence, backups, availability, and hosting cost. |

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

## How it compares

| Approach | Authoritative record | Additional state | Retrieval |
| --- | --- | --- | --- |
| `CLAUDE.md` / memory files | Markdown maintained for the agent | The files themselves | Whole-file or harness-specific lookup |
| Separate memory service | Agent-specific database | A corpus and ingestion path to maintain | Product-specific |
| Plain backend connector | Source task app, repository, or vault | Usually none beyond connector state | Direct fetch or backend-native search |
| **ATS** | Source task app, repository, or vault | Cache, query/action/event state; optional derived vector index | Keyword + native + optional dense retrieval, RRF, provenance, typed context |

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. Every `find` carries a confidence verdict from branch agreement (`--min-sources N` is the matching gate), `--project` binds it to one project, a stale corpus cache answers immediately while it refreshes in the background, and an empty exact match (`notes find`, `search`, `get`) answers with the nearest items instead of nothing.
- **Writes that survive retries and concurrency.** `update --append` / `--prepend` add to the body that is there; `--if-match <contentHash>` lands only while the body is unchanged; `create --if-absent` and `--idempotency-key` make a retried create return what the first one produced. Shared HTTP requests have deadlines and respect cancellation. Reads retry transient failures; mutations retry only explicit rate-limit rejections, so ambiguous failures do not replay a write.
- **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 loc