Skip to main content

Memory skill

Memory Skill

Use AI DevKit memory as a durable knowledge layer for reusable project context.

On this page

Install command

AI DevKit installs its built-in skills as one curated set. Run this once to install memory with the rest of the built-in workflow skills.

bash
npx ai-devkit@latest skill add --built-in

What it does

Use memory when an agent should search, save, or update durable knowledge instead of relying on chat history. It is useful for recurring project facts, hard-won fixes, reusable workflows, and verified implementation notes.

When to use it

  • Search reusable project context before non-trivial work
  • Save verified knowledge that future agents should reuse
  • Update stale memory entries when project behavior changes

Supported agents

  • Claude Code
  • Codex
  • Cursor
  • opencode

The SKILL.md file

This is what your agent reads when the skill runs. View it on GitHub (opens in a new tab)

Use npx ai-devkit@latest memory ... as the durable knowledge layer.

Workflow#

  1. For implementation, debugging, review, planning, or documentation tasks, search before deep work unless the task is trivial:

    bash
    npx ai-devkit@latest memory search --query "<task, subsystem, error, or convention>" --limit 5
    

    For broad or risky tasks, search multiple angles: subsystem, error text, framework, command, and task intent.

  2. Use results as context:

    • Trust repo files, tests, fresh command output, and explicit user instructions over memory.
    • If memory conflicts with verified evidence, use the evidence and update the stale memory.
    • Mention memory only when it changes the plan or avoids asking the user again.
  3. Search before storing:

    bash
    npx ai-devkit@latest memory search --query "<knowledge to store>" --table
    
  4. Store or update only after the quality gate passes.

Quality Gate#

Before storing, all must be true:

  • Future sessions are likely to reuse it.
  • It is verified by code, docs, tests, command output, or explicit user instruction.
  • It is not merely a restatement of obvious nearby files unless it prevents repeated agent mistakes.
  • It is scoped narrowly enough.
  • Existing memory does not already cover it.
  • It contains no secrets, credentials, private customer data, personal data, raw logs, or temporary paths.

Store:

  • Project conventions, user preferences, durable decisions.
  • Reusable fixes, testing patterns, commands, setup gotchas.
  • Non-obvious constraints, architecture rules, failure patterns.

Do not store:

  • Task progress, transcripts, speculation, generic programming facts.
  • Raw errors without diagnosis.
  • Anything the user did not intend to persist.

Commands#

bash
npx ai-devkit@latest memory search \
  --query "<query>" \
  --tags "<tags>" \
  --scope "<scope>" \
  --limit 5

Use --table to get IDs for updates:

bash
npx ai-devkit@latest memory search --query "<query>" --table

Options: --query/-q required; --tags; --scope/-s; --limit/-l from 1-20; --table.

Store#

bash
npx ai-devkit@latest memory store \
  --title "<actionable title, 10-100 chars>" \
  --content "<context, guidance, evidence, exceptions>" \
  --tags "<lowercase,tags>" \
  --scope "<global|project:name|repo:org/repo>"

Use this content shape when helpful:

text
Context: Where this applies.
Guidance: What to do.
Evidence: File, command, test, or user instruction.
Exceptions: When not to apply it.

Update#

Find the ID with search --table, then update only changed fields:

bash
npx ai-devkit@latest memory update \
  --id "<memory-id>" \
  --title "<updated title>" \
  --content "<updated content>" \
  --tags "<replacement,tags>" \
  --scope "<updated scope>"

--tags replaces all existing tags.

Scoping#

Use the narrowest useful scope:

  • repo:<org/repo> for one repository.
  • project:<name> for one app, product, or workspace.
  • global only for knowledge that applies across unrelated projects.

If unsure, use a narrower scope.

Troubleshooting#

  • CLI missing: run npx ai-devkit@latest --version.
  • Duplicate title: search, then update the existing item if it is the same knowledge.
  • Empty results: broaden terms, remove filters, or search symptoms and subsystem names separately.
  • Validation error: check title/content lengths, query length, and --limit range.
  • DB path: default is ~/.ai-devkit/memory.db; project config can override it automatically.
esc