🧠 Recall

A local-first AI memory platform — built for engineers who forget nothing.

🖥️ Desktop App · 📡 API Reference · 🧩 Architecture

---

What Is Recall?

Every engineer has years of work scattered across dozens of repos, notes, and half-finished side projects — and no real memory of most of it. Recall fixes that by running quietly on your own machine: it watches the folders you point it at, reads everything that lands in them, and turns your own file history into a searchable, chattable, visual second brain.

Ask it something like "where did I implement JWT auth?" and Recall doesn't grep for a string — it understands the question, searches by meaning across every file it's indexed, and answers in plain language with citations back to the exact source.

No cloud sync. No uploading your code to a third party's product. Your files never leave your machine — only the text Recall summarizes ever touches an AI API, and even that's your own key, your own choice of provider.

Features

• 🔍 Hybrid Semantic Search — vector similarity (pgvector) fused with PostgreSQL full-text search, ranked together, so results surface by meaning and keyword, not one or the other.
• 💬 AI Assistant — a retrieval-augmented chat that answers questions about your own codebase, streamed token-by-token, every claim traceable back to the file it came from.
• 🕸️ Knowledge Graph — an interactive, force-directed map of how your files, projects, topics, and technologies connect — click a node, jump straight to the source.
• 📁 Project Explorer — auto-detects project boundaries from .git, package.json, pom.xml, and similar markers, then writes an AI brief for each one: overview, stack, architecture, complexity.
• 🧠 Memories — Recall doesn't log everything, it notices what's worth remembering: your first time touching a new technology, a pattern repeating across projects, a milestone worth flagging.
• 📆 Activity Timeline — a day-by-day feed of your engineering activity, built automatically from real filesystem events, zero manual logging.
• 🖥️ Browser or Desktop — ships as a web app and as a packaged Electron application, same data either way.

Architecture

Recall is a layered pipeline — every file that lands in a watched folder flows through detection, understanding, and indexing automatically, with no manual step in between.

graph TD
    FS[("📁 Watched Folder")] -->|NIO WatchService| Watcher[File Watcher]
    Watcher -->|Redis Queue| Indexer[Indexer + Tika Parser]
    Indexer -->|Chunks| AI[AI Processing — LangChain4j]

    subgraph "AI Layer"
        AI -->|Summarize| Gemini[Gemini 3.5 Flash Lite]
        AI -->|Embed| Embed[Gemini Embedding]
    end

    Gemini --> Store[(PostgreSQL + pgvector)]
    Embed --> Store

    Store --> Search[Hybrid Search]
    Store --> Assistant[RAG Assistant]
    Store --> Graph[Knowledge Graph]
    Store --> Dashboard[Dashboard]

Loading

RAG Pipeline — How the Assistant Answers

sequenceDiagram
    participant U as User
    participant F as Frontend
    participant B as AssistantService
    participant V as pgvector
    participant G as Gemini

    U->>F: Ask a question
    F->>B: POST /chat (SSE)
    B->>G: Embed the query
    G-->>B: 768-dim vector
    B->>V: Cosine similarity search
    V-->>B: Top-K relevant chunks
    B->>G: Stream response w/ retrieved context
    G-->>B: Token stream
    B-->>F: SSE tokens + source citations
    F-->>U: Streamed answer, cited to source files

Loading

Tech Stack

Layer	Technology	Why
Backend	Spring Boot 3.5, Java 21	Mature, typed, production-grade for a long-running local service
AI	LangChain4j + Gemini (chat & embeddings)	Provider-agnostic abstraction, structured output support
Database	PostgreSQL 16 + pgvector	Native vector similarity search alongside relational data
Cache	Redis 7	Indexing queue, search cache, distributed rate limiting
Search	Hybrid: pgvector cosine + full-text (tsvector)	Catches both conceptual and literal matches
Parsing	Apache Tika	Handles PDF, DOCX, and dozens of formats out of the box
Frontend	React 19, TypeScript, Vite 6, Tailwind CSS 4	Fast dev loop, typed end-to-end
State	TanStack Query, Zustand	Server-state caching + minimal client state
Animation	Framer Motion	Physically-based motion, not CSS keyframe hacks
Desktop	Electron, electron-builder	One codebase, native app on Windows/macOS/Linux
Infra	Docker Compose, Flyway	Reproducible environments, versioned schema migrations

