iRecall

iRecall is a local-first quote and note recall tool written in Go. It stores notes in SQLite, uses an OpenAI-compatible model to extract tags and recall keywords, and generates answers grounded only in the quotes it retrieves.

The project currently ships with:

• a Bubble Tea terminal client
• an HTTP web UI server
• a Wails-based desktop client
• a shared Go core for persistence, retrieval, import/export, and provider integration

Features

• Create and edit free-form quotes and notes
• Auto-tag notes with an OpenAI-compatible chat-completions endpoint
• Search the local quote corpus with SQLite FTS5
• Filter weaker matches with a configurable relevance threshold
• Generate grounded answers from retrieved quotes
• Save Recall question/response pairs as quotes with generated tags
• Review Recall history and promote past sessions into quotes
• Export and import quotes through a versioned JSON share format
• Preserve author and source provenance on imported content
• Protect the web UI with a locally managed password and browser session
• Configure provider settings, retrieval settings, theme, web port, and mock-LLM debug mode
• Run isolated local instances with a custom data root
• Switch the active storage root from the TUI Settings page or with -data-path

Getting Started

Requirements

• Go
• a compatible OpenAI-style API endpoint for chat completions
• optional: Node.js and npm for frontend-backed builds (make frontend-build, make build-web, make build-desktop, make build-release)

Build the terminal client

make build
./bin/irecall

Build the web UI server

make build-web
./bin/irecall-web

Useful flags:

./bin/irecall-web --version
./bin/irecall-web --debug
./bin/irecall-web -host 0.0.0.0
./bin/irecall-web -port 9527
./bin/irecall-web -data-path /tmp/irecall-web-dev

The persisted web-port default is 9527. Port 95270 is not usable because TCP ports must be in the range 1..65535.

Useful flags:

./bin/irecall --version
./bin/irecall --debug
./bin/irecall -data-path /tmp/irecall-dev

First run

1. Save your display name in the startup prompt.
2. Open Settings.
3. Configure the provider host, port, HTTPS setting, API key if required, and model.
4. Optionally fetch available models from /v1/models.
5. If you are using the web UI, the first launch prompts for the web password in the terminal before the server starts listening. Use Settings to change it later. For headless MCP/operator usage, start irecall-web with --api-only and pass the provider settings on startup instead of going through the frontend UI.
6. Save the settings and start adding quotes.

Provider Compatibility

iRecall expects an OpenAI-compatible API with:

• POST /v1/chat/completions
• GET /v1/models

Typical setups:

Provider	Host	Port	HTTPS	API Key
Ollama	localhost	11434	off	not required
LM Studio	localhost	1234	off	not required
Hosted OpenAI-compatible endpoint	provider host	provider port	usually on	provider-specific

Usage

The shipped clients currently expose four primary surfaces:

• Recall: ask questions and review the retrieved quotes used to answer them
• History: review saved recall sessions and reopen their reference quotes
• Quotes: browse, edit, delete, import, and export stored quotes
• Settings: configure provider, retrieval, and theme options

Notable workflows:

• add quotes from the TUI and refine drafts before saving
• save the current Recall question/response as a quote
• reopen a past History entry and save it as a quote later
• export selected quotes to a JSON payload
• import shared quotes back into another instance
• tune retrieval with MaxResults and MinRelevance

MinRelevance uses a normalized 0.0..1.0 scale:

• 0.0 disables filtering
• 0.3 to 0.7 is a good practical range
• 1.0 is very strict

Data Storage

On Linux iRecall now consolidates defaults under the data directory so everything lives together by default. The effective defaults (when XDG vars are not set) are:

Item	Default Path
All app files (data/config/state)	~/.local/share/irecall/
SQLite database	~/.local/share/irecall/irecall.db
Log file	~/.local/share/irecall/irecall.log
Persisted preferred root file	~/.local/share/irecall/root-path (used only if you choose a custom root)

Notes:

• Config and state now fall back to the data directory by default so the app uses a single per-user directory unless XDG_* environment variables override individual locations.
• To run an isolated instance with its own storage root, pass a root path. The root will contain data/, config/, and state/ subdirectories:

./bin/irecall -data-path /path/to/instance

• You can also set the storage root from the TUI Settings page. When you save a new root, iRecall:
  • closes the current runtime (to avoid DB locks),
  • if the target root is empty, copies current data/, config/, and state/ into <root>/... (copy, not move),
  • if the target already contains iRecall data, attaches to it without overwriting,
  • persists the chosen root so it is applied on future launches,
  • attempts to reopen the previous runtime on failure (partially-copied files are not automatically removed).

Leaving the setting blank returns to the platform default behavior (XDG paths or the consolidated data dir fallback described above).

