Nugget Class

new Nugget(opts: {
  name: string;
  D?: number;
  banks?: number;
  ensembles?: number;
  autoSave?: boolean;
  saveDir?: string;
  maxFacts?: number;
})

remember(key: string, value: string, noteMeta?: GraphNoteMetaInput): void

const nugget = new Nugget({ name: "project" });
nugget.remember("user:preferred-language", "TypeScript");
nugget.remember("shared:test-command", "pnpm test", { type: "preference" });

recall(
  query: string,
  sessionId?: string,
): { answer: string | null; confidence: number; margin: number; found: boolean; key: string }

const result = nugget.recall("preferred-language", "session-abc");
if (result.found) {
  console.log(result.answer);     // "TypeScript"
  console.log(result.confidence); // e.g. 0.97
  console.log(result.margin);     // e.g. 0.42
}

forget(key: string): boolean

const removed = nugget.forget("user:preferred-language");
console.log(removed); // true

facts(): Array<{ key: string; value: string; hits: number }>

for (const fact of nugget.facts()) {
  console.log(`${fact.key} = ${fact.value} (${fact.hits} hits)`);
}

createNote(
  title: string,
  content: string,
  tags?: string[],
  meta?: GraphNoteMetaInput,
): MemoryNote

const note = nugget.createNote(
  "CORS fix",
  "Add the client origin to the allowlist in config.ts line 47.",
  ["bug", "cors"],
  { scope: "project", type: "note" },
);
console.log(note.id); // "note-project-a1b2c3d4"

editNote(
  noteId: string,
  newContent: string,
  updates?: {
    tags?: string[];
    title?: string;
    hidden?: boolean;
    rewrittenAt?: string;
    noteMeta?: GraphNoteMetaInput;
  },
): MemoryNote | null

const updated = nugget.editNote(
  "note-project-a1b2c3d4",
  "Add origin to allowlist in config.ts:47 and restart the server.",
  { tags: ["bug", "cors", "resolved"] },
);

updateNote(
  noteId: string,
  updates: Partial<Omit<MemoryNote, "id" | "nuggetName">>,
): MemoryNote | null

nugget.updateNote("note-project-a1b2c3d4", {
  stability: "durable",
  confidence: 0.95,
});

deleteNote(noteId: string, hard?: boolean): boolean

// Soft archive (reversible)
nugget.deleteNote("note-project-a1b2c3d4");

// Permanent removal
nugget.deleteNote("note-project-a1b2c3d4", true);

addLink(note1: string, note2: string, reason: string): boolean

nugget.addLink("CORS fix", "note-project-b5c6d7e8", "same module affected");

mergeNotes(target: string, source: string, reason: string): MemoryNote | null

const merged = nugget.mergeNotes(
  "CORS configuration",
  "CORS fix",
  "duplicate notes about the same CORS issue",
);

searchNotes(
  query: string,
  limit?: number,
  opts?: NoteFilterOptions,
): SearchNotesResult[]

const results = nugget.searchNotes("CORS", 3);
for (const { note, score } of results) {
  console.log(`${note.title} — score ${score.toFixed(3)}`);
}

listNotes(opts?: NoteFilterOptions): MemoryNote[]

// All visible notes
const notes = nugget.listNotes();

// Including archived notes
const all = nugget.listNotes({ includeHidden: true });

// Only user-scoped fact notes
const userFacts = nugget.listNotes({ scope: "user", type: "fact" });

getNote(noteId: string): MemoryNote | null

const note = nugget.getNote("note-project-a1b2c3d4");
if (note) {
  console.log(note.content);
}

clear(): void

nugget.clear();
console.log(nugget.facts()); // []

status(): {
  name: string;
  fact_count: number;
  dimension: number;
  banks: number;
  ensembles: number;
  capacity_used_pct: number;
  capacity_warning: string;
  max_facts: number;
  note_count: number;
}

const s = nugget.status();
console.log(`${s.fact_count} facts, ${s.capacity_used_pct}% capacity used`);
if (s.capacity_warning) console.warn(s.capacity_warning);

save(path?: string): string

const savedPath = nugget.save();
console.log(`Saved to ${savedPath}`);

// Save to a custom path
nugget.save("/tmp/backup.nugget.json");

static load(path: string, opts?: { autoSave?: boolean }): Nugget

const nugget = Nugget.load("~/.nuggets/project.nugget.json");
console.log(nugget.facts());