Task Keep

Let your agents quietly preserve meaningful work—and find it when you need it.

Most of the time, you do not need to ask Task Keep to do anything. Your agents record meaningful completed, changed, failed, and unfinished work as they go. Later, that history makes requests like these possible:

What did I work on yesterday?

Where is the report I prepared for AAA last month?

Find every file created for the XXX project during the last three months, compress them, and save the archive for me.

Your agent can search the history, recover the relevant context and artifact paths, and continue with the requested action. You only need to mention Task Keep explicitly when you want to; routine recording and relevant recall are guided by the installed skill.

Task Keep preserves the parts of past work that are worth reusing: completed deliverables, important decisions, confirmed failures, and unfinished work that should survive the current session. It is not a conversation archive, and it does not replace an agent's built-in memory.

Two simple jobs

1. Recall past work

When earlier work may be useful, Task Keep searches the work history and returns only the most relevant records. It helps an agent recover context without loading entire transcripts or guessing what happened before.

Current files and current user instructions always take priority over stored history.

2. Keep meaningful results

Before finishing meaningful work, Task Keep records what was requested, what happened, what changed, how the result was validated, and what remains unfinished.

It intentionally skips ordinary questions, trivial edits, scratch attempts, and unnecessary conversation details.

Recommended installation: ask your agent

The easiest way to install Task Keep is to give this repository URL to an agent that can read files and run shell commands.

Copy and send this prompt to your agent:

Install Task Keep from https://github.com/miter37/task-keep.

Read README.md completely, then follow the section named
"Instructions for installing agents". Detect every supported agent program
installed on this computer, install the Task Keep skill for each one, create
the shared JSONL storage directory, and add the managed Task Keep instructions
to the appropriate AGENTS.md or CLAUDE.md files.

Preserve all existing files and instructions. Do not report success until you
have verified every path you changed.

The agent performing the installation may be Codex, Claude Code, Google Antigravity CLI, Hermes, OpenClaw, OpenCode, Grok Build, or another capable local agent.

Instructions for installing agents

This section is written for the agent performing the installation.

CRITICAL INSTRUCTION: Step 3 (installing SKILL.md) and Step 4 (adding the instruction block) must be performed as a pair for EVERY detected agent. It is strictly forbidden to complete Step 3 for an agent without also completing Step 4. You MUST NOT report success until you have self-verified the checklist in Step 5 and explicitly printed the verification results.

Install Task Keep for every supported agent you can positively detect on the user's computer. Do not infer configuration directories from the executable location. Inspect environment variables, application configuration, profiles, and workspaces when the user has customized them.

If a location is ambiguous, show the discovered candidates and ask the user which one to use. Never silently install into a guessed profile or workspace.

Check both the executable and its configuration. Common executable names are codex, claude, agy, hermes, openclaw, opencode, and grok. A binary found on PATH is evidence that an agent is installed, but its binary directory is not its skill or instruction directory. Existing configuration directories may also reveal profiles or workspaces that are not currently on PATH.

1. Obtain the source

Clone or download this repository to a temporary or user-approved location. Read SKILL.md and SETUP.md before making changes.

Do not execute unreviewed scripts from the repository. Task Keep needs only file and directory operations.

2. Choose one shared data root

All installed agents must read and write the same Task Keep data.

The data root must be independent of the current project, repository clone, agent installation directory, and current working directory. Use the operating system's standard per-user application-state or application-support location.

Resolve the data root in this order:

1. Use TASK_KEEP_HOME when it is set.
2. Otherwise, reuse an existing Task Keep data root if one is already configured.
3. Otherwise, select the default for the current operating system:

Operating system	Default Task Keep data root
Linux and WSL	$XDG_STATE_HOME/task-keep when XDG_STATE_HOME is set; otherwise $HOME/.local/state/task-keep
macOS	$HOME/Library/Application Support/task-keep
Windows	%LOCALAPPDATA%\task-keep

