Safe, secure and cost-effective.
Connect your live data streams; Lens turns them into a cited knowledge graph your agent can reason over, through MCP, a REST API or its own assistant. It runs on your hardware with local models or any cloud model, private by default and cost-aware.
curl -fsSL https://raw.githubusercontent.com/adeelahmad/lense/main/install.sh | shThat one line is all: it opens an installer in your browser that checks the computer, asks how Lens should run (in
Docker or a microsandbox microVM), the AI model and its key and any extras, then installs
what's missing (Docker included), starts Lens and opens its setup page
(details). Run it again to update. On Windows, run
irm https://raw.githubusercontent.com/adeelahmad/lense/main/install.ps1 | iex in PowerShell; or skip the terminal and
double-click the launcher for your system from the latest release.
Deployment covers servers and Cloudron; there are also packages for
Synology, QNAP and Proxmox.
To work on the code instead, make run builds and runs everything from a checkout, make setup-code prints the
first-admin setup code, and make dev runs it with hot reload; see Get started.
AI doesn't lack intelligence. It lacks structure. Lens gives your agent eyes. Without structure, every prompt is a guess about who you are and what happened. Lens supplies the people and things involved, how they relate, what happened when, and the source of each fact, so your agent stops guessing.
Lens is one private AI hub for your whole life. Every source is a sensor: recordings, documents, email, calendars, web pages, chat rooms, devices and webhooks all flow in, and everything becomes memory you can trust, because every answer cites where it came from, down to the second of a recording or the line of a document. It runs on your own hardware, from a Raspberry Pi to the cloud, and you own every byte.
Lens is built first for agents and AI assistants. People talk to their agent in chat, by voice, or in Slack, WhatsApp and other chat rooms; the web app is for setup, settings, pipelines and workflows, review, debugging and the charts that show what is in the archive and what it cost.
Lens is also infrastructure to build on. An app built on Lens, such as an email responder or a customer manager, starts with real, structured context (who is involved, what was said, what was decided, with sources) instead of a blank prompt. Apps reach it the same way agents do: through the MCP server, the REST API and OAuth sign-in, limited to what their person may read.
Everything below is built and merged. Work that is still in a pull request is listed under In progress.
- Connect your agents. Lens is an MCP server (
/mcp): agents search, read transcripts and notes, cite exact moments, explore the graph with Cypher or SPARQL, suggest topics and graph changes, write notes and make podcasts. They sign in with OAuth and see only what their person may read. The web app runs on the same REST API, so an agent can do what a person can. (MCP, API, authentication) - Ask, and get cited answers. A chat assistant on every page, and by voice, searches your archive by words (and by
meaning, once turned on), reads it, cites it and acts on it with tools: changes wait for your approval. It reads
answers aloud with your speech provider, and
/clearand/compactkeep long conversations short. Each namespace can have its own assistant with its own name, instructions and memory, answering in Slack, Discord, Telegram, Matrix, WhatsApp and other chat rooms through Matterbridge. (Chat, chat rooms, speech providers) - Extend the assistant. Add tools (a prompt, a web request, a graph drawn on the canvas, or sandboxed Python), skills, hooks and remote MCP servers, by code, on the canvas or just by asking. Install skills and plugins from marketplaces in the open plugin format, or from a repository or an archive. (Extending the assistant)
- Bring in everything. Watched folders on S3, Dropbox, Google Drive, OneDrive, SFTP, SMB, WebDAV or local disks; IMAP mail and iCal calendars; a built-in MQTT broker, syslog and webhook streams; import webhooks for scanners and phone shortcuts. Upload audio, video, PDFs, Office files, photos, JSON and zip or tar archives; capture web pages one at a time, from a link list or a bookmarks file, by API or by asking the assistant; and import videos and podcasts by their address (off by default). (Sensors, processing, import webhooks)
- Clip from the browser. The Lens web clipper for Chrome turns a page, a selection or a part you pick into Markdown, lets you look it over, and sends it to a namespace. (Web clipper)
- Understand it. Transcription and speaker recognition, text on screen and in scans, faces (off by default), entities and topics in a knowledge graph you can explore, query with Cypher or SPARQL, and see as it was at any version. With anytopdf, photos are found by what they show. (Graph, graph history, topics, video)
- Learn from it. Make a two-host podcast episode about what you pick, every claim cited and checked against its source, read aloud in two voices. Keep notes beside every recording, entity and topic, written by you or the assistant, and export a resource or a collection as an evidence PDF. (Podcasts, notes, evidence PDFs)
- Automate it. Pipelines and workflows on a canvas, routines on a schedule, batch runs over a collection, and notifications to webhooks, Slack, Discord and Matterbridge. (Processing, notifications)
- See what it costs. An activity ledger of every model call, with reports, charts and budgets that cap spending. Routine choices go to small decision models, and the LLM only when it adds value. (Activity and costs, budgets)
- Keep it up to date. Lens checks for a new release once a day and tells admins by email or a notification. It backs the database up and upgrades itself through a small agent on the machine, from the API; nothing installs unless an admin says so. (Updates and backups)
- Watch it run. OpenTelemetry traces and metrics, and a Prometheus
/metricsendpoint with a sample Grafana dashboard. Both are off until you turn them on, and send nothing anywhere else. (Telemetry, Prometheus) - Stay private. Passkeys instead of passwords, encryption at rest with a key per namespace, roles per namespace, and an audit log. Reach it from anywhere through a Cloudflare tunnel with nothing opened on your router. (Encryption, access, remote access)
- Use open standards. RDF and Dublin Core for every record, OAuth for apps and OpenID Connect sign-in, MCP, MQTT, IIIF for publishing, OpenTelemetry and Prometheus for monitoring, and an optional Fedora mirror. (Linked data, IIIF, Fedora)
Lens runs on a small machine. Heavy parts (local speech models, a local LLM, document conversion, Fedora) stay off or download only when you turn them on, and any of them can be swapped for a cloud provider instead. Every setting lives in the web app. (Components, speech providers, local models)
These are open pull requests, not yet part of Lens:
- Chat channels: a built-in Telegram bot on a shared channel layer (#293) and a Slack app over Socket Mode (#287), without Matterbridge.
- Costs: a budget meter in the top bar and a Costs page (#275), and an overall AI budget with soft and hard limits asked for in setup (#281).
- Upgrades and backups in the web app: an upgrade page with live steps that rolls back when the new version doesn't start (#262), and restore, download links and scheduled backups (#263).
- Running it: HTTPS with certificates from Let's Encrypt or ZeroSSL (#289), structured logs with a log viewer and syslog output (#284), built-in usage analytics (#274), and Prometheus and Grafana as an opt-in service (#297).
- People: email invitations, and removing someone for good (#286).
- Lens.app for macOS: a menu-bar app that carries microsandbox (#280).
- The web clipper for Firefox (#282), Safari (#283) and Edge (#285), with releases that update themselves (#294).
- Files: assets shown as folders and files by namespace and collection (#290) and shared read-only over NFS (#295); items called assets unless they are audio or video (#273).
- Reading and search: documents read by an Apache Tika server (#292), content similar to a text, a resource, a topic or an entity (#296), and reading aloud with StyleTTS2 on this machine (#291).
fastapi_backend/ |
FastAPI API (/api/v1), MCP server, the processing engine, and the lens CLI and workers |
nextjs-frontend/ |
Next.js web app with a typed client generated from the API's OpenAPI schema |
extensions/browser/ |
the web clipper browser extension |
installer/ |
the web installer and the double-click launchers |
| SurrealDB | documents, graph edges, the job queue and graph history; word search in a small SQLite index beside it |
The guides are on the docs site and in the docs folder:
- Start: Get started, deployment, microsandbox, configuration, components, updates and backups, remote access
- Agents and apps: MCP server, API, authentication, access
- Use: chat and batch runs, chat rooms, podcasts, notes, web clipper, sensors, processing, video, notifications
- Knowledge: graph and Cypher, graph history, topics, linked data (RDF), IIIF, Fedora
- Models and cost: local models, speech providers, activity and costs, budgets
- Operate: encryption, storage, database, telemetry, Prometheus
- Build: architecture, web app, technology, API work the design needs, contributing, agent rules
Security, threat model, changelog.
Lens is open source under the MIT License. Optional extras that you install yourself may carry their own
licenses (for example extract-msg, GPL-3.0, for Outlook .msg files); none is part of the default install.
Built on the Next.js FastAPI Template (MIT).