{"id":48369186,"url":"https://github.com/NeoVertex1/nuggets","last_synced_at":"2026-04-21T05:01:31.845Z","repository":{"id":344925263,"uuid":"1183723892","full_name":"NeoVertex1/nuggets","owner":"NeoVertex1","description":"First AI assistant with holographic memory","archived":false,"fork":false,"pushed_at":"2026-04-15T02:15:44.000Z","size":1810,"stargazers_count":346,"open_issues_count":0,"forks_count":19,"subscribers_count":6,"default_branch":"main","last_synced_at":"2026-04-15T04:13:23.455Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/NeoVertex1.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-03-16T22:26:10.000Z","updated_at":"2026-04-15T03:30:11.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/NeoVertex1/nuggets","commit_stats":null,"previous_names":["neovertex1/nuggets"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/NeoVertex1/nuggets","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NeoVertex1%2Fnuggets","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NeoVertex1%2Fnuggets/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NeoVertex1%2Fnuggets/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NeoVertex1%2Fnuggets/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/NeoVertex1","download_url":"https://codeload.github.com/NeoVertex1/nuggets/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NeoVertex1%2Fnuggets/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32077837,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-21T02:38:07.213Z","status":"ssl_error","status_checked_at":"2026-04-21T02:38:06.559Z","response_time":128,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-04-05T16:00:25.508Z","updated_at":"2026-04-21T05:01:31.837Z","avatar_url":"https://github.com/NeoVertex1.png","language":"TypeScript","funding_links":[],"categories":["TypeScript"],"sub_categories":[],"readme":"# Nuggets\nA 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.\n![Logo](https://github.com/NeoVertex1/nuggets/blob/d180ee6df491d2db741eed0bf254ba917a4c12e2/images/Gemini_Generated_Image_mgaktymgaktymgak.png)\n\n## New: Nuggets Memory plugin\n\nIf you want the new plugin/MCP version of Nuggets for coding agents, start here.\n\nPackage:\n- `nuggets-memory-plugin`\n\nInstall:\n```bash\nnpm install -g nuggets-memory-plugin\n```\n\nThen register it with your agent host using the host's native MCP command.\n\n### Hermes Agent\n```bash\nhermes mcp add nuggets-memory --command nuggets-memory-plugin\n```\n\n### Claude Code\n```bash\nclaude mcp add nuggets-memory -- nuggets-memory-plugin\n```\n\n### Codex\n```bash\ncodex mcp add nuggets-memory -- nuggets-memory-plugin\n```\n\nWhat the plugin is for:\n- lightweight cross-session memory nudges\n- short durable facts\n- preferences, corrections, and tiny project hints\n- MCP tools like `guide`, `nudges`, `recall`, `remember`, `list`, and `status`\n\nNotes:\n- If startup speed matters, prefer the globally installed binary above over `npx`.\n- The plugin-first workspace and release flow live in [`nuggets-memory/`](./nuggets-memory).\n- The rest of this README documents the original Nuggets app/gateway project and older non-plugin workflow.\n\n## Why Nuggets?\n\nLLM agents forget everything between sessions. RAG systems fix this but need vector databases, embedding APIs, and infrastructure. Nuggets takes a different approach:\n\n- **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.\n- **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.\n- **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.\n\nThink of it as an AI that lives in your pocket, remembers what matters, and reaches out when it has something useful to say.\n\n## What's Inside\n\n### Holographic Memory Engine (`src/nuggets/`)\n\nThe core of the system. Pure TypeScript, zero dependencies.\n\nEach \"nugget\" is a topic-scoped memory (e.g., `user`, `project`, `agent`). 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.\n\n- **remember** — bind a key-value pair into the holographic vector\n- **recall** — unbind a query and decode via cosine similarity (~1ms), with token-overlap matching for natural language queries\n- **forget** — subtract a binding from the superposition\n- **promote** — facts recalled 3+ times get written to `MEMORY.md` for permanent context\n- **memory kinds** — facts are auto-classified into `user` (preferences), `project` (files, commands, repo context), or `agent` (self-knowledge) scopes. Recall searches across kinds in priority order.\n\nStorage is a simple JSON file per kind at `~/.nuggets/` (e.g., `user.nugget.json`, `project.nugget.json`). Vectors are never serialized — they're rebuilt deterministically from a seeded PRNG, so the files stay tiny. A migration script (`npm run migrate:memory`) splits legacy single-file memory into the new kind-based layout.\n\n### Messaging Gateway (`src/gateway/`)\n\nA multi-channel message router that connects your AI to Telegram and WhatsApp.\n\n- **Process pool** — one Pi subprocess per user, reused across messages, reaped after 5 min idle\n- **JSONL RPC** — communicates with Pi via stdin/stdout, no sockets or HTTP\n- **Message queue** — serializes concurrent messages per user to prevent race conditions\n- **Heartbeat** — checks in every 30 min during waking hours. If there's nothing to say, it stays quiet\n- **Cron scheduler** — 5-field cron expressions for recurring messages, reminders, and one-shot timers\n- **Quiet hours** — no proactive messages between 10 PM and 8 AM (configurable)\n\n### Pi Extensions (`.pi/extensions/`)\n\nHooks into the Pi agent lifecycle:\n\n- **nuggets.ts** — gives Pi a `nuggets` tool for remember/recall/forget with memory kind routing, auto-captures file paths and user preferences from conversation, injects memory into system prompt\n- **proactive.ts** — gives Pi a `schedule` tool so it can create reminders and recurring tasks on its own\n\n## Setup\n\n### Prerequisites\n\n- Node.js 18+\n- [Pi](https://github.com/mariozechner/pi) — the AI coding agent that powers the assistant. Install globally:\n  ```bash\n  npm install -g @mariozechner/pi-coding-agent\n  ```\n- An [Anthropic API key](https://console.anthropic.com/) (the Max plan does **not** work — Anthropic blocked third-party OAuth in Jan 2026)\n- A Telegram bot token (from [@BotFather](https://t.me/BotFather))\n- Your Telegram chat ID (from [@userinfobot](https://t.me/userinfobot))\n\n### Quick Start\n\n```bash\nnpm install -g @mariozechner/pi-coding-agent   # install Pi (if not already)\ngit clone https://github.com/NeoVertex1/nuggets.git\ncd nuggets\nnpm install\nnpm run setup\nnpm run dev\n```\n\n### Setup Wizard\n\n`npm run setup` walks you through configuration interactively and is the recommended path for first run because it writes `.env` for you:\n\n```\n  Nuggets Setup Wizard\n  ====================\n\n  ── AI Provider ──────────────────────────────────────\n\n  Note: Anthropic Max plan does NOT work (third-party OAuth\n  was blocked Jan 2026). You need an API key from:\n  https://console.anthropic.com/\n\n  Paste your sk-ant-... key:\n  Anthropic API key: sk-ant-api03-...\n\n  ── Telegram ─────────────────────────────────────────\n\n  Create a bot via @BotFather on Telegram, paste the token:\n  Bot token: 123456789:AAF...\n\n  Send /start to @userinfobot on Telegram to get your chat ID:\n  Chat ID: 987654321\n\n  ── WhatsApp (optional) ──────────────────────────────\n\n  Your JID (e.g. 1234567890@s.whatsapp.net) — press Enter to skip:\n  WhatsApp JID:\n\n  ── Pi Model (optional) ──────────────────────────────\n\n  Model ID (press Enter for Pi's default):\n  Model:\n\n  ✓ .env written successfully.\n\n  Ready! Run `npm run dev` to start.\n```\n\nThe wizard validates inputs (API key format, token format, numeric chat ID), shows masked current values if `.env` already exists, and writes the file atomically.\n\n### Getting Your Telegram Credentials\n\n1. **Bot token** — open Telegram, search for [@BotFather](https://t.me/BotFather), send `/newbot`, follow the prompts. You'll get a token like `123456789:AAF7_NRCOM2nxZt...`\n2. **Chat ID** — search for [@userinfobot](https://t.me/userinfobot), send `/start`. It replies with your numeric chat ID.\n3. Run `npm run setup`, paste both values, and you're done.\n\n## How It Works\n\n```\nYou (Telegram/WhatsApp)\n  │\n  ▼\nGateway ── router ── message queue (per user)\n  │                      │\n  ├── heartbeat          ▼\n  ├── cron          Pi subprocess (JSONL RPC)\n  │                      │\n  │                 ┌────┴─────┐\n  │              nuggets    schedule\n  │              extension  extension\n  │                 │          │\n  │            ~/.nuggets/   .gateway/cron/\n  │           (HRR memory)  (job store)\n  │                 │\n  │            promoteFacts()\n  │                 │\n  │            MEMORY.md\n  │         (permanent context)\n  ▼\nEventQueue ◄── cron fires ── \"0 9 * * *\"\n           ◄── heartbeat ─── every 30 min\n           ◄── timer ──────── one-shot\n```\n\n**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.\n\n**Proactive flow**: Heartbeat timer fires → Pi checks memory for anything worth following up on → if yes, sends you a message. If not, stays silent.\n\n**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.\n\n## Architecture\n\n```\nsrc/\n  nuggets/              Memory engine (pure TypeScript, zero deps)\n    core.ts             HRR math: bind, unbind, orthogonalize, sharpen\n    memory.ts           Nugget class: remember, recall, forget (+ token-overlap matching)\n    shelf.ts            NuggetShelf: multi-nugget manager with kind-aware routing\n    kinds.ts            Memory kind types, auto-classification heuristics\n    promote.ts          MEMORY.md promotion (3+ recall threshold)\n    index.ts            Public API\n\n  migrate-memory.ts     Migration: legacy single nugget → kind-based layout\n\n  gateway/              Messaging gateway\n    main.ts             Entry point — wires everything together\n    config.ts           Environment config + helpers\n    router.ts           Message routing + proactive event handling\n    pi-rpc.ts           Pi subprocess communication (JSONL RPC)\n    pi-pool.ts          Per-user process pool with idle eviction\n    telegram.ts         Telegram bot (grammY)\n    whatsapp.ts         WhatsApp client (Baileys)\n    event-queue.ts      Proactive event bus\n    cron.ts             5-field cron scheduler + request file watcher\n    heartbeat.ts        Per-user periodic check-ins\n\n  setup.ts              Interactive setup wizard\n\n.pi/extensions/\n  nuggets.ts            Memory tool + auto-capture + system prompt injection\n  proactive.ts          Schedule tool + cron file bridge\n```\n\n## Scripts\n\n| Command | What it does |\n|---|---|\n| `npm run setup` | Interactive setup wizard — creates `.env` |\n| `npm run dev` | Start the gateway (Telegram + WhatsApp) |\n| `npm test` | Run tests |\n| `npm run migrate:memory` | Migrate legacy single-file memory to kind-based layout |\n| `npm run typecheck` | Type-check without emitting |\n| `npm run build` | Compile to `dist/` |\n\n## Testing\n\n```bash\nnpm test\n```\n\nTests cover HRR math (bind/unbind accuracy, orthogonalization), nugget operations (remember/recall/forget lifecycle), and shelf management.\n\n## License\n\nMIT\nnpm run migrate:memory` | Migrate legacy single-file memory to kind-based layout |\n| `npm run typecheck` | Type-check without emitting |\n| `npm run build` | Compile to `dist/` |\n\n## Testing\n\n```bash\nnpm test\n```\n\nTests cover HRR math (bind/unbind accuracy, orthogonalization), nugget operations (remember/recall/forget lifecycle), and shelf management.\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FNeoVertex1%2Fnuggets","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FNeoVertex1%2Fnuggets","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FNeoVertex1%2Fnuggets/lists"}