Hark

Execution memory that lets Agent Skills carry what they learned into the next run

Comment

Short description:
Hark is an execution-memory plane for Agent Skills. It turns real run evidence, failures, recoveries, and successful paths into scoped experience stored in CockroachDB, then brings the relevant experience into later runs. Workflows are additive: each workflow supplies its Skill, scope, safe tools, and environment adapter while Hark preserves the same memory, provenance, retrieval, and invalidation semantics underneath.

Built with:
CockroachDB Cloud, CockroachDB Distributed Vector Indexing, CockroachDB Agent Skills, AWS Lambda, Amazon S3, AWS Systems Manager Parameter Store, AWS CloudFormation, Amazon CloudWatch, Amazon Bedrock, Google Gemini, Python, JavaScript

Public application:
https://sdzlkokjx52kzobxgsl74riswa0afbzv.lambda-url.us-east-1.on.aws/

Prepared production investigation:
https://sdzlkokjx52kzobxgsl74riswa0afbzv.lambda-url.us-east-1.on.aws/demo/ZnGIi4hehPOyM354yuEkxUrUrldivqca

Public repository:
https://github.com/PrathmeshAdsod/HARK

Add your workflow guide:
https://github.com/PrathmeshAdsod/HARK/blob/master/ADD_WORKFLOW.md

Setup and operations:
https://github.com/PrathmeshAdsod/HARK/blob/master/SETUP.md

License:
https://github.com/PrathmeshAdsod/HARK/blob/master/LICENSE

Project Story

About the project

Hark gives Agent Skills something they normally lose between runs: execution experience.

A Skill can describe the right procedure, but the environment still teaches the agent things the Skill could not know in advance: a permission boundary, a failed preflight, the recovery that worked, the evidence that mattered, or a path that should be skipped next time.

Hark captures those outcomes as governed memory in CockroachDB and makes the relevant experience available to the next related execution.

The memory plane is independent of a specific incident type. A Hark workflow contributes four workflow-specific pieces:

  1. the Agent Skill,
  2. a stable Skill/workflow/environment scope,
  3. an explicit safe tool surface,
  4. an adapter to the real target environment.

Everything beneath that boundary stays Hark: immutable execution evidence, derived experience, vector recall, deterministic failure recovery, source/use provenance, invalidation, provider routing, and execution budgets.

For the hackathon, we validated that architecture end to end with a complete CockroachDB query-regression workflow using Cockroach Labs' official profiling-statement-fingerprints Agent Skill.

Inspiration

Agent Skills are a powerful way to encode reusable procedure, but procedure is not the same as experience.

An agent can follow the same Skill tomorrow and rediscover the same environment-specific failure it already solved today. Chat history does not really solve this: it is difficult to scope, hard to invalidate, and usually detached from the exact execution evidence that produced the conclusion.

That led to the core question behind Hark:

What if the execution layer itself could remember?

Not by retraining the model, rewriting the Skill, or dumping old conversations into a prompt. Instead, Hark stores compact, provenance-backed experience derived from real runs and recalls it only when the Skill, workflow, environment, and task are compatible.

What it does

Hark wraps an Agent Skill with a persistent execution-memory loop:

task
  → scoped memory search
  → Skill + relevant prior experience
  → bounded tool execution
  → evidence / failure / recovery / outcome
  → experience persisted in CockroachDB
  → later related task recalls that experience
  → provenance records exactly what influenced the run

The production workflow demonstrates this with CockroachDB query-regression diagnosis.

On the first investigation, Hark loads the official profiling-statement-fingerprints Skill and searches for relevant prior experience. None exists.

The agent then runs real read-only diagnostics against CockroachDB. A restricted diagnostic identity reaches a cluster-setting preflight that the environment does not permit, and CockroachDB enforces that boundary with SQLSTATE 42501. Hark does not escalate privileges. The agent continues through the safe diagnostic path using statement statistics, EXPLAIN, and index metadata.

Hark persists what the run taught it: the failure, the successful recovery, the evidence path, the diagnosis, provenance, and a canonical 256-dimensional execution-memory embedding.

A later, differently worded investigation searches memory before acting. In the verified production pair, CockroachDB recalled the earlier experience at cosine similarity 0.757532, above the configured 0.73 threshold. The agent skipped the known denied preflight, still gathered fresh evidence, and completed with:

  • 4 → 3 diagnostic tools
  • 1 → 0 tool failures
  • 8.85 s → 6.93 s

The later run is explicitly linked to the exact experience that influenced it. Memory can also be invalidated without erasing its audit history.

Hark's workflow model is additive. Additional workflows can provide a different Skill, scope, safe tools, and environment adapter while keeping the same execution-memory semantics. The repository includes both a manual extension path and a coding-agent-assisted path in ADD_WORKFLOW.md.

How we built it

We separated Hark into two conceptual layers.

Workflow layer

A workflow defines:

  • the Skill the agent should follow,
  • its Skill/workflow/environment identity,
  • the tools the model is allowed to select,
  • the adapter that executes those tools against the real environment.

