Skip to main content
The graph layer lives in ~/.nuggets/graph/graph.json and is shared across all nuggets in the same saveDir. All types below are exported from src/nuggets/graph.ts and re-exported through src/nuggets/index.ts.

​
MemoryNote

The primary record type. Every fact and free-form note in the graph is a MemoryNote. 
export interface MemoryNote extends NoteMetadata {
  id: string;
  nuggetName: string;
  title: string;
  content: string;
  tags: string[];
  links: NoteLink[];
  vector: NoteVectorSpec;
  hidden: boolean;
  kind: "fact" | "note";
  sourceKey?: string;
  hits: number;
  lastHitSession: string;
  createdAt: string;
  updatedAt: string;
  lastAccessedAt: string;
  lastRewrittenAt?: string;
  archivedAt?: string;
}
​
id
string
required
Globally unique identifier in the form fact-<nuggetName>-<8-char-uuid> or note-<nuggetName>-<8-char-uuid>.
​
nuggetName
string
required
Name of the nugget that owns this note. Immutable after creation.
​
title
string
required
Human-readable title. For fact-kind notes this is the fact key.
​
content
string
required
Note body or fact value. Whitespace is normalised on write.
​
tags
string[]
required
Lower-cased, hyphenated tags. Always includes <nuggetName>, scope:<scope>, and type:<type> system tags.
​
links
NoteLink[]
required
Outbound links to other notes. See NoteLink.
​
vector
NoteVectorSpec
required
FHRR vector specification used for similarity search. See NoteVectorSpec.
​
hidden
boolean
required
true when the note has been soft-deleted. Hidden notes are excluded from search and listNotes by default.
​
kind
"fact" | "note"
required
"fact" for notes mirrored from the FHRR fact store. "note" for free-form notes created with createNote.
​
sourceKey
string
The original fact key for fact-kind notes. undefined for free-form notes.
​
hits
number
required
Number of times this note has been recalled across distinct sessions.
​
lastHitSession
string
required
Session ID of the most recent hit. Empty string if never recalled.
​
createdAt
string
required
ISO 8601 timestamp of when the note was first created.
​
updatedAt
string
required
ISO 8601 timestamp of the most recent write.
​
lastAccessedAt
string
required
ISO 8601 timestamp of the most recent read or recall.
​
lastRewrittenAt
string
ISO 8601 timestamp of the most recent reflection rewrite, if any.
​
archivedAt
string
ISO 8601 timestamp set when the note is soft-deleted. undefined while the note is visible.
In addition, MemoryNote extends NoteMetadata, so every note also carries subject, scope, type, source, confidence, and stability.

​
NoteMetadata

Semantic metadata attached to every note and inferred automatically from the key, content, and tags when not supplied explicitly. 
export interface NoteMetadata {
  subject: string;
  scope: MemoryScope;
  type: MemoryType;
  source: MemorySource;
  confidence: number;
  stability: MemoryStability;
}
​
subject
string
required
Semantic owner of this memory. Common values: "user:primary", "assistant:self", "shared:project", "session:current".
​
scope
MemoryScope
required
Visibility scope. See MemoryScope.
​
type
MemoryType
required
Categorisation of what kind of memory this is. See MemoryType.
​
source
MemorySource
required
How this memory was acquired. See MemorySource.
​
confidence
number
required
Degree of certainty in the content, in the range [0, 1]. Clamped to valid range on write.
​
stability
MemoryStability
required
Whether the memory is expected to persist across sessions. See MemoryStability.

​
MemoryScope

export type MemoryScope = "self" | "user" | "shared" | "project" | "session";
ValueMeaning
"self"Belongs to the assistant’s own model or persona.
"user"Belongs to the primary user (preferences, personal details).
"shared"Shared between assistant and user, or cross-cutting context.
"project"Scoped to the current repository or project.
"session"Temporary, valid only for the current session.
You can set the scope explicitly on a fact key using a prefix: user:, self:, shared:, project:, or session:. Without a prefix, Nuggets infers the scope from the key text and content.

​
MemoryType

export type MemoryType =
  | "fact"
  | "note"
  | "preference"
  | "reflection"
  | "self_model"
  | "project"
  | "relationship"
  | "style";