Resolve the selected location to an absolute path. If the required OS variable or user-home location cannot be determined, ask the user for a permanent data location. Never fall back to the current working directory, project directory, downloaded repository, temporary directory, or an agent's own installation directory.

Create this structure if it does not exist:

<TASK_KEEP_DATA_ROOT>/
├── worklog/
│   ├── <current-year>.jsonl
│   └── <previous-year>.jsonl
└── requests/

Create missing year files as empty files. Preserve every existing record. Never truncate, replace, or reformat an existing JSONL file during installation. Where supported, keep the data root private to the current OS user.

If an older Task Keep or agent-work-memory data directory is found, preserve it and ask before moving or merging data.

3. Install the skill

Install a local copy of SKILL.md as task-keep/SKILL.md in every detected agent's supported skill directory. Create missing directories when necessary.

Use the application's configured home, profile, or workspace when it differs from the default. The following paths are defaults and discovery hints, not permission to ignore custom configuration.

Agent	Preferred project or workspace skill location	Common user-level location
Codex	<project>/.agents/skills/task-keep/SKILL.md	$HOME/.agents/skills/task-keep/SKILL.md
Claude Code	<project>/.claude/skills/task-keep/SKILL.md	$HOME/.claude/skills/task-keep/SKILL.md
Google Antigravity CLI (agy)	<project>/.agents/skills/task-keep/SKILL.md	$HOME/.agents/skills/task-keep/SKILL.md
Hermes	<workspace>/.agents/skills/task-keep/SKILL.md when configured as an external skill directory	<HERMES_HOME>/skills/task-keep/SKILL.md
OpenClaw	<workspace>/skills/task-keep/SKILL.md	$HOME/.openclaw/skills/task-keep/SKILL.md
OpenCode	<project>/.agents/skills/task-keep/SKILL.md	$HOME/.agents/skills/task-keep/SKILL.md or $HOME/.config/opencode/skills/task-keep/SKILL.md
Grok Build	<project>/.agents/skills/task-keep/SKILL.md	$HOME/.agents/skills/task-keep/SKILL.md or $HOME/.grok/skills/task-keep/SKILL.md

One physical copy may serve multiple agents when they officially discover the same directory. Do not create redundant copies unless an agent requires its own location.

Ensure every installed copy starts with valid skill metadata. If the source already contains equivalent YAML frontmatter, preserve it. Otherwise, prepend this metadata to the local copy:

---
name: task-keep
description: Use when past work may help with the current task, or when meaningful completed, failed, or unfinished work should be preserved for a future agent.
---

In every installed copy, make the resolved data root unambiguous by adding or updating this local-only managed section with absolute paths:

<!-- task-keep:storage:start -->
## Local Task Keep storage

Use only the following storage locations for this installation:

- Data root: `<ABSOLUTE_TASK_KEEP_DATA_ROOT>`
- Work history: `<ABSOLUTE_TASK_KEEP_DATA_ROOT>/worklog/YYYY.jsonl`
- Detailed references: `<ABSOLUTE_TASK_KEEP_DATA_ROOT>/requests/`

Do not create or use another Task Keep data location unless the user explicitly changes it.
<!-- task-keep:storage:end -->

Modify only the locally installed copies. Do not write a machine-specific absolute path back into the cloned repository.

4. Add persistent invocation instructions

Determine the project root or workspace root the user wants Task Keep to cover.

Before creating a file, inspect the instruction files that each detected agent actually loads. Creating a higher-precedence file can accidentally hide an existing lower-precedence file even when no content is deleted. Preserve both the files and the effective instruction chain.

Use these precedence notes:

