ais

# ais

**Save anything under your own keys, recall it by those keys.**

An index in plain text on your own disk, with apps for the phone, the browser and the terminal over it. You save anything (a link, a file, a note, a password) under one or more keys, and recall it by those keys: `ais venice italy` gives back what you saved under both, the way your mind does, by association. It stores only a reference, so your documents stay where you keep them; the index is a view, and your data is never touched. Not a search engine over everyone's web, and not a tagger that guesses: an index of your own things under your own words. Why that matters is [below](#why).

One engine, thin front-ends. The CLI is the contract; the web GUI (`ais --serve`), the Flutter mobile app and a native Win32 wrapper sit over it, and the engine depends on none of them. C, no database, no runtime to install.

A coding agent can call `ais` the way it calls grep, except that it recalls what you filed instead of searching for it again: one line of config, 2,900 tokens a question against 24,500, and 40 of 40 answers exact. [The measurement, and how to reproduce it](#give-an-agent-your-index).

Because it is plain text, it outlives its own tools: your index survives decades of archiving, still opens in fifty years, and exports into anything, no lock-in. Keeping data readable that long is computing's unsolved *digital dark age*, where file formats and the apps that open them die faster than the data. Plain text, readable since the 1960s on any machine with no special program, is the oldest and safest answer.

<p align="center">
  <img src="screenshots/demo.gif" width="78%" alt="Save a photo, two ssh tunnels and a link under your own keys, then recall them by key">
</p>
<p align="center"><em>Save a path, the ssh tunnel you always look up, a link: each under the words you would think of later. Then ask by those words. The same index on the phone:</em></p>
<p align="center">
  <img src="screenshots/android-timeline.png" width="30%" alt="Everything you saved: links, file paths, and encrypted secrets">
  <img src="screenshots/android-search.png" width="30%" alt="Search returns clickable links">
  <img src="screenshots/android-tags.png" width="30%" alt="Browse everything by tag">
</p>
<p align="center"><em>Save links, file paths and notes, recall them by tag; passwords stay encrypted (&#128274;).</em></p>

## Why

**Your memory, yours to keep.**

A search engine and an automatic tagger both answer with the *mean*: what these words mean to most people, what the model saw most often. That is the right answer when you are looking for something everyone knows, and the wrong one when you are looking for something only you saved.

Your keys are the deviation from that mean. "venice" is a week in 2023 for one person, a glass factory for another, a chapter of a thesis for a third. Nothing but you records which one it is, and no amount of training data recovers it, because averaging is precisely what removes it.

So ais does not guess and does not tag for you. It saves what you give it under the words you chose, and hands it back when you say them again. That is the whole trade: you do the small work of naming a thing once, and in exchange the index is yours rather than an average of everyone's, in plain text you control, never taking your files hostage.

See [`about.txt`](doc/about.txt) for the pitch and the memex origin, and [`foundation.md`](doc/foundation.md) for the prior/compression argument behind it.

## Questions

**Why not SQLite, or a database?**
A database is the right tool for an *app*; this is for a *person*. SQLite is a binary file one program understands; ais is line-oriented plain text you can read, grep, diff, and recover by hand. You trade query power you do not need for the durability and transparency of plain text (see [`about.txt`](doc/about.txt)).

**Why not an embedded engine (BerkeleyDB, LMDB, gdbm)?**
Because a bundled engine is a dependency you do not control. An early ais version actually ran on BerkeleyDB (both the Java and the C editions) right as it was acquired and relicensed; this plain-text design is that lesson, learned firsthand. A format only one library version can open is a bet that the library, its license, and its on-disk layout outlive your data; they rarely do. ais has no engine to depend on: any future ais, any unix tool, or any format you migrate to can read the store.

**Is keys-only search not limiting?**
On purpose. The keys you assign *are* the point: they are your prior, your ordering of the world. Full-text search finds words; keys find the meaning you committed to. (`ais --find` still searches values and paths.) To search a document's contents, keep it as a file and index its path.

**Is the built-in web server not a toy?**
It is deliberately minimal and not the main interface. `ais --serve` is one thin wrapper over the CLI, a single-user loop that binds 127.0.0.1 only. The native Win32 app and the Flutter mobile app are other wrappers; the engine depends on none of them. The full front-end map is in [`dev/DISTRIBUTION.md`](doc/dev/DISTRIBUTION.md).

**Is this not just a bookmark manager / recoll / org-mode?**
It overlaps all three and copies none. Not a bookmark manager: it saves *anything* under *any* keys, not URLs in a browser. Not full-text (recoll): it indexes the keys you choose, not document bodies. Not org-mode: no single tree, no app lock-in, no markup to learn, just keys with set algebra (AND / OR) over plain files. The distinctive part is that the index *is your bias*, kept unaveraged and portable.

**Why not embeddings or a vector database?**
An embedding places your note near the average meaning of its words, which is the averaging this index exists to avoid. Recall here is exact: the keys you chose, intersected. A wrong key returns nothing instead of the three nearest neighbours, so an agent gets an answer it can trust or no answer at all, with no index to rebuild, no model to pin, and no similarity threshold to tune. Embedding search is the better tool when you do not know what you filed; keys are the better tool when you do.

**Does it replace my photo library or files?**
No, it points *into* them. For files, photos and pages ais is an index of pointers, not a store of copies: a photo stays in Immich, a file on disk, a page at its URL. You save the *reference* under your own keys and recall it by association; the silo keeps the bytes. It does not compete with Immich or the filesystem, it sits across them as the one associative layer that remembers where a thing is and why it mattered. (Secrets are the one exception: those it stores inline, encrypted, see below.)

**Can it hold passwords? Is it a password manager?**
Yes. A secret is stored encrypted inline (`-e`), so a login lives right next to the context it belongs to, and two things set it apart from a built-in manager. It is **cross-platform**: Apple Keychain and Google Password Manager are locked to one ecosystem, while ais is the same plain-text index on Windows, macOS, Linux, Android and the CLI, so your secrets travel with you. And it is **agent-safe**: decryption is interactive (a passphrase you supply at a terminal or in the app), so an agent reading your index sees an opaque `aisc:` marker, not the secret, with no master key or unlocked vault to drain. What it is *not* is a bulk web-login manager: no autofill, no generation, no shared vaults, so for hundreds of site logins a dedicated cross-platform manager is still more convenient. See [`about.txt`](doc/about.txt).

## Give an agent your index

An agent that greps and reads to find something you already saved pays that cost on every question. Recall by key costs one line, and it is exact: a wrong key returns nothing rather than something plausible.

One line wires it into a client:

```sh
claude mcp add ais -- ais --mcp        # or: {"mcpServers":{"ais":{"command":"ais","args":["--mcp"]}}}
```

That serves `recall`, `find`, `tags` and `timeline` over stdin/stdout. It is read-only, `ais --mcp rw` adds saving, and there is no delete or edit at any setting. Encrypted values stay opaque. It opens your home index, the current named index, or the one `-f` names, and refuses a `.ais/` it merely found by walking up, because a clone can ship one: a project index is served by naming it, `claude mcp add ais -- ais -f /abs/path/of/project/.ais --mcp`, and that line in the client's configuration is the permission. The full picture is in [`doc/MCP.md`](doc/MCP.md).

The same index is memory shared between sessions, between you and an agent, and between agents of different models. On your home index the agent asks you for keys. On a project's or a group's index, named with `-f`, it chooses them from the keys already in use, so the next session, or another model, recalls what was saved by the group's words. An agent saves when asked; left alone it rarely does ([measured](experiment/memory/README.md)). Several agents serve one index at once: reads take no lock, and writes serialize under an exclusive lock. The index syncs between laptops and Android phones, and an iPhone app is in progress. [Details](doc/MCP.md#a-projects-or-a-groups-index), and [what the plain-text file does not show](doc/MCP.md#what-the-file-does-not-show): locking, crash-safe rewrites, an index that answers in milliseconds at a million records, and a merge that survives edits and deletes on devices that were apart.

A skill is the other door, for an agent that already has a shell: [`.claude/skills/ais/SKILL.md`](.claude/skills/ais/SKILL.md), copied into your own project's `.claude/skills/`. It drives the CLI, so it can edit and delete records, which the server cannot at any setting.

The measurement: eight questions, five repeats each, `claude-sonnet-4-6` run both ways over the same corpus, the recall arm answering from the recalled row alone. The index reached the agent as CLI tools, which is the same lookup `ais --mcp` serves ov