Download the PHP package nahid-hasan/ai-notes without Composer

🧠 ollama-notes-laravel-package (ai-notes)

Turn your Laravel app into an AI-powered memory system.

Record a voice note or write text. Search it later using natural language — not keywords. No OpenAI account needed. Runs 100% locally and free with Ollama + Whisper.

Features

• 🎙️ Voice notes — upload audio, Whisper transcribes it automatically
• ✍️ Text notes — store any text, summarized and embedded instantly
• 🔍 Semantic search — find notes by meaning, not just keywords (pgvector)
• 🤖 Ask questions — RAG-powered Q&A across your entire note history
• ⚡ Queue-first — all AI processing runs async via Laravel queues
• 🔌 Swappable drivers — Ollama (free/local) or OpenAI (paid)
• 🐳 Docker included — full docker-compose setup out of the box
• 🧪 Fake provider — test without any AI services running

Requirements

For the free local AI stack (recommended): Docker is required to run Ollama and Whisper containers.
For OpenAI: just an API key, no Docker needed for AI services.

Installation

1. Install the package

2. Run the install command

This publishes the config file and migrations.

3. Run migrations

This creates the ai_notes table and enables the pgvector extension automatically.

Setup: Free Local Stack (Recommended)

This uses Ollama (summarization + embeddings) and Whisper (transcription) — both running in Docker, zero cost, zero API keys.

Step 1 — Add Docker services

Copy this into your docker-compose.yml:

For the complete docker-compose.yml with Whisper Dockerfile and Flask server, see Docker Setup below.

Step 2 — Pull the AI models

First pull is ~2-4GB. After that, restarts are instant.

Step 3 — Configure your .env

Step 4 — Start the queue worker

That's it. You're running fully local AI.

Setup: OpenAI (Paid Alternative)

If you prefer OpenAI and already have an API key:

No Ollama or Whisper needed. Everything else works identically.

Note: When switching from Ollama (768 dims) to OpenAI (1536 dims), you need to re-run migrations with the correct dimension. Set AI_NOTES_VECTOR_DIM=1536 in .env before migrating.

Usage

Storing Notes

From audio (voice note):

From text:

Checking Processing Status

AI processing is async. Poll the status or use a webhook/event:

Searching Notes

How distance scores work:

Asking Questions (RAG)

Working with the Model Directly

Complete API Reference

AINote::fromAudio(UploadedFile $file, ?int $userId = null): AINote

Upload an audio file. Queues transcription → summarization → embedding. Returns the note immediately with status = "pending".

AINote::fromText(string $text, ?int $userId = null, ?string $title = null): AINote

Store a text note. Queues summarization → embedding. Returns the note immediately with status = "pending".

AINote::search(string $query, int $limit = 5, ?int $userId = null): Collection

Semantic search across all done notes. Returns an Eloquent Collection sorted by relevance. Each result includes a distance attribute.

AINote::ask(string $question, int $contextLimit = 3, ?int $userId = null): string

RAG-powered question answering. Finds the most relevant notes, builds context, and asks the AI to answer your question based on them. Returns a plain string answer.

Configuration

Publish and edit config/ai-notes.php:

Docker Setup

Full docker-compose.yml for a new project using this package:

docker/whisper/Dockerfile:

docker/whisper/server.py:

Testing

The package ships with a FakeAIProvider so your tests never hit real AI services:

Customise fake responses:

Custom AI Driver

Implement the AIProvider contract to use any AI provider:

Register it in a service provider:

Troubleshooting

SQLSTATE: type "vector" does not exist
You're using plain PostgreSQL without pgvector. Use the pgvector/pgvector:pg16 Docker image instead of postgres:16.

Notes stuck on pending status
Your queue worker isn't running. Start it:

Ollama returns empty embeddings
The model isn't pulled yet:

Whisper is slow on first request
Normal — it loads the model into memory on first call (~10-15 seconds). Subsequent calls are fast.

distance is always high (>0.8) for all results
Your notes were embedded with a different model than your search query. If you switched from Ollama to OpenAI (or vice versa), re-process your notes:

Notes have status = failed
Check storage/logs/laravel.log for the error. Common causes: Ollama not running, Whisper unreachable, or audio file format not supported by Whisper.

Roadmap

• [ ] Livewire/Vue UI component
• [ ] Auto-tagging via AI
• [ ] Vector DB drivers (Pinecone, Weaviate, Qdrant)
• [ ] Realtime recording via browser MediaRecorder API
• [ ] Team/multi-tenant support
• [ ] Note export (PDF, Markdown)
• [ ] Scheduled note digests ("summarize my week")

Contributing

Contributions are welcome. Please:

1. Fork the repo
2. Create a feature branch: git checkout -b feature/my-feature
3. Write tests for your changes
4. Submit a PR against main

License

The MIT License. See LICENSE for details.