# @reneza/ats-adapter-ticktick

> **Turn your TickTick into your agent's context layer.** Reference adapter for [Agentic Task System](https://github.com/renezander030/agentic-task-system) — wraps TickTick's OpenAPI v1 (plus optional local qdrant + nomic-embed via Ollama) into the ATS adapter contract so agents can find / read / link / update tasks and notes via a single CLI surface.

## Why this exists

TickTick has thousands of your durable notes plus an excellent mobile capture flow. What it's missing is an agent-native retrieval layer tuned for how *agents* query (not how humans type). This adapter adds:

- **Wiki layer** — designate a project (default: "Permanent Notes") as your knowledge base. `find` / `get` / `url` / `links` operate on it.
- **Hybrid retrieval** — pure TickTick semantic search misses short note titles; this adapter exposes the dense vector path so [@reneza/ats-core](https://npmjs.com/package/@reneza/ats-core)'s parallel fan-out can fuse it with keyword + title-fuzzy. Result on a 5-question agent bench: 60% top-1 / 80% recall@5, vs 20% / 40% for dense alone.
- **Agent-data notes** — fenced ```json blocks inside notes, extracted via `--extract json` for cron / agent consumption. Single source of truth, mobile-editable, no schema migration.

## Install

```bash
npm install -g @reneza/ats-cli @reneza/ats-adapter-ticktick
ats config use ticktick
ats auth login          # prints TickTick OAuth URL + exchange command
ats find "deployment runbook"
```

For semantic / hybrid retrieval, also run a local qdrant + Ollama with `nomic-embed-text`:

```bash
docker run -d --name qdrant -p 6333:6333 qdrant/qdrant:latest
docker run -d --name ollama -p 11434:11434 ollama/ollama:latest
docker exec ollama ollama pull nomic-embed-text
ats sync vector
```

Nomic retrieval prefixes are opt-in because stored documents and queries must
be migrated together. Build a separate collection and metadata manifest before
enabling them:

```bash
ATS_TICKTICK_VECTOR_COLLECTION=ticktick_tasks_nomic_prefixed \
ATS_TICKTICK_VECTOR_META="$HOME/.local/share/ats/vector-index-meta-nomic-prefixed.json" \
ATS_TICKTICK_NOMIC_PREFIXES=1 \
ats sync vector --full
```

Use the same three variables for subsequent search commands. Do not enable only
the query prefix against an existing unprefixed collection.

## What this adapter implements

All six required methods of the ATS adapter contract:

- `listProjects()` — TickTick projects via Open API v1
- `listTasksInProject(projectId)` — active tasks in a project
- `getTask(projectId, taskId)` — full task body
- `createTask(input)` — POST /open/v1/task
- `updateTask(projectId, taskId, patch)` — POST /open/v1/task/{id}
- `urlFor({projectId, taskId})` — `https://ticktick.com/webapp/#p/<proj>/tasks/<task>` deep links

Plus auth lifecycle (`authStatus` / `authLogin` / `authExchange` for OAuth) and the optional `searchByQuery` (TickTick's substring-only native search).

Adapter ships with the wiki helpers (`notes.find/get/url/links`), capture-time relevance enrichment (`--relevance`), and the Qdrant + Ollama integration through its rich task extension. Its contract-level optional method is `searchByQuery`; the local-cache adapter additionally exposes `bulkFetch`.

## Repo + docs

- **Repo**: https://github.com/renezander030/agentic-task-system
- **Wiki conventions**: https://github.com/renezander030/agentic-task-system/blob/main/docs/wiki-conventions.md
- **Adapter interface**: https://github.com/renezander030/agentic-task-system/blob/main/docs/adapter-interface.md

## License

MIT