Skip to main content
Nuggets is a personal AI assistant that remembers. It combines fast local FHRR memory, a living note graph, and a multi-channel messaging gateway so your assistant can learn from conversations, reorganize its own memory, and keep working across restarts. Most agents forget between sessions. RAG fixes that, but it usually means embeddings, a vector database, and extra infrastructure. Nuggets takes a lighter approach: pure TypeScript, local JSON storage, and algebraic memory math that runs in under a millisecond.

​
The three memory layers

Nuggets separates memory into three cooperating layers:
LayerBest forStorage
FHRR factsShort key-value facts recalled by query.nugget.json files
Note graphRich notes with titles, tags, links, and context~/.nuggets/graph/graph.json
MEMORY.mdPermanent, high-value knowledgePromoted from the note graph
All memory is local. No cloud database, no embeddings API — just fast algebraic math and JSON files on your machine.

​
Key features

FHRR fact memory

Short facts are stored as phase-based complex vectors and recalled algebraically in about a millisecond. No embeddings or vector database required.

Living note graph

Richer memory lives in a Zettelkasten-style graph with titles, content, tags, links, and deterministic FHRR vectors. Graph search uses both text overlap and FHRR similarity.

Autonomous rewriting

The assistant runs a daily cleanup pass that merges near-duplicates, improves tags, adds related links, and archives low-value notes — without any manual intervention.

Multi-channel gateway

Connect Telegram, WhatsApp, and Discord to a single AI backend. The proactive system handles heartbeat follow-ups, cron reminders, and scheduled maintenance.

Backend modes

Choose between Pi, Codex CLI, or a local OpenAI-compatible server (Ollama, MLX). Switch backends without changing your memory data.

Skills

Skills live in a Nuggets-owned registry at skills/<id>/. Each skill has a skill.json for metadata and a SKILL.md for instructions. Manage sticky skills in chat with /skills, /skill use, and /skill remove.

​
Architecture

src/
  nuggets/
    core.ts
    memory.ts
    graph.ts
    rewrite.ts
    shelf.ts
    promote.ts
    index.ts

  gateway/
    main.ts
    config.ts
    agent-pool.ts
    agent-session.ts
    router.ts
    pi-rpc.ts
    codex-rpc.ts
    local-model-rpc.ts
    telegram.ts
    discord.ts
    whatsapp.ts
    event-queue.ts
    cron.ts
    heartbeat.ts

.pi/extensions/
  nuggets.ts
  proactive.ts

skills/
  nuggets-memory/
  reviewer/
  planner/
  debugger/
  researcher/

​
How it flows

You (Telegram / WhatsApp / Discord)
  │
  ▼
Gateway → router → backend session
  │                    │
  │                    ▼
  │              Nuggets memory stack
  │              ├─ FHRR facts
  │              ├─ graph notes
  │              └─ rewrite pass
  │
  ├─ heartbeat
  ├─ cron reminders
  └─ daily memory reflection
Normal path:
  1. You send a message.
  2. The backend answers and can query Nuggets first.
  3. Useful facts or notes get stored.
  4. High-value notes are promoted to MEMORY.md.
Proactive path:
  1. A heartbeat or cron fires.
  2. The agent checks if it should message you.
  3. A silent maintenance job can also trigger reflectAndCleanMemory.

Get started

Install Nuggets and send your first message in under five minutes.

Build docs developers (and LLMs) love

Get started for freeTalk to us