DOCSEARCHbyAlgolia
Submit Docs

nuggets

repository·main·Indexed 18 days ago

https://github.com/neovertex1/nuggets

A personal AI assistant featuring a holographic memory engine based on Holographic Reduced Representations (HRR) for fast, offline, cross-session persistence. It includes a multi-channel messaging gateway for Telegram and WhatsApp, integrates with the Pi coding agent, and provides a memory plugin for MCP hosts like Hermes Agent, Claude Code, and Codex. The system supports proactive reminders via a cron scheduler and classifies memory into user, project, and agent scopes.

Tokens
15.4K
Snippets
58
Records
76
Agent score
64%

What's inside nuggets

  1. Compare AI memory systems: Nuggets vs RAG, Mem0, and MemOS

    main

    When choosing a memory system for your AI application, consider the following trade-offs based on your requirements for speed, cost, and scale:

    RAG (Retrieval-Augmented Generation)

    • Best for: Large-scale document retrieval and handling massive datasets.
    • Mechanism: Embeds documents into a vector database and performs semantic search at query time.
    • Trade-offs: High latency, requires embedding APIs and vector DB infrastructure, and incurs ongoing costs.

    Mem0

    • Best for: Smart conversational memory that requires understanding relationships between facts.
    • Mechanism: Uses an LLM to extract facts from conversations and stores them in a graph/vector hybrid.
    • Trade-offs: High cost due to LLM calls for both reading and writing, and dependency on external APIs.

    MemOS / Memlayer

    • Best for: Applications requiring structured memory layers (combining short-term context with long-term storage).
    • Mechanism: Explicit memory management across different storage tiers.
    • Trade-offs: Complex architecture with multiple moving parts and dependencies on embeddings/databases.

    Nuggets

    • Best for: Personal AI agents (e.g., Telegram bots) that need fast, cheap, offline memory for facts and user preferences.
    • Mechanism: Uses holographic reduced representations where facts are encoded as superposed complex vectors, with recall via algebraic unbinding.
    • Pros: Sub-millisecond recall, zero API costs, runs offline, tiny storage (JSON file), zero dependencies, and deterministic.
    • Cons: Capacity is limited by vector dimension (approx. 512 facts at D=16384), key-value only (not for document chunks), and uses fuzzy string matching instead of semantic understanding.

  2. Understand Nuggets constraints and best practices

    main

    Nuggets is an associative cache based on Holographic Reduced Representations (HRR), not a traditional database. To use it effectively, observe these constraints:

    When to use Nuggets

    • Caching learned facts: Project patterns, user preferences, or code locations.
    • Remembering past fixes: Storing diagnosis + fix pairs for recurring bugs.
    • Cross-session memory: Facts persist to ~/.nuggets/ and survive restarts.
    • Pre-search check: Check if you already know a file location before searching the filesystem.

    When NOT to use Nuggets

    • Large data: Do not store large documents or code blocks; keep values as short strings.
    • Exact retrieval: HRR is approximate; do not use it if you require exact text matching.
    • Structured data: Do not use it for complex queries, joins, or filtering (use a real database instead).
    • High density: Avoid exceeding ~250 facts per nugget. If a nugget reaches capacity, create a new one with a different topic.

  3. Understand the Astro Blog project structure

    main

    The project follows a standard Astro directory structure:

    • public/: Contains static assets like images.
    • src/components/: Location for Astro, React, Vue, Svelte, or Preact components.
    • src/content/: Contains 'collections' of Markdown and MDX documents. You can use getCollection() to retrieve posts (e.g., from src/content/blog/) and use schemas to type-check frontmatter.
    • src/layouts/: Contains layout components.
    • src/pages/: Contains .astro or .md files. Each file in this directory is exposed as a route based on its filename.
    • astro.config.mjs: The Astro configuration file.
    • package.json: Project dependencies and scripts.
    • tsconfig.json: TypeScript configuration.
    ├── public/
