Oh Knots

how the cartine tames agentic memory

Welcome to Knots. You can’t imagine the sheer volume of puns discarded during the process of editing this post.

What the hell is Knots

It’s an agentic memory system.

remember sammy jankis...

Every work unit is captured as a "knot". A knot moves through a workflow where each step is either:

• a Queue (waiting to be grabbed) or

• an Action (already grabbed).

It’s simple. Opinionated. Fast.

Literally every coder everywhere has already built this

Yes but would they wear a platinum blonde wig to a daily standup? Then I win. May I now continue with my shameless, disingenuous self-marketing?

Since you brought it up though, Knots was more than heavily inspired by Beads. Beads is pretty neat and it changed the way I think about working with agents.

Fair enough

Thanks. Now look, Knots is cool because the work units are self-describing prompts. They record which model touched which step. They're backed by git so you can sync across a worktree without a server. It’s not built with any particular agent in mind.

How does it actually work

Install it:

curl -fsSL https://raw.githubusercontent.com/acartine/knots/main/install.sh | sh

Initialize it in your repo:

$ kno init
► initializing local store
► opening cache database at .knots/cache/state.sqlite
► ensuring gitignore includes .knots rule
✔ local store initialized
► initializing remote branch origin/knots
  ↳ this can take a bit...
✔ remote branch origin/knots initialized
══════════════════════════════════
FIT TO BE TIED 🎉
══════════════════════════════════

Create a knot:

kno new "add dark mode support"

Now an agent — or you — polls for work:

➜ knots git:(main) ✗ kno poll
# add 'kno ready <optional_ready_type>' command
**ID**: d816  |  **Priority**: none  |  **Type**: work
**Profile**: autopilot_no_planning  |  **State**: ready_for_implementation
## Description
list queued knots in workflow order, with optional filter based on implicit ready types such as plan_review, implementation_review, plan, implementation, etc.
---
# Implementation

## Input
- Knot in `ready_for_implementation` state
- Approved implementation plan (in knot notes)

## Actions
1. Create a feature branch from main in a worktree
2. Implement changes following the plan
3. Write tests for all new behavior
4. Run any sanity gates defined in the project or the plan
5. Add a handoff_capsule to the knot with `kno update <id> --add-handoff-capsule "<handoff_capsule>"
 --handoff-username <username> --handoff-date <date RFC3339> --handoff-agentname <agentname> --handoff-model <model> --handoff-version <model_version   >`
5. Commit and push the feature branch
6. Profile variant: Create a PR if the knot profile expects it
7. Profile variant: Merge the feature branch into main if the knot profile expects it

## Output
- Working implementation on feature branch
- All tests passing with coverage threshold met
- Transition: `kno next <id>`

## Failure Modes
- Blocked by dependency: `kno update <id> --status deferred --add-note "<blocker details>"`
- Implementation infeasible: `kno update <id> --status ready_for_planning --add-note "<blocker details>"`
## Completion
`kno next <id> --actor-kind agent`
➜ knots git:(main) ✗

What exactly is happening there?

Three things are bound together in that output:

1. work unit — what the knot is, its description, its priority;

2. state — which drives exactly which prompt fires; and

3. prompt — auto-generated from the state and the profile, with the completion command already embedded.

The agent doesn’t need to remember anything. It just does the work and runs the command at the bottom. That’s it. That’s the whole deal.

Pipe it straight into your agent and you’re off:

kno poll --claim | myagent-cli --prompt -

And then what?

The agent runs the completion command, the knot transitions state, and the next agent pick-up is already waiting. You can run a loop — poll, claim, work, complete, repeat — or just fire it manually when you’re ready. Either way, Knots keeps the queue honest.

Tell me more about “profiles”

A profile is how knots communicate with agents about who owns each step and what “done” means. There are six built-in profiles. Here are a few examples:

• autopilot (agent handles everything end to end, including planning)

• semiauto (human reviews the plan before the agent builds),

• autopilot_no_planning (skip planning entirely, agent just implements).

The profile is a knot-level attribute, determining which prompts fire at which states — which is how the same knot can behave totally differently depending on whether a human or an agent is supposed to be touching it.

Is this for humans too, or just agents?

Both. Humans can claim knots too.

The workflow is a guide for agents - it allows you to determine in advance - how much involvement do I want to have in this unit of work? Does it require planning? Do I want to do the code review?

The human can override the workflow at any step. The agent cannot.

Should we be disturbed about our casual use of the word ‘humans’?

Without question.

OK, I’m in. Now what?

Install it. The README has everything else. Go build something.

Anything else going on?

Obviously we’ll be integrating Knots tightly with Foolery. We’ll also introduce OpenRouter support and configurable RWLs. Should hit your inbox by mid-March.

Did you just intentionally throw RWLs out there like it was a thing?

Fuck yes. This is shameless self-promotion, remember?

as always, the cartine thanks you for your time