Desktop and web currently show the active storage paths in Settings, but they do not yet expose a root-path editor.

Project Layout

iRecall/
├── cmd/irecall/      # terminal entry point
├── cmd/irecall-mcp/  # MCP bridge entry point
├── config/           # XDG path helpers
├── core/             # engine, models, DB layer, LLM client
│   ├── db/
│   └── llm/
├── app/              # Shared desktop/web application orchestration
├── desktop/          # Wails desktop runtime
├── frontend/         # Shared frontend assets and source
├── mcp/              # MCP bridge package and iRecall REST wrapper
├── web/              # HTTP web UI runtime
├── docs/             # roadmap, specs, design docs, plans
├── tools/            # auxiliary tools such as Redmine export
├── tui/              # Bubble Tea application and pages
│   ├── pages/
│   └── styles/
├── Makefile
└── README.md

Development

Common targets:

make build
make build-mcp
make build-web
make build-release
make run
make test
make lint
make build-all

Release artifact bundle:

make build-release

This writes versioned .tar.gz release archives to dist/release/ for the TUI, desktop app, web frontend bundle, and web server. Windows executables are packaged inside .tar.gz archives instead of being emitted as raw .exe files.

Artifact filenames use RELEASE_VERSION, which defaults to the exact Git tag on tagged commits and otherwise falls back to the current short commit hash. You can override it explicitly, for example make build-release RELEASE_VERSION=v0.3.0.

Desktop build:

make build-desktop

Web UI build:

make build-web

MCP bridge build:

make build-mcp

MCP token provisioning uses the web binary:

make build-web
./bin/irecall-web \
  --api-only \
  --host 127.0.0.1 \
  --port 9527 \
  --provider-host api.openai.example/v1 \
  --provider-port 443 \
  --provider-https \
  --provider-api-key-path ~/.config/irecall/provider-api-key \
  --provider-model gpt-4.1 \
  --provider-keyword-model gpt-4.1-mini
./bin/irecall-web auth issue-token --write-token-file ~/.config/irecall/mcp-api-token

Frontend dependencies:

make frontend-install
make frontend-build

Documentation

• docs/PLAN.md: roadmap and planning index
• docs/SPEC.md: technical specification
• docs/KEYWORD_MATCHING.md: how keyword extraction and quote matching work
• docs/schema.md: quote, share, and provenance schema guide
• docs/UI_DESIGN.md: shared UI contract
• docs/WAILS_DESKTOP.md: desktop mapping
• docs/QUOTES_SHARING_DESIGN.md: sharing model
• docs/WEB_REST_API.md: current web REST endpoint reference
• docs/WEB_API_TOKEN_AUTH.md: REST API bearer-token design
• docs/MCP_OPENCLAW.md: MCP bridge scaffold and operator notes
• tools/redmine_export/README.md: Redmine export tool usage

Headless API mode for MCP/OpenClaw

For production-safe operator or MCP usage, start the web server with --api-only. This skips the frontend password bootstrap, does not serve the frontend UI, and keeps /api/app/* protected by bearer-token auth.

Example:

go run ./web \
  --host 127.0.0.1 \
  --port 9527 \
  --api-only \
  --provider-host api.openai.example/v1 \
  --provider-port 443 \
  --provider-https \
  --provider-api-key-path ~/.config/irecall/provider-api-key \
  --provider-model gpt-4.1 \
  --provider-keyword-model gpt-4.1-mini
./bin/irecall-web auth issue-token --write-token-file ~/.config/irecall/mcp-api-token
./bin/irecall-mcp --token-file ~/.config/irecall/mcp-api-token

Notes:

• --provider-host, --provider-port, --provider-https, --provider-api-key-path, --provider-model, and --provider-keyword-model apply the provider config in memory for that API-only process before LLM-backed routes run.
• --provider-model sets the response/default model used by recall responses, quote refine, and tagging. --provider-keyword-model optionally overrides recall keyword extraction and falls back to --provider-model when omitted.
• The API key is read from the file path at startup. If the file is missing, unreadable, or empty, the server exits with a clear error instead of starting with partial configuration.
• The startup-loaded API key is not persisted back into iRecall's saved settings unless you explicitly save settings through the app later.
• irecall-mcp prefers --token-file or IRECALL_API_TOKEN_FILE so operator deployments do not need to inline the bearer token into shared config.

Testing-only password bypass

For automated testing or local debugging you can still disable the interactive web password setup with --unsafe-no-password-check.

WARNING: This flag disables important auth checks. Only use it in trusted test environments and never for production, operator, or MCP deployments.

Example:

go run ./web --port 9527 --unsafe-no-password-check