Skip to main content
Most agents forget between sessions. RAG (retrieval-augmented generation) solves this, but it typically requires embeddings, a vector database, and external infrastructure to run. Nuggets takes a lighter approach: pure TypeScript, local JSON storage, and algebraic memory math that runs without any network calls. Instead of one large retrieval store, Nuggets splits memory into three layers with different speeds, capacities, and lifetimes.

​
The three layers

LayerMechanismSpeedBest forStorage
FHRR fact memoryPhase-based complex vectors~1 msShort key-value facts recalled by query~/.nuggets/<name>.nugget.json
Note graphZettelkasten-style JSON graphFastRich notes with titles, tags, links, and context~/.nuggets/graph/graph.json
MEMORY.mdPromoted plain-text file—Permanent, high-value knowledgeProject memory directory
All three layers are entirely local. There is no cloud database, no embeddings API, and no external service required.

​
How the layers work together

The three layers form a pipeline from fast but shallow to slower but richer:
1

Recall first

Before searching code or files, query memory with nuggets recall "what you're looking for". If the answer is in the fact layer, you get it back in under a millisecond. If the fact layer misses, the agent can fall back to a graph search.
2

Store what you learn

When the agent discovers something worth keeping, it stores a short fact with nuggets remember or creates a note in the graph when the information is too rich for a single key-value pair.
3

Let the graph grow

Notes accumulate over sessions. Each note carries a title, content, tags, and links to related notes. The graph layer handles context that would be awkward to compress into a one-line fact.
4

Promote what sticks

Notes that are recalled three or more times across different sessions are automatically promoted to MEMORY.md. This file is read on every session start, so truly important knowledge becomes permanent.
5

Daily reflection cleans up

Around 9:00 AM each day, a quiet reflection pass inspects up to 10 notes. It normalizes content, merges near-duplicates, improves tags, adds links, and archives low-value notes — without any manual intervention.

​
When to use each layer

Use facts for short, atomic pieces of information that you want to retrieve by keyword:
  • File locations: nuggets remember locations "auth handler" "src/auth/middleware.ts:47"
  • Commands: nuggets remember project "test cmd" "pytest tests/ -v"
  • Patterns: nuggets remember project "error handling" "uses Result type, never throws"
  • User preferences: nuggets remember prefs "style" "2-space indent, no semicolons"
Facts stay compact on disk because the FHRR vectors are regenerated from deterministic seeds rather than stored. The tradeoff is that recall is approximate — it uses algebraic similarity, not exact text matching.
Use notes when the memory is richer than a one-line fact:
  • A durable note with a title and several sentences of context
  • Something that should link to other related notes
  • Information the agent might want to rewrite or merge later
  • Anything with useful metadata like scope, type, or stability
In Pi-backed flows, the agent gets graph tools directly: createNote, addLink, editNote, and searchNotes.
You do not write to MEMORY.md directly. The promoteFacts function handles promotion automatically when a note crosses the recall threshold (3+ hits across sessions). The file is formatted as human-readable markdown grouped by section, so you can also edit it manually if needed.

​
Recall-first pattern

Nuggets is designed around a recall-first workflow. Before doing any expensive search, always check memory: 
# 1. Ask memory first
nuggets recall "authentication middleware location"

# If the result is good enough, use it.
# If not, do the expensive search, then cache the result:
nuggets remember locations "auth handler" "src/auth/middleware.ts:47"

# If the information warrants a richer note, create one in the graph:
# (in Pi-backed flows via the createNote tool)
This pattern means that repeated questions get faster over time as facts and notes accumulate. The daily reflection pass keeps the graph tidy so stale or low-quality entries do not pile up.

​
Layer comparison

FHRR fact memory

Phase-based complex vectors, D=16384 dimensions, ~512 facts per nugget, sub-millisecond recall. No stored vectors — regenerated from seeds.

Note graph

Zettelkasten-style JSON graph with titles, tags, links, and FHRR-powered semantic search. Stores richer context than facts can hold.

Autonomous rewriting

Daily cleanup pass that merges near-duplicates, improves tags, adds links, archives low-value notes, and promotes high-hit notes to MEMORY.md.

Build docs developers (and LLMs) love

Get started for freeTalk to us