Agent	Instruction handling
Codex	Use the effective AGENTS.override.md when one is active at the target level; otherwise use AGENTS.md.
Claude Code	Use CLAUDE.md. It may import the shared AGENTS.md with @AGENTS.md.
Google Antigravity CLI (agy)	Use the effective project AGENTS.md.
Hermes	Check .hermes.md or HERMES.md first, then AGENTS.md, then CLAUDE.md; update the context file Hermes will actually load.
OpenClaw	Use the configured workspace AGENTS.md, not an unrelated Git repository root.
OpenCode	Check local AGENTS.md before CLAUDE.md. Do not create AGENTS.md blindly if doing so would hide required instructions from an existing CLAUDE.md.
Grok Build	Use the effective project instruction chain; Grok can read both the AGENTS.md and Claude-compatible families.

Use AGENTS.md as the shared default when doing so does not hide existing instructions. When the effective file already exists, preserve all current content. When no applicable instruction file exists, create the documented default for that agent.

Insert or update exactly one managed block:

<!-- task-keep:start -->
1) When past work history needs to be searched or consulted, use the task-keep skill to retrieve it.
2) Before ending work, use the task-keep skill to record any completed deliverable, completed change, final confirmed failure, unfinished work, or completed user mission.
<!-- task-keep:end -->

For Claude Code:

• If CLAUDE.md already imports AGENTS.md, make no additional Task Keep insertion in CLAUDE.md.
• If AGENTS.md contains the managed block and CLAUDE.md exists, add @AGENTS.md only when that import is missing.
• If CLAUDE.md does not exist, create it with @AGENTS.md.
• Preserve all existing Claude-specific instructions.

If importing or creating AGENTS.md would change another agent's precedence and hide existing instructions, stop and reconcile the instruction chain before continuing. Do not trade a successful Task Keep installation for the loss of unrelated project guidance.

The start and end comments are installer markers. On reinstall, replace only the content between matching markers. Never duplicate the block.

5. Verify the installation

Before reporting success:

1. Confirm that every installed SKILL.md exists and is readable.
2. Confirm that all installed copies point to the same absolute Task Keep data root.
3. Confirm that the current and previous year JSONL files exist.
4. Confirm that the managed instruction block appears exactly once in each detected agent's effective instruction chain.
5. Confirm that every detected agent can reach the managed block through the instruction file it actually loads, including Claude Code through CLAUDE.md.
6. Use each detected agent's inspection or skill-listing command when available.
7. Report which agents were detected, which were installed, every path changed, and anything that still requires user action.

Do not claim that an undetected or unverified agent was installed successfully.

Manual installation

If you prefer to install Task Keep yourself:

1. Choose the OS-standard permanent data root from the table above. Do not use the project or agent installation directory.
2. Create worklog/<current-year>.jsonl, worklog/<previous-year>.jsonl, and requests/ under that root.
3. Copy SKILL.md into the appropriate task-keep/SKILL.md directory from the table above.
4. Add the local storage section to the installed copy with the absolute data paths.
5. Add the managed Task Keep block to the effective project or workspace instruction file, normally AGENTS.md.
6. For Claude Code, create or update CLAUDE.md so it imports AGENTS.md.
7. Restart the agent if it does not detect newly created top-level skill directories during the current session.

What Task Keep stores

Task Keep writes one concise JSON object per meaningful work item to worklog/YYYY.jsonl. A record contains the searchable project name, the verified absolute project root when available, the request, outcome, important decisions or failures, validation, remaining work, artifact paths, and search keywords.

Long details are optional and belong in requests/ only when a concise record would lose information that a future agent genuinely needs.

Task Keep must never store secrets, tokens, passwords, private keys, session cookies, or unnecessary personal data.

What Task Keep is not

• It is not a full conversation archive.
• It is not a database service.
• It is not a replacement for an agent's built-in memory.
• It does not treat old records as current truth.
• It does not record every answer, edit, or failed attempt.

Its job is narrower: keep enough meaningful work history that the next agent does not have to start from zero.

Data ownership

Task Keep data is plain JSONL and Markdown stored on the user's machine. Back it up like any other important local work data. You can inspect, edit, move, or delete it with ordinary file tools.