Skip to main content
The nuggets CLI is the fastest way to interact with the memory system from scripts, CI pipelines, and AI agent hooks.
Follow the recall-first pattern: check memory before doing an expensive search, then save what you find.

​
nuggets remember

nuggets remember <nugget> <key> <value>
Stores or updates a fact in the named nugget. If the nugget does not exist it is created automatically. If a fact with the same key already exists, its value is overwritten. Arguments
​
nugget
string
required
Name of the target nugget.
​
key
string
required
Lookup key for the fact. Use a scoped prefix (user:, self:, shared:, project:, session:) to set the memory scope explicitly. Without a prefix, the scope is inferred automatically.
​
value
string
required
Value to store. Quote multi-word values.
# Store a file location
nuggets remember locations "shared:auth-handler" "src/auth/middleware.ts:47"

# Store a command
nuggets remember project "shared:test-cmd" "pnpm test"

# Store a user preference
nuggets remember prefs "user:indent" "2 spaces, no semicolons"

# Store a bug fix note
nuggets remember debug "shared:cors-error" "add origin to allowlist in config.ts"

​
nuggets recall

nuggets recall <query> [--nugget <name>]
Searches memory for a fact matching the query. Without --nugget, all nuggets are searched and the result with the highest confidence is returned. Arguments
​
query
string
required
Query string. The engine tries exact match, substring containment, then fuzzy sequence matching.
Flags
​
--nugget
string
Restrict the search to a single named nugget.
Output format 
Found: shared:auth-handler
Value: src/auth/middleware.ts:47
Confidence: 0.97  Margin: 0.43
Nugget: locations
When nothing is found: 
Not found.

# Search all nuggets
nuggets recall "auth handler"

# Search a specific nugget
nuggets recall "test command" --nugget project

​
nuggets forget

nuggets forget <nugget> <key>
Removes a fact from the named nugget and deletes its associated graph note. Arguments
​
nugget
string
required
Name of the nugget to modify.
​
key
string
required
Key of the fact to remove. The match is case-insensitive.
nuggets forget debug "shared:cors-error"

​
nuggets list

nuggets list
Lists all nuggets in the default save directory (~/.nuggets) with a summary of each. Output format 
Nugget: locations
  Facts: 12  Notes: 14  Capacity: 3.2%

Nugget: project
  Facts: 8  Notes: 10  Capacity: 2.1%

Nugget: prefs
  Facts: 5  Notes: 5  Capacity: 1.3%

nuggets list

​
nuggets facts

nuggets facts <nugget>
Lists all facts stored in the named nugget. Arguments
​
nugget
string
required
Name of the nugget to inspect.
Output format 
Nugget: project  (8 facts)

  shared:test-cmd        pnpm test
  shared:auth-handler    src/auth/middleware.ts:47
  user:indent            2 spaces, no semicolons

nuggets facts project

​
Recall-first workflow

The recommended agent pattern:
1

Ask memory first

nuggets recall "what you need"
Use the result directly if confidence is high enough.
2

Do the expensive work if needed

Search files, call APIs, or run tools only when memory doesn’t have a good answer.
3

Save what you discover

nuggets remember <nugget> "<key>" "<value>"
Short, one-line facts go here.
4

Use the graph layer for richer context

When the information is longer than one line or should link to other notes, use the programmatic API to call createNote and addLink instead.

Build docs developers (and LLMs) love

Get started for freeTalk to us