├── src/
│   ├── components/
│   ├── content/
│   ├── layouts/
│   └── pages/
├── astro.config.mjs
├── README.md
├── package.json
└── tsconfig.json

  4. How the Messaging Gateway and Proactive Flow work

    main

    The Messaging Gateway connects your AI to Telegram and WhatsApp using a multi-channel router.

    Message Flow

    1. You send a message via Telegram/WhatsApp.
    2. The gateway routes it to a dedicated Pi subprocess (using JSONL RPC via stdin/stdout).
    3. Pi checks the holographic memory for context.
    4. Pi responds, and the gateway delivers the reply.

    Proactive Flow

    • Heartbeat: The system checks in every 30 minutes during waking hours. If the AI has something useful to say based on memory, it sends a proactive message.
    • Cron Scheduler: Supports 5-field cron expressions for recurring messages, reminders, and one-shot timers.
    • Quiet Hours: By default, no proactive messages are sent between 10 PM and 8 AM (configurable).
    • Process Management: One Pi subprocess is maintained per user and is reaped after 5 minutes of inactivity.

  5. How the Holographic Memory Engine works

    main

    The memory engine uses Holographic Reduced Representations (HRR) to store facts as superposed complex-valued vectors. This allows multiple facts to be stored in a single mathematical object while remaining individually retrievable.

    Core Operations

    • remember: Binds a key-value pair into the holographic vector.
    • recall: Unbinds a query and decodes via cosine similarity (~1ms). It supports natural language queries via token-overlap matching.
    • forget: Subtracts a binding from the superposition.
    • promote: Facts that are recalled 3 or more times are automatically promoted to MEMORY.md for permanent context.

    Memory Kinds

    Facts are auto-classified into three scopes:

    • user: Preferences.
    • project: Files, commands, and repository context.
    • agent: Self-knowledge.

    Recall searches across these kinds in priority order. Data is stored as JSON files in ~/.nuggets/ (e.g., user.nugget.json).

  6. Implement the recall-first pattern

    main

    To optimize agent performance and reduce costs, follow the recall-first pattern. Instead of performing expensive operations (like file searches, API calls, or RAG queries) immediately, check the Nuggets associative cache first.

    Workflow:

    1. Query: When an agent needs information, run nuggets recall "<query>".
    2. Hit: If a result is returned, use the cached answer immediately.
    3. Miss: If no result is found, proceed with the expensive search/API call/file read.
    4. Cache: Once the information is retrieved, store it using nuggets remember <topic> "<key>" "<answer>" to make it available for future queries.

  8. Organize nuggets by topic

    main

    To maintain efficiency and stay within capacity guidelines, organize your facts into logical nuggets. When a nugget reaches capacity, create a new one; recall searches can be broadcast across all nuggets automatically.

    Suggested Organization Strategy

    Nugget namePurposeExample Key/Value
    projectBuild commands, tech stack, deploy process"test command" $\rightarrow$ "pytest src/ -v"
    prefsUser preferences and conventions"indent style" $\rightarrow$ "2 spaces"
    locationsFile/function definitions"auth handler" $\rightarrow$ "src/auth/middleware.ts:47"
    debugPast bug diagnoses"CORS error" $\rightarrow$ "add origin to allowlist in config.ts"

  9. Set up Nuggets via the Setup Wizard

    main

    The recommended way to configure Nuggets is using the interactive setup wizard, which validates your credentials and writes the .env file for you.

    Prerequisites

    • Node.js 18+
    • Pi (AI coding agent) installed globally: npm install -g @mariozechner/pi-coding-agent
    • An Anthropic API key (Note: Anthropic Max plan does not work due to OAuth restrictions).
    • A Telegram bot token (from @BotFather).
    • Your Telegram chat ID (from @userinfobot).

    Installation Steps

    npm install -g @mariozechner/pi-coding-agent
git clone https://github.com/NeoVertex1/nuggets.git
cd nuggets
npm install
npm run setup
npm run dev
    npm run setup

  10. Register Nuggets Memory with MCP hosts

    main

    After installing the nuggets-memory-plugin globally, register it with your specific agent host using their native MCP command:

    Hermes Agent

    hermes mcp add nuggets-memory --command nuggets-memory-plugin

    Claude Code

    claude mcp add nuggets-memory -- nuggets-memory-plugin

    Codex

    codex mcp add nuggets-memory -- nuggets-memory-plugin

  11. Install and use the Nuggets CLI

    main

    Nuggets is a fast key-value memory system for LLM agents. You can interact with it primarily through the CLI after installing via pip. Use the --json flag with recall, list, status, or facts to get machine-readable output for automation.

    Available Commands

    CommandDescription
    nuggets remember <nugget> <key> <value>Store a fact (automatically creates the nugget if it doesn't exist)
    nuggets recall <query> [--nugget <name>]Query memory (searches all nuggets by default)
    nuggets forget <nugget> <key>Remove a specific fact
    nuggets listList all existing nuggets
    nuggets statusShow overall system status
    nuggets facts <nugget>List all facts contained within a specific nugget
    nuggets clear <nugget>Clear all facts from a specific nugget
    pip install nuggets

# Example usage
nuggets remember project "test command" "pytest src/ -v"
nuggets recall "how do I test"

  12. Install the Nuggets Memory Plugin for coding agents

    main

    If you are using a coding agent and want to provide it with lightweight cross-session memory (preferences, corrections, project hints), install the nuggets-memory-plugin via npm. This plugin provides MCP tools such as guide, nudges, recall, remember, list, and status.

    npm install -g nuggets-memory-plugin