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"

# Trace mode: prints the path of the per-run trace file
npx tsx src/cli/index.ts agent --trace "list all 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 eleven scenarios. The first six cover the basics (search, list, add, summarise, general question, safe delete behavior); five adversarial cases added in v1.3.0 cover prompt injection in note content, malformed tool arguments, ignoring injected instructions, soft-delete recoverability, and runaway-loop prevention. Cases can define setup/verify hooks for state-based assertions.

Hardening (v1.3.0)

This release hardens the agent without changing what it can do:

• Structured tool contracts — every tool's arguments are validated with a Zod schema (src/agent/schemas.ts) before execution and before the approval prompt. Invalid arguments (e.g. a non-UUID delete id) are rejected with a clear, retryable error the model can self-correct, instead of reaching a service.
• Prompt injection defense — the system prompt instructs the agent to treat all tool output as data, never instructions. User input is sanitised (control characters stripped, suspicious phrases logged) and the final answer is screened for data-exfiltration URLs.
• Soft delete — delete_note now marks a note with a deletedAt timestamp instead of erasing it. Deleted notes vanish from search and list but remain recoverable in the store. Supports dryRun to preview a deletion. (The direct delete CLI command remains a hard delete.)
• Per-run traces — every agent run writes a structured JSON trace to traces/run-<timestamp>.json (auto-pruned after 30 days). The --trace flag prints the path. Trace files hold real note content and are git-ignored.
• Expanded evals — 11 cases total, including 5 adversarial ones (see below).

The agent core (src/agent/) has no CLI/filesystem coupling — HITL approval is an injected callback and trace persistence lives in src/observability/ — so the loop can be reused by a future web frontend unchanged.

Project Structure

src/
  agent/             Agent loop, tools, schemas, prompt, and memory
  cli/               CLI commands
  evals/             Eval cases and runner
  observability/     Per-run trace writer
  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.