A personal AI assistant that remembers. Nuggets combines holographic memory with a multi-channel messaging gateway so your AI actually learns from conversations — facts recalled often get promoted to permanent memory, and everything persists across restarts.

LLM agents forget everything between sessions. RAG systems fix this but need vector databases, embedding APIs, and infrastructure. Nuggets takes a different approach:

• Holographic memory — facts are stored as superposed complex-valued vectors using Holographic Reduced Representations (HRR). Recall is algebraic, sub-millisecond, and runs locally with zero external dependencies.
• Self-improving — when a fact is recalled 3+ times across sessions, it gets promoted to permanent context. The agent gets faster and cheaper over time.
• Proactive — the assistant doesn't just respond. It checks in periodically, runs scheduled tasks, and sends reminders — all through the same Telegram or WhatsApp chat.

Think of it as an AI that lives in your pocket, remembers what matters, and reaches out when it has something useful to say.

The core of the system. Pure TypeScript, zero dependencies.

Each "nugget" is a topic-scoped memory (e.g., learnings, preferences, project). Facts are key-value pairs compressed into a fixed-size complex vector via HRR binding. Multiple facts superpose into one mathematical object but remain individually retrievable.

• remember — bind a key-value pair into the holographic vector
• recall — unbind a query and decode via cosine similarity (~1ms)
• forget — subtract a binding from the superposition
• promote — facts recalled 3+ times get written to MEMORY.md for permanent context

Storage is a simple JSON file per nugget at ~/.nuggets/. Vectors are never serialized — they're rebuilt deterministically from a seeded PRNG, so the files stay tiny.

A multi-channel message router that connects your AI to Telegram and WhatsApp.

• Process pool — one Pi subprocess per user, reused across messages, reaped after 5 min idle
• JSONL RPC — communicates with Pi via stdin/stdout, no sockets or HTTP
• Message queue — serializes concurrent messages per user to prevent race conditions
• Heartbeat — checks in every 30 min during waking hours. If there's nothing to say, it stays quiet
• Cron scheduler — 5-field cron expressions for recurring messages, reminders, and one-shot timers
• Quiet hours — no proactive messages between 10 PM and 8 AM (configurable)

Hooks into the Pi agent lifecycle:

• nuggets.ts — gives Pi a nuggets tool for remember/recall/forget, auto-captures file paths and user preferences from conversation, injects memory into system prompt
• proactive.ts — gives Pi a schedule tool so it can create reminders and recurring tasks on its own

• Node.js 18+
• Pi — the AI coding agent that powers the assistant. Install globally:

  npm install -g @mariozechner/pi-coding-agent

• An Anthropic API key (the Max plan does not work — Anthropic blocked third-party OAuth in Jan 2026)
• A Telegram bot token (from @BotFather)
• Your Telegram chat ID (from @userinfobot)

npm install -g @mariozechner/pi-coding-agent   # install Pi (if not already)
git clone https://github.com/NeoVertex1/nuggets.git
cd nuggets
npm install
npm run setup
npm run dev

npm run setup walks you through configuration interactively:

  Nuggets Setup Wizard
  ====================

  ── AI Provider ──────────────────────────────────────

  Note: Anthropic Max plan does NOT work (third-party OAuth
  was blocked Jan 2026). You need an API key from:
  https://console.anthropic.com/

  Paste your sk-ant-... key:
  Anthropic API key: sk-ant-api03-...

  ── Telegram ─────────────────────────────────────────

  Create a bot via @BotFather on Telegram, paste the token:
  Bot token: 123456789:AAF...

  Send /start to @userinfobot on Telegram to get your chat ID:
  Chat ID: 987654321

  ── WhatsApp (optional) ──────────────────────────────

  Your JID (e.g. [email protected]) — press Enter to skip:
  WhatsApp JID:

  ── Pi Model (optional) ──────────────────────────────

  Model ID (press Enter for Pi's default):
  Model:

  ✓ .env written successfully.

  Ready! Run `npm run dev` to start.

The wizard validates inputs (API key format, token format, numeric chat ID), shows masked current values if .env already exists, and writes the file atomically.

1. Bot token — open Telegram, search for @BotFather, send /newbot, follow the prompts. You'll get a token like 123456789:AAF7_NRCOM2nxZt...
2. Chat ID — search for @userinfobot, send /start. It replies with your numeric chat ID.
3. Run npm run setup, paste both values, and you're done.

You (Telegram/WhatsApp)
  │
  ▼
Gateway ── router ── message queue (per user)
  │                      │
  ├── heartbeat          ▼
  ├── cron          Pi subprocess (JSONL RPC)
  │                      │
  │                 ┌────┴─────┐
  │              nuggets    schedule
  │              extension  extension
  │                 │          │
  │            ~/.nuggets/   .gateway/cron/
  │           (HRR memory)  (job store)
  │                 │
  │            promoteFacts()
  │                 │
  │            MEMORY.md
  │         (permanent context)
  ▼
EventQueue ◄── cron fires ── "0 9 * * *"
           ◄── heartbeat ─── every 30 min
           ◄── timer ──────── one-shot

Message flow: You send a message → gateway routes it to your Pi process → Pi checks nuggets memory for context → Pi responds → gateway delivers the reply.

Proactive flow: Heartbeat timer fires → Pi checks memory for anything worth following up on → if yes, sends you a message. If not, stays silent.

Memory promotion: After enough sessions, facts that keep getting recalled (3+ times) are promoted from holographic memory to MEMORY.md, where they become permanent context for every future session.

src/
  nuggets/              Memory engine (pure TypeScript, zero deps)
    core.ts             HRR math: bind, unbind, orthogonalize, sharpen
    memory.ts           Nugget class: remember, recall, forget
    shelf.ts            NuggetShelf: multi-nugget manager
    promote.ts          MEMORY.md promotion (3+ recall threshold)
    index.ts            Public API

  gateway/              Messaging gateway
    main.ts             Entry point — wires everything together
    config.ts           Environment config + helpers
    router.ts           Message routing + proactive event handling
    pi-rpc.ts           Pi subprocess communication (JSONL RPC)
    pi-pool.ts          Per-user process pool with idle eviction
    telegram.ts         Telegram bot (grammY)
    whatsapp.ts         WhatsApp client (Baileys)
    event-queue.ts      Proactive event bus
    cron.ts             5-field cron scheduler + request file watcher
    heartbeat.ts        Per-user periodic check-ins

  setup.ts              Interactive setup wizard

.pi/extensions/
  nuggets.ts            Memory tool + auto-capture + system prompt injection
  proactive.ts          Schedule tool + cron file bridge

npm test

Tests cover HRR math (bind/unbind accuracy, orthogonalization), nugget operations (remember/recall/forget lifecycle), and shelf management.

MIT