ValueMeaning
"fact"A short key-value fact from the FHRR store.
"note"A free-form note created with createNote.
"preference"A user or assistant preference.
"reflection"A note generated during a reflection pass.
"self_model"Information about the assistant’s own behaviour or identity.
"project"Project-level context such as architecture or conventions.
"relationship"A relationship between two entities.
"style"A style guideline or coding convention.

​
MemorySource

export type MemorySource =
  | "explicit_user"
  | "agent_reflection"
  | "tool_observation"
  | "inferred"
  | "system";
ValueMeaning
"explicit_user"The user directly stated this information.
"agent_reflection"The agent derived this during a reflection pass.
"tool_observation"Observed from a tool call (file reads, edits, etc.).
"inferred"Inferred from context, lower confidence.
"system"Injected by the system or infrastructure.

​
MemoryStability

export type MemoryStability = "temporary" | "durable";
ValueMeaning
"temporary"Expected to expire or become irrelevant after the current session. Used automatically for session-scoped notes and keys prefixed with _, tmp, or scratch.
"durable"Expected to remain relevant across sessions. The default for most notes.
A directed link from one note to another, stored on both endpoints when created through addLink. 
export interface NoteLink {
  to: string;
  reason: string;
  createdAt: string;
}
​
to
string
required
ID of the target note.
​
reason
string
required
Human-readable description of the relationship.
​
createdAt
string
required
ISO 8601 timestamp of when the link was created.

​
NoteVectorSpec

The FHRR vector representation of a note, stored in the graph and used for semantic similarity search. 
export interface NoteVectorSpec {
  seed: number;
  basis: string[];
}
​
seed
number
required
Numeric seed derived from the basis string length. Used as a quick identity hash.
​
basis
string[]
required
Up to 20 string tokens representing the note’s semantic basis (title tokens, content tokens, tag tokens, link tokens, and metadata tokens such as kind:fact or scope:user). The vector is reconstructed from these tokens on demand.

​
GraphNoteMetaInput

Input type for supplying optional metadata when creating or updating notes. Any field you omit is inferred automatically. 
export interface GraphNoteMetaInput {
  subject?: string;
  scope?: MemoryScope;
  type?: MemoryType;
  source?: MemorySource;
  confidence?: number;
  stability?: MemoryStability;
}
​
subject
string
Override the inferred subject.
​
scope
MemoryScope
Override the inferred scope.
​
type
MemoryType
Override the inferred memory type.
​
source
MemorySource
Override the inferred source.
​
confidence
number
Override the inferred confidence. Clamped to [0, 1].
​
stability
MemoryStability
Override the inferred stability.
nugget.remember("project:deploy-cmd", "pnpm deploy", {
  source: "explicit_user",
  stability: "durable",
  confidence: 1.0,
});

​
NoteFilterOptions

Filter options accepted by listNotes and searchNotes. 
export interface NoteFilterOptions {
  includeHidden?: boolean;
  subject?: string;
  scope?: MemoryScope;
  type?: MemoryType;
}
​
includeHidden
boolean
default:"false"
When true, soft-deleted (hidden) notes are included in the results.
​
subject
string
Return only notes whose subject exactly matches this string.
​
scope
MemoryScope
Return only notes with this scope.
​
type
MemoryType
Return only notes of this type.
// List all durable project notes including archived ones
nugget.listNotes({
  includeHidden: true,
  scope: "project",
  type: "note",
});

​
SearchNotesResult

A single result item returned by searchNotes. 
export interface SearchNotesResult {
  note: MemoryNote;
  score: number;
  vectorScore: number;
  textScore: number;
}
​
note
MemoryNote
required
The matching note.
​
score
number
required
Combined relevance score after softmax re-ranking. Range [0, 1]. Results are sorted by this value descending.
​
vectorScore
number
required
Cosine similarity contribution from the FHRR vector, normalised to [0, 1]. Weighted at 42% of the final score.
​
textScore
number
required
Text overlap contribution. Based on exact phrase match and token overlap against title, content, tags, subject, scope, and type. Weighted at 48% of the final score.

Build docs developers (and LLMs) love

Get started for freeTalk to us