Project Structure

recall/ ├── backend/ Spring Boot application (Maven) │ ├── src/main/java/com/recall/ │ │ ├── ai/ Summaries, embeddings, topics, relationships │ │ ├── assistant/ RAG chat pipeline + SSE streaming │ │ ├── connector/ Workspace & folder connector management │ │ ├── graph/ Knowledge graph aggregation │ │ ├── indexing/ File parsing, chunking, indexing queue │ │ ├── project/ Automatic project detection & briefs │ │ ├── search/ Hybrid vector + keyword search │ │ └── settings/ Encrypted API key & config storage │ ├── src/main/resources/db/migration/ Flyway migrations (V1–V10) │ └── Dockerfile ├── frontend/ React + Vite application │ ├── src/pages/ Route-level page components │ ├── src/features/ Feature modules (projects, memories, timeline) │ ├── src/components/ Shared UI, layout, search, indexing components │ ├── electron/ Electron main process + preload script │ └── Dockerfile ├── docker/ │ ├── docker-compose.yml │ └── postgres/init.sql ├── docs/ PRD, architecture, design system, phase plans └── README.md

Getting Started

Prerequisites

• Java 21 (LTS)
• Node.js 20+ and npm
• Docker + Docker Compose
• A Gemini API key (free tier available)

Quick Start — Full Docker Stack

cd docker
docker compose up -d

Service	Port	Description
postgres	5432	PostgreSQL 16 with pgvector
redis	6379	Redis 7
backend	8080	Spring Boot API
frontend	80	Nginx serving the React SPA + proxy

Give it ~30 seconds, then open http://localhost and drop your Gemini key into Settings — it's encrypted at rest (AES-256-GCM) before it touches disk.

Local Development

# 1. Infra only
cd docker && docker compose up -d postgres redis

# 2. Backend — http://localhost:8080
cd backend && ./mvnw spring-boot:run -Dspring-boot.run.profiles=docker

# 3. Frontend — http://localhost:5173
cd frontend && npm install && npm run dev

Desktop App (Electron)

cd frontend
npm install
npm run electron         # build + launch
npm run electron:build   # produce distributable installers (Win/macOS/Linux)

API Reference

Base URL: http://localhost:8080/api/v1

Endpoint	Method	Description
/health	GET	Health check (DB + Redis)
/settings	GET/POST	Application settings (incl. API key)
/workspaces	GET/POST	Manage workspaces
/connectors	GET/POST	Manage monitored folders
/indexing/status	GET	Current indexing status
/indexing/rescan	POST	Trigger a manual rescan
/search	POST	Hybrid semantic + keyword search
/chat	POST	AI assistant (Server-Sent Events)
/conversations	GET	List saved conversations
/graph	GET	Knowledge graph (nodes + edges)
/dashboard	GET	Aggregate stats + recent activity
/projects	GET	Auto-detected projects
/memories	GET	AI-generated memories
/activities	GET	Activity timeline

Testing

cd backend && mvn clean test    # unit + integration tests (Testcontainers)
cd frontend && npm run build    # type check + production build

The backend suite exercises rate limiting, retry/backoff, RAG grounding, graph construction, and end-to-end file-watch → index → AI-processing flows against real Postgres and Redis containers — not just mocks.

A Note on Free-Tier API Usage

Recall's AI features run against the Gemini API's free tier by default, which enforces daily/per-minute rate limits. The pipeline handles this gracefully: a global rate limiter throttles all AI calls regardless of concurrency, failures are classified (transient vs. quota-exhausted) and retried intelligently, and large workspaces may simply take more than a day to fully process — that's expected, not a bug.

License

Private — All rights reserved.

_{Built for engineers who never want to explain their own code from memory again.}