Note Assistant

A personal AI note assistant that lets you save notes, search them, ask questions, and run an agent that can decide when to use note tools.

The app is intentionally small and learning-focused: it starts with a basic CLI, adds semantic search with RAG, and now includes an agentic flow with tool use and evals.

What It Can Do

• Save notes with optional tags.
• List and delete notes.
• Ask questions using your saved notes as context.
• Run an agent that can search, list, summarise, add, or delete notes.
• Ask for approval before the agent adds or deletes anything.
• Run starter evals against an isolated test note database.

How It Works

ask "When is my dentist appointment?"
        |
Embed the question
        |
Search local LanceDB notes
        |
Send relevant note text to Groq
        |
Return an answer based on your notes

The agent command adds one more step: it lets the model choose a tool first, such as search_notes, list_notes, or add_note, then uses the tool result to answer.

Stack

| Role | Tool | |---|---| | CLI | Node.js + TypeScript | | LLM | Groq | | Embeddings | Google Gemini gemini-embedding-001 | | Vector store | LanceDB, stored locally |

Setup

Install dependencies:

npm install

Create your local env file:

cp .env.example .env

Fill in:

GROQ_API_KEY=your_groq_key
GEMINI_API_KEY=your_gemini_key
GROQ_MODEL=llama-3.1-8b-instant
GROQ_MODEL_AGENT=llama-3.3-70b-versatile
GEMINI_EMBEDDING_MODEL=gemini-embedding-001

Usage

# Add a note
npx tsx src/cli/index.ts add "Dentist appointment May 3rd at 2pm"

# Add a note with tags
npx tsx src/cli/index.ts add --tag work --tag meeting "Sprint planning every Monday 10am"

# Ask using the RAG flow
npx tsx src/cli/index.ts ask "When is sprint planning?"

# List notes
npx tsx src/cli/index.ts list

# Delete a note
npx tsx src/cli/index.ts delete <note-id>

Agent examples:

# Quiet by default: only prints the answer
npx tsx src/cli/index.ts agent "Summarise my work notes"

# Debug mode: also shows model, tools used, and iterations
npx tsx src/cli/index.ts agent --debug "Summarise my work notes"

# Requires approval before saving
npx tsx src/cli/index.ts agent "Save a note: buy groceries tomorrow"

Evals

Run the starter eval suite:

npx tsx src/evals/runner.ts

The eval runner uses a separate LanceDB path under data/evals-lancedb, seeds its own notes, and checks six basic scenarios: search, list, add, summarise, general question, and safe delete behavior.

Project Structure

src/
  agent/             Agent loop, tools, prompt, and memory
  cli/               CLI commands
  evals/             Starter eval cases and runner
  rag/               Retrieval and answer generation
  services/          LLM, embeddings, notes, and vector store
  types/             Shared TypeScript types

Useful Checks

npx tsc --noEmit
npm run build
npx tsx src/evals/runner.ts

Notes

• Existing add, ask, list, and delete commands still work as before.
• The agent uses a stronger Groq model for better tool calling.
• Add and delete actions go through a human approval prompt.