Memory

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

Search

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

Use --table to get IDs for updates:

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

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

Store

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:

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:

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.