The included production workflow uses Cockroach Labs' pinned profiling-statement-fingerprints Skill and a restricted CockroachDB diagnostic identity with four fixed, read-only operations.

Hark memory plane

CockroachDB Cloud stores:

  • runs,
  • immutable execution events,
  • derived experiences,
  • deterministic failure recoveries,
  • run-to-experience provenance,
  • provider-budget reservations,
  • concurrency leases,
  • invalidation state,
  • canonical VECTOR(256) execution-memory embeddings.

Distributed Vector Indexing performs semantic recall only after exact Skill/workflow/environment/demo scoping. This keeps unrelated experience from silently crossing boundaries.

The same memory semantics can be reused when another workflow supplies different Skills, tools, and environment integrations.

AWS runtime

AWS Lambda hosts the bounded Python agent, JSON API, and responsive frontend behind a public Function URL.

CloudFormation defines the runtime and least-privilege IAM. SSM Parameter Store holds encrypted configuration and the execution kill switch. S3 stores private deployment packages, and CloudWatch receives runtime logs.

The reasoning layer is provider-resilient. Amazon Bedrock Nova Micro is the preferred reasoning path when the account is authorized for it. Gemini 3.5 Flash-Lite is the verified automatic fallback, with Gemini 3.1 Flash-Lite as a tertiary provider-failure route.

Memory embeddings stay in one canonical semantic space using Gemini Embedding 2 at exactly 256 dimensions, independent of which reasoning provider handled a run.

Challenges we ran into

Making memory change execution, not just retrieve text

The important part was not showing a similarity score. The retrieved experience had to alter the agent's next execution while still requiring fresh evidence.

Hark therefore injects a compact Experience Brief and uses it to avoid a known dead-end path, while the related run still performs the useful diagnostic operations and produces a new evidence-grounded diagnosis.

Keeping memory scoped and compatible

Agent memory becomes dangerous if experience from the wrong Skill or environment leaks into another run.

Hark filters by Skill, workflow, environment, status, and active-memory scope before vector ranking. We also keep all memory vectors in one canonical embedding space so provider changes cannot make unrelated vector spaces look comparable.

Choosing a real recall threshold

We did not choose the vector threshold by guesswork. Related prompts scored roughly 0.742–0.754 against the initial production experience, while unrelated prompts peaked around 0.657. We selected a precision-first threshold of 0.73 and then verified the production pair at 0.757532.

Building a safe execution boundary

User text never becomes arbitrary SQL. The reasoning model can only choose from the explicit tool surface provided by the workflow. The current CockroachDB workflow uses a separate least-privilege diagnostic identity, while the memory identity owns the memory lifecycle.

Provider resilience without changing memory semantics

Reasoning-provider availability should not determine whether previously learned experience remains usable. We separated the reasoning route from the canonical memory representation so Hark can fail over between reasoning providers while keeping execution memory stable and comparable.

Accomplishments that we're proud of

  • Built a reusable execution-memory plane around Agent Skills rather than storing raw chat history.
  • Defined a clear extension contract: Skill + scope + safe tools + real environment adapter.
  • Documented both manual and coding-agent-assisted workflow extension paths in ADD_WORKFLOW.md.
  • Shipped a live AWS application with a complete CockroachDB production workflow.
  • Captured a real SQL permission boundary and a safe recovery without privilege escalation.
  • Persisted evidence, recovery, vector memory, provenance, and invalidation in one CockroachDB system.
  • Demonstrated a related run that actually used prior experience and changed its execution path.
  • Reduced the verified related run from 4 tools / 1 failure to 3 tools / 0 failures.
  • Passed 17 local tests and 13/13 production database verification checks.
  • Kept memory inspectable: every experience points to its source run and every later use is recorded explicitly.

What we learned

The most useful agent memory is not “what the model said last time.” It is what execution taught the system.

That means memory needs more than embeddings. It needs scope, provenance, compatibility boundaries, failure structure, invalidation, and a clear relationship to the evidence that produced it.

We also learned that the workflow boundary matters. The Skill, tools, and environment may change, but the memory semantics do not have to. Once that boundary is explicit, the same Hark memory plane can sit beneath very different operational workflows.

CockroachDB was a strong fit for this because relational state, transactions, provenance, and vector search can live together instead of splitting operational memory across a database and a separate vector service.

What's next for Hark

The next step is to make workflow extension a first-class product surface rather than a repository-level contract.

That means:

  • a formal workflow/adapter interface,
  • registration of multiple Skills and environments,
  • authenticated team workspaces,
  • organization-level retention and invalidation policies,
  • workflow-specific evaluation cohorts,
  • stronger observability around memory usefulness,
  • and eventually a smoother “bring your Skill and environment” developer experience.

The repository already documents how to add additional workflows today. The longer-term goal is to make that extension path progressively more declarative while preserving the same memory guarantees.

Built With

Share this project:

Updates