adeelahmad/lense

**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.
Install
That one line is all: it opens an installer in your browser that checks the computer, then either installs with the
defaults in one click (with a model server it finds on the computer) or asks how Lens should run (in Docker or a
microsandbox microVM), the AI model and its key and any extras. Either way it 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. On a Mac with Apple silicon,
Lens.app from the same release installs Lens, runs it without Docker and keeps it in
the menu bar (built, early: not signed yet).
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.
Why Lens
**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.
What you can do with it
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 assets' text and notes, cite exact
moments, find similar content, explore the graph with Cypher or SPARQL or browse it as folders and files, suggest
topics and graph changes, edit and merge entities and topics (with undo), write notes and make podcasts. They sign in
with OAuth and see only what their person may read; the account menu copies the MCP address in one click. A namespace
can also have an MCP server of its own (/mcp/ ) and answer OpenAI's chat completions API for any app,
cited from that namespace alone, each off until its owner turns it on, with API keys that open that one namespace and
nothing else. The same folders and files can be mounted read-only over S3, WebDAV, NFS or SMB, so file managers and
scripts read Lens too. The web app runs on the same REST API, so an agent can do what a person can.
(MCP, one namespace's MCP server,
chat completions, API,
the graph as files, 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