@reneza/ats-core

Agent-side retrieval that fans out every available retriever in parallel and votes on the result. Core always provides ranked keyword search, adds adapter-native search when available, and adds dense+sparse hybrid retrieval when the adapter supplies embeddings. The merged top-K includes sources: [...] provenance.

The adapter-agnostic core of Agentic Task System — an agent-native context layer over the task app you already use, with pluggable storage adapters.

Why this exists

Pure semantic search (nomic-embed via qdrant) underweights short titles — a doc titled simply ffmpeg doesn't surface for "ffmpeg commands". Pure keyword search misses paraphrased queries. Hybrid retrieval fused via Reciprocal Rank Fusion gets you 60% top-1 / 80% recall@5 on agent-issued queries versus 20% / 40% for dense alone (n=5 micro-bench, see repo).

Built for agents that read top-K, not humans that read top-1.

Install

npm install @reneza/ats-core

You'll typically pair it with a storage adapter — see @reneza/ats-adapter-ticktick for the reference implementation, or write your own adapter against the 6-method interface.

What you get

• Parallel retrieval — fan-out + RRF fusion, deadline-bounded, provenance-tagged results
• Corpus cache — disk-backed, 5-min TTL; warm calls avoid remote corpus fetches
• Usage logger — instrumented retrieval calls write JSONL for later analysis
• Bench harness — Q/A pairs you author, scored by hit@1 / recall@5 / MRR per tag bucket
• Adapter interface + validator — JSDoc types for the contract every storage adapter implements
• Portable execution context — intent, exploration promotion, hierarchy/conflict evaluation, lifecycle validity, typed relationships, graph traversal, and context assembly in task bodies
• Action ledger — append-only JSONL records of agent actions, sources, approvals, output, and advancement
• Scoped security decisions — default-deny trust/action/resource policy with approval checks and mandatory allow/deny auditing
• Task event stream — deterministic corpus diffs with stable IDs, atomic content-free checkpoints, and no autonomous execution
• Workflow-progress benchmark — separate advancement, context waste, blocker, completion, reopen, and correction metrics over disclosure-safe episode records

Quick example

import { validateAdapter } from '@reneza/ats-core';
import adapter from '@reneza/ats-adapter-ticktick';

validateAdapter(adapter);
// adapter is now ready to plug into core.find / core.get / core.url

See the agent execution layer. Run npm run prove:intent, npm run prove:beads, and npm run prove:progress in the repository for synthetic end-to-end proofs.

Adapter contract (six methods, three optional)

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 uses if present, falls back if not:
  searchByQuery?(query: string): Promise<Task[]>
  bulkFetch?(): Promise<Task[]>
  embeddings?(texts: string[]): Promise<number[][]>
}

Full spec at docs/adapter-interface.md.

Repo + docs

• Repo: https://github.com/renezander030/agentic-task-system
• Adapter interface: https://github.com/renezander030/agentic-task-system/blob/main/docs/adapter-interface.md

License

MIT