◆───◆───◆
╱ ╲ ╱ ╲ ╱ ╲
◆───◆───◆───◇
╱ ╲ ╱ ╲ ╱ ╲ ╱ ╲
◆───◆───◆╌╌╌◆╌╌╌◆───◇───◇
╱ ╲ ╱ ╲ ╱ · · · · · ╱ ╲ ╱
◆───◆───◆───◇╌╌╌·╌╌╌◇───◇
╱ ╲ ╱ ╲ ╱ ╲ ╱ · · · · · ╱
◆╌╌╌◆╌╌╌◆───◇───◆╌╌╌◆╌╌╌◆
· · · · · ╱ ╲ ╱ ╲ ╱ ╲ ╱ ╲
·╌╌╌·╌╌╌◇───◆───◆───◆───◇
· · · · · ╱ ╲ ╱ ╲ ╱ ╲ ╱ ╲
·╌╌╌·╌╌╌◆╌╌╌◆╌╌╌◆───◇───◇
· · · · · ╱ ╲ ╱
·╌╌╌·╌╌╌◇───◇
· · · · · ╱
·╌╌╌·╌╌╌◇
░░░░░░╗░░░░░░╗ ░░╗ ░░╗░░░░░░░╗░░░░░░░░╗ ░░░░░╗ ░░╗ ░░╗ ░░╗░░░╗ ░░╗░░░░░░░╗
▒▒╔════╝▒▒╔══▒▒╗╚▒▒╗ ▒▒╔╝▒▒╔════╝╚══▒▒╔══╝▒▒╔══▒▒╗▒▒║ ▒▒║ ▒▒║▒▒▒▒╗ ▒▒║▒▒╔════╝
▓▓║ ▓▓▓▓▓▓╔╝ ╚▓▓▓▓╔╝ ▓▓▓▓▓▓▓╗ ▓▓║ ▓▓▓▓▓▓▓║▓▓║ ▓▓║ ▓▓║▓▓╔▓▓╗ ▓▓║▓▓▓▓▓╗
██║ ██╔══██╗ ╚██╔╝ ╚════██║ ██║ ██╔══██║██║ ██║ ██║██║╚██╗██║██╔══╝
╚██████╗██║ ██║ ██║ ███████║ ██║ ██║ ██║███████╗███████╗██║██║ ╚████║███████╗
╚═════╝╚═╝ ╚═╝ ╚═╝ ╚══════╝ ╚═╝ ╚═╝ ╚═╝╚══════╝╚══════╝╚═╝╚═╝ ╚═══╝╚══════╝
Crystalline intelligence for AI agents. Plain markdown underneath.
Psychology splits intelligence in two: fluid intelligence reasons about a new problem in the moment, crystallized intelligence is what learning left behind, the vocabulary, the judgment and the lessons already paid for. A language model is fluid intelligence in its purest form, brilliant in the moment and a stranger at the start of every session. Crystalline is the other half: the crystalline intelligence an agent builds up and keeps, session by session, until it stops being a stranger and becomes a peer.
The difference it makes, in one exchange:
Moving day
You: Here's the washing machine's manual as a PDF. Learn it - I am
never reading 60 pages about laundry.
Agent: Learned it. Captured programs, error codes and maintenance
into home (#appliances), manual attached.
Eight months later, a fresh session
You: The machine is blinking E18 and the display is in Italian??
Agent: Recalled from home: E18 is a blocked drain pump filter.
Front panel, bottom right, quarter turn - towel down first,
about a liter of water comes out.
Get started
Crystalline is one binary. Two commands on a Mac with Homebrew and Claude Code:
brew install jordiboehme/tap/crystalline
crystalline install claude-code
Start Claude Code and say:
Add two domains: books for what I read, and work for this repository. Here is my reading log from the last three years - work out what I actually like. Then capture what this repository is about.
The agent creates both domains with its add_domain tool, a folder with a starter MANIFEST each, captures what it learns from the log and from the repository as engrams, and the next session starts from them.
Fluid, the web UI, is at http://localhost:7411 and the first visit creates your admin account. What the install command wired, and how to undo it: Claude Code setup.
Using Claude Desktop? Install Crystalline first (Homebrew above, or the MSI below), then add the extension: Claude Desktop setup. If you use only Claude Desktop on a Mac, you can take the Desktop-only extension, which carries Crystalline inside.
Via .deb package (Debian, Ubuntu and derivatives, amd64 or arm64):
version=$(curl -fsSL https://api.github.com/repos/jordiboehme/crystalline/releases/latest | grep -m1 '"tag_name"' | cut -d '"' -f4)
arch=amd64 # or arm64
curl -fsSLO "https://github.com/jordiboehme/crystalline/releases/download/${version}/crystalline_${version#v}_${arch}.deb"
sudo dpkg -i "crystalline_${version#v}_${arch}.deb"
crystalline --version
The package ships a systemd unit, installed disabled: see Linux server with systemd to run the daemon as a service. Then crystalline install claude-code and the prompt above.
Via MSI: download crystalline-<version>-windows-amd64.msi (or crystalline-<version>-windows-arm64.msi for Arm devices) from the latest release and double-click it, or install silently with msiexec /i <file> /qn. The installer adds Crystalline to the system PATH and upgrades in place. Windows releases are not code signed yet. Verify the download against SHA256SUMS or with gh attestation verify <file> --repo jordiboehme/crystalline (how), then confirm the SmartScreen prompt (More info > Run anyway).
The MSI also registers a Windows task that starts the Crystalline daemon when you sign in, which is what the Claude Desktop extension connects to.
Every release also ships the standalone crystalline binary for macOS (Apple Silicon and Intel), Linux (x86_64 and arm64, statically linked) and Windows (x64 and Arm64), with a SHA256SUMS file, or build from a clone with cargo build --release. The macOS binaries are code signed and notarized, so Gatekeeper runs them without a prompt.
Why not a memory feature
A chat memory is a hidden blob. One vendor owns it, it is tied to one model, and nobody around the agent can see it, review it, version it or share it. Crystalline is files you own: plain markdown, read by every agent and every person on the team, reviewed like code and kept in your own repositories. Change the model and the knowledge stays.
What sets it apart
- Plain markdown, an open format. An engram is a markdown file with YAML frontmatter in Google's Open Knowledge Format (OKF) v0.2. Any tool reads it, nothing locks you in and the index is disposable:
crystalline reindex --fullrebuilds it from the files. Files are written as UTF-8 with LF line endings; a file with CRLF line endings is read as it is and converted to LF on its next write. - Scales past a folder of files. Domains with MANIFEST routing, hybrid text-plus-semantic search, a knowledge graph and temporal filtering: the ten-thousandth engram is as findable as the tenth.
- Knowledge retires, it does not disappear. A fact that stopped holding is superseded, not overwritten. The old engram stays addressable by date ("what applied last June"), retired knowledge fades in ranking instead of vanishing and
crystalline evolvetells you what the archive needs next. - Agents and people share one intelligence. Agents work over MCP, people work in Fluid, and a team shares through GitHub pull requests, with review mode and private drafts for a domain that wants a gate.
- Many ways to the right engram, and all of them fast. An agent does not have to guess one query. It searches by meaning, follows typed relations through the graph, filters by tag or status, walks the links between engrams and pulls a whole neighborhood in one call. At ten thousand engrams a search comes back in well under half a second, so looking before answering costs it nothing.
- Hello · Hallo · Hola · Bonjour · Ciao · Olá · Hoi · Ahoj · مرحبا · こんにちは · 안녕하세요 · 你好. Search is multilingual: the built-in embedding model reads more than 200 languages, 52 of them with retrieval training, so a German engram answers an English question and the other way round, and a domain that mixes languages needs no translation.
Fluid
The primary author in Crystalline is the agent. Fluid is how you take part: read what was learned, correct a fact, add knowledge of your own, in the browser, without spending a token. It is built into the binary and on by default at http://localhost:7411. An engram is a page, the editor previews live, everyone in the same engram sees each other's cursors, search is the same hybrid ranking the agents use and a maintenance page shows what the knowledge needs next. The full tour: Fluid, the web UI. Pages can use callouts, status labels, math, task lists, footnotes and diagrams, and pasting from a wiki or a browser becomes clean Markdown: The Markdown Crystalline understands.
Deployment
Crystalline runs the same way in every scenario: a daemon in the middle keeps one search index in sync with knowledge, and one or more agents connect to it, whether over a local stdio pipe or a network HTTP endpoint. docs/deployment.md walks through every shape with one diagram per scenario, plus running the container image, configuring through environment variables and read-only serving.
Go deeper
- The Crystalline Handbook is the book-length guide: the idea, the system, installation and the full working loop, written to be read in an evening or to run a training from. Read it online at https://jordiboehme.github.io/crystalline/, or download the PDF or the EPUB.
- The docs: setup per harness, how an agent learns, teams, verify and evolve, the Reflection, virtual domains, architecture.
- FAQ: the short answers, and why not just a folder of files.
- Deployment: every scenario from a laptop to an air-gapped server, one diagram each.
- Security: what Crystalline reads, writes and sends, how to close the local listener, and how to verify a release.
- Found a rough edge or a missing piece? Open an issue - and if Crystalline made your agent a better peer, a star helps others find it.
Support
Crystalline is free and open source. If it earned its place in your workflow, you can support the work here:
Privacy Policy
Crystalline is local-first: no telemetry, no analytics, no accounts and no data collection by the developer. Every engram lives as a markdown file plus a local search index on your own machine, entirely under your control.
Crystalline never sends your knowledge to a language model: the model runs in your agent harness, which receives what Crystalline answers and passes it to the provider you chose there.
One outbound connection happens by default:
- Hugging Face, for a one-time download of the local embedding model. It starts automatically on first start, or explicitly with
crystalline model download, and sends no engram data. Once the model is cached, no further call is made. PointHF_ENDPOINTat a mirror, orCRYSTALLINE_MODELS_DIRat a pre-fetched copy, to avoid the connection. Governed by the Hugging Face privacy policy.
Every other connection exists only after you turn it on:
- GitHub, once you turn on team collaboration (
crystalline config set github.enabled trueandcrystalline connect github). It uses your own OAuth token, and engram data flows only to the repositories you choose to share it with.github.api_urlpoints it at a GitHub Enterprise server instead. Governed by GitHub's privacy statement or your own server's terms. - Hugging Face again, once you turn on the contradiction check (
evolve.contradictions), for a one-time download of its local NLI model into the same cache. It sends no engram data. - Your single sign-on provider, when you configure OIDC sign-in for the web UI. Crystalline talks to the issuer you name.
- A remote embedding service, when you set
embeddings.provider: openai-compatibleinconfig.yaml. The text of your engrams is then sent to the endpoint you configure, to compute its embeddings. The default provider is local and sends nothing. - A PostgreSQL server, when you set
database.backend: postgresanddatabase.urlto share one search index between instances. The index holds the text of your engrams. - A Crystalline server you connect to, after
crystalline connect <url>(or withCRYSTALLINE_REMOTE_URLandCRYSTALLINE_REMOTE_TOKENset). Searches and engram reads and writes for its domains go to that server, under your account there. A search over all domains also sends the search text to it. Your local engrams stay on your machine.
Nothing else leaves the machine.
The developer shares nothing with anyone. Data retention is entirely user-controlled: deleting a domain or an engram deletes the data, and uninstalling Crystalline leaves your markdown untouched.
Questions: [email protected].
License
Mozilla Public License 2.0 - see LICENSE.