NuggetShelf is the recommended entry point when your application works with more than one nugget. It owns the nugget lifecycle (create, load, remove) and fans out recall and search queries across all managed nuggets automatically.
Constructor
new NuggetShelf(opts?: {
saveDir?: string;
autoSave?: boolean;
})
opts.saveDir
string
default:"~/.nuggets"
Directory where nugget files and the graph are stored. All nuggets created by this shelf share the same saveDir.
Passed through to every nugget created or loaded by this shelf.
import { NuggetShelf } from "./src/nuggets/index.js";
const shelf = new NuggetShelf({ saveDir: "~/.nuggets" });
shelf.loadAll(); // restore any previously saved nuggets
Properties
The directory used for all nugget files on this shelf. Read-only.
Whether auto-save is enabled for all nuggets. Read-only.
The number of nuggets currently held on the shelf.
Nugget lifecycle
create
create(
name: string,
opts?: { D?: number; banks?: number; ensembles?: number },
): Nugget
Nugget and registers it on the shelf. Throws if a nugget with that name already exists.
Unique name for the nugget.
FHRR vector dimensionality.
Number of ensemble copies.
Nugget instance.
const prefs = shelf.create("prefs");
prefs.remember("user:theme", "dark");
get
get(name: string): Nugget
Name of the nugget to retrieve.
const prefs = shelf.get("prefs");
console.log(prefs.facts());
getOrCreate
getOrCreate(name: string): Nugget
Name of the nugget to retrieve or create.
const locations = shelf.getOrCreate("locations");
locations.remember("shared:auth-handler", "src/auth/middleware.ts:47");
has
has(name: string): boolean
true if a nugget with the given name is registered on the shelf.
if (!shelf.has("debug")) {
shelf.create("debug");
}
remove
remove(name: string): void
.nugget.json file, and removes all of its graph notes. Throws if the nugget does not exist.
remove() permanently deletes the nugget file and all associated notes. This cannot be undone.
Name of the nugget to remove.
list
list(): Array<ReturnType<Nugget["status"]>>
status() object for every registered nugget.
for (const info of shelf.list()) {
console.log(`${info.name}: ${info.fact_count} facts, ${info.note_count} notes`);
}
loadAll
Scans saveDir for *.nugget.json files and loads each one into the shelf. Files that cannot be parsed are silently skipped. Call this once at startup to restore a previous session.
const shelf = new NuggetShelf();
shelf.loadAll();
console.log(shelf.size); // number of nuggets restored
saveAll
Calls save() on every registered nugget. Useful when autoSave is disabled and you want a single explicit flush.
const shelf = new NuggetShelf({ autoSave: false });
// ... batch operations ...
shelf.saveAll();
Fact methods
remember
remember(
nuggetName: string,
key: string,
value: string,
noteMeta?: GraphNoteMetaInput,
): void
Optional metadata for the mirrored graph note.
shelf.remember("project", "shared:test-cmd", "pnpm test");
recall
recall(
query: string,
nuggetName?: string,
sessionId?: string,
): ReturnType<Nugget["recall"]> & { nugget_name: string | null }
nuggetName is provided, the search is scoped to that nugget. Otherwise, every nugget is queried and the result with the highest confidence is returned.
Query string passed to each nugget’s recall.
Restrict the search to this nugget. Throws if the nugget does not exist.
Session identifier for hit tracking.
Name of the nugget that produced the winning result, or null if nothing was found.
// Search all nuggets
const result = shelf.recall("test command");
console.log(result.answer, result.nugget_name);
// Search one nugget
const result2 = shelf.recall("test-cmd", "project");
forget
forget(nuggetName: string, key: string): boolean
true if the fact was removed, false if not found.
shelf.forget("project", "shared:test-cmd");
Note methods
createNote
createNote(
nuggetName: string,
title: string,
content: string,
tags?: string[],
meta?: GraphNoteMetaInput,
): MemoryNote
shelf.createNote("project", "Deploy checklist", "Run pnpm build, then push.", ["deploy"]);
editNote
editNote(
nuggetName: string,
noteId: string,
newContent: string,
updates?: {
tags?: string[];
title?: string;
hidden?: boolean;
rewrittenAt?: string;
noteMeta?: GraphNoteMetaInput;
},
): MemoryNote | null
Nugget.editNote.
shelf.editNote("project", "note-project-a1b2c3d4", "Updated deploy steps.");
addLink
addLink(
nuggetName: string,
note1: string,
note2: string,
reason: string,
): boolean
shelf.addLink("project", "Deploy checklist", "CORS fix", "both affect production");
searchNotes
searchNotes(
query: string,
nuggetName?: string,
limit?: number,
opts?: NoteFilterOptions,
): Array<SearchNotesResult & { nugget_name: string }>
limit is applied.
Restrict the search to this nugget.
Maximum number of results.
SearchNotesResult items each augmented with nugget_name: string.
const results = shelf.searchNotes("CORS");
for (const { note, score, nugget_name } of results) {
console.log(`[${nugget_name}] ${note.title} (${score.toFixed(3)})`);
}
listNotes
listNotes(
nuggetName?: string,
opts?: NoteFilterOptions,
): Array<MemoryNote & { nugget_name: string }>
nugget_name field.
// All notes on the shelf
const all = shelf.listNotes();
// Notes from a specific nugget
const projectNotes = shelf.listNotes("project");
reflectAndCleanMemory
reflectAndCleanMemory(
nuggetName?: string,
limit?: number,
): ReflectionResult
reflectAndCleanMemory for full details.
Restrict the pass to this nugget. Omit to process all nuggets.
Maximum number of notes to inspect. Capped at 10.
ReflectionResult.
const result = shelf.reflectAndCleanMemory();
console.log(`Inspected ${result.inspected}, merged ${result.merged}, tagged ${result.tagged}`);
