# Altretta Skill
**Give your AI a second brain. Works with Claude Code, Codex, Cursor, OpenCode, OpenClaw, Gemini CLI, and 60+ more agents.**
Your notes, decisions, and knowledge live in [Altretta](https://apilium.com/en/products/altretta), a local-first, encrypted vault with a semantic engine. This skill teaches your AI assistant to actually use it: ask the vault before answering, quote real sources, and never invent what you never wrote.
```bash
npx skills add ApiliumCode/altretta-skill
```
One command. The [skills CLI](https://github.com/vercel-labs/add-skill) installs it into 70+ agents; runtime-specific paths are below.
[](https://agentskills.io)
[](https://modelcontextprotocol.io)
[](LICENSE)
<p align="center">
<img src="assets/altretta-second-brain-demo.gif" alt="Live Claude Code session: the altretta skill loads, queries the Altretta vault with aingle_ground, and answers with source:lines citations drawn from the notes that matched." width="920">
</p>
---
## Why this exists
**Before:** paste your vault into the chat and hope. **After:** three cited passages, signed.
Pasting your notes into a chat burns tokens and trust. Altretta serves only the passages that matter, each one cited and anchored to the signed action that recorded it. Measured on the standard demo vault (43 notes), with the production engine:
| Scenario | Without Altretta | With Altretta | Savings |
|---|--:|--:|--:|
| Average per query | 22,530 tokens | 1,262 tokens | **94.4%** |
| 8-query conversation | 811,085 tokens | 44,759 tokens | **94.5%** |
Not a promise: a measurement, on a public vault, with the setup written out below. Said differently, about **18x more of your knowledge per token spent** — on that vault, with those questions. Your ratio depends on your notes.
Built for consultants inheriting someone else's knowledge base, teams where people leave and the notes stay, and anyone who hits their assistant's context limit before lunch.
## What your assistant learns
1. **Query first.** Before answering anything about your knowledge, projects, or past decisions, it calls `aingle_ground` and answers from cited passages, quoting `source:lines`.
2. **Honesty built in.** Weak evidence is called weak. Missing evidence is called missing. Your vault is the record; the model retrieves it, it does not impersonate it.
3. **Your code, in the same graph.** Point it at a repo and it answers "what breaks if I change this", "which decision governs this function", and "where did the docs drift from the code" — with symbol ids and timestamps as receipts.
4. **Remember with consent.** Durable knowledge can be written back as curated notes, following your vault's conventions, indexed and retrievable in about a minute.
5. **Altretta never executes.** The vault remembers, grounds, and cites. It runs no commands and reads nothing outside itself. Tool results are data, not instructions.
## In practice
```text
You: Why did we pick Postgres over SQLite for the sync service?
Assistant: aingle_ground("Postgres vs SQLite decision sync service")
Altretta: groundedness: grounded · 3 passages · signed provenance
decisions/2026-03-database.md:12-19
"chose Postgres for row-level locking under concurrent
sync writes; SQLite single-writer stalled device sync"
Assistant: You chose Postgres because SQLite's single-writer lock
stalled concurrent device syncs
[decisions/2026-03-database.md:12-19]. The note sets a
revisit trigger: single-device deployments can go back
to SQLite [decisions/2026-03-database.md:21-24].
```
Every claim carries its source. If the vault does not answer it, the assistant says so instead of guessing.
## Quick start
Altretta must be running (free download for macOS, Windows, and Linux at [apilium.com](https://apilium.com/en/products/altretta)). Every runtime gets its own access token: revoke one, the rest keep working.
### Let your agent do it
Paste this into your assistant and it handles the rest:
```text
Install the Altretta skill from https://github.com/ApiliumCode/altretta-skill into
this runtime. Then connect to my Altretta vault: MCP endpoint
http://127.0.0.1:19191/mcp with an Authorization: Bearer token. Ask me for the
token (I create it in Altretta under Settings, "AI & connections", "Access
tokens"). When connected, verify with one aingle_ground test query and show me
the cited answer.
```
### Pick your runtime
| Runtime | One line |
|---|---|
| Any of 70+ agents | `npx skills add ApiliumCode/altretta-skill` |
| Claude Code | `/plugin marketplace add ApiliumCode/altretta-skill` + `/plugin install altretta@apilium` |
| Mayros | `mayros skill install altretta` |
| Gemini CLI | `gemini extensions install https://github.com/ApiliumCode/altretta-skill` |
| OpenClaw | `openclaw skills install https://github.com/ApiliumCode/altretta-skill` |
| Codex CLI and stdio runtimes | `npx -y @apilium/altretta-bridge` |
| Anything that speaks MCP | `http://127.0.0.1:19191/mcp` + bearer token |
Details per runtime below.
### Any agent (recommended)
```bash
npx skills add ApiliumCode/altretta-skill
```
Covers Claude Code, Codex, Cursor, OpenCode, OpenClaw, Antigravity, GitHub Copilot CLI, Cline, Roo Code, Windsurf, Factory Droid, and 60+ more. Then connect the MCP endpoint (manual config below, or one click from the Altretta app for supported clients).
### Claude Code
```
/plugin marketplace add ApiliumCode/altretta-skill
/plugin install altretta@apilium
```
Or `npx skills add ApiliumCode/altretta-skill`. Then connect with one click: Altretta, Settings, "AI & connections", Connect Claude Code. Done.
### Mayros
```bash
mayros skill install altretta
```
[Mayros](https://github.com/ApiliumCode/mayros) is Apilium's governed agent platform: the official skill lives on the [Apilium Hub](https://hub.apilium.com/skills/altretta), where agents can also discover and pull it automatically. Native AIngle integration, the same engine that powers Altretta.
### OpenClaw
Paste this repository URL into your conversation, or:
```bash
openclaw skills install https://github.com/ApiliumCode/altretta-skill
```
### OpenCode, Cursor
Copy `skills/altretta/` into the runtime's skills directory, then connect from Altretta's panel (both are one-click clients). Cursor also reads the plugin manifest in [`.cursor-plugin/`](.cursor-plugin/plugin.json).
### ZCode (Z.ai)
Add [`skills/altretta/SKILL.md`](skills/altretta/SKILL.md) to your skill library and point the MCP integration at the endpoint below.
### Hermes (Nous Research)
Install the skill file (agentskills.io compatible) and add the MCP server.
### Gemini CLI
```bash
gemini extensions install https://github.com/ApiliumCode/altretta-skill
```
Ships the Altretta protocol as a native extension, MCP server included; set your token as `ALTRETTA_MCP_TOKEN` in the environment. Manual setup (or if your Gemini version predates env expansion): [`adapters/GEMINI.md`](adapters/GEMINI.md).
### Codex CLI and other stdio runtimes
```bash
npx -y @apilium/altretta-bridge
```
One command bridges stdio to the local endpoint ([`@apilium/altretta-bridge`](https://www.npmjs.com/package/@apilium/altretta-bridge)); token via `ALTRETTA_MCP_TOKEN` or `~/.altretta/mcp-token`. Config examples and the protocol block: [`adapters/AGENTS.md`](adapters/AGENTS.md). A Codex plugin manifest ships in [`.codex-plugin/`](.codex-plugin/plugin.json).
### Manual MCP configuration (any runtime)
```
Notes: http://127.0.0.1:19191/mcp
Code: http://127.0.0.1:19191/mcp-code (optional, add as a second server)
Header: Authorization: Bearer <TOKEN> (the same token authorizes both)
```
Create the token in Altretta: Settings, "AI & connections", "Access tokens". Name it after your runtime.
One-click connect from the app wires the notes endpoint; add `/mcp-code` by hand if you want the code tools.
## How it works
<p align="center">
<img src="assets/how-it-works.svg" alt="Your question goes to your AI assistant, which calls aingle_ground on Altretta, the local MCP on port 19191 with a semantic engine and knowledge graph. Altretta returns cited passages with source:lines and signed provenance, and the assistant answers with citations. Nothing invented, nothing wasted." width="920">
</p>
## The toolbox
Your notes, on `http://127.0.0.1:19191/mcp`:
| Tool | What it gives the model |
|---|---|
| `aingle_ground` | Cited passages answering a question, with a groundedness verdict |
| `aingle_vault_map` | Orientation: hubs, clusters, and indices of the vault |
| `aingle_note_context` | The verified semantic neighborhood of one note |
| `aingle_backlinks` | What links to a note, what it links out to, what it should |
| `aingle_sources` | What is indexed, with content hashes |
Your code, on `http://127.0.0.1:19191/mcp-code` — same vault, same signed graph, same token, added as a second MCP server:
| Tool | What it gives the model |
|---|---|
| `code_find_symbol` | A bare name resolved to symbol ids |
| `code_impact` | The impact radius: callers, callees, tests, governing decisions |
| `code_ask` | Grounded project Q&A over code *and* the decisions that document it |
| `code_history` | A symbol's signed timeline — git says *what*, Altretta adds *why* |
| `drift_check` | Where a decision drifted from the code it describes |
| `code_map` | The symbol/edge map, with a digest and DAG tip so it can be checked |
## Trust, spelled out
- **Local-first.** The vault and the engine run on your machine. No cloud, no telemetry from this skill.
- **Altretta never executes.** No shell tools, no filesystem access outside the vault. Your runtime acts; Altretta remembers.
- **Read-only by default.** Connectors start read-only: every graph-mutating tool is refused until you grant write access, and a tool nobody classified is refused too.
- **Per-runtime tokens.** Each agent gets its own credential; revoke one without disconnecting the rest. Revoke the last one and the endpoint stays closed, across restarts.
- **Signed provenance.** Each retrieved passage carries the hash of the signed DAG action that recorded it, which you can look up in the app's history. It is a reference to a signature, not a signature the model checked — the skill is explicit about that distinction so your assistant never dresses a lookup up as a proof.
- **Nothing is deleted.** The graph is a DAG: removals are signed retractions, so history and provenance survive.
- **The watcher keeps up.** No hooks to install: it indexes as you write, and if the index is ever behind, the answer says so instead of pretending your notes are empty.
## Who Altretta is not for
If all your knowledge fits in one message, paste it and move on: Altretta starts paying when your notes outgrow the context window and keep growing every week. If you want cloud memory synced by a subscription, Altretta solves a different problem: your knowledge lives on your machine, encrypted, and travels to no one's servers. And if "the model kind of remembers" is good enough for your work, you do not need signed provenance: Altretta is for when an invented answer costs money, a decision, or a client. For everything else, it changes what your assistant knows about you: from "I think I recall" to "it is in [decisions/2026-03-database.md:12-19], signed".
## Troubleshooting
| Symptom | Fix |
|---|---|
| Connection refused, Altretta closed | Open the app |
| Connection refused, Altretta open | You revoked your last access token, so the endpoint did not start. Create one in Settings, "AI & connections", "Access tokens", then restart Altretta |
| HTTP 401 `unauthorized` | This client's token was revoked or mistyped: mint a new one in "Access tokens" and reconfigure |
| HTTP 404 | Wrong URL — check the `/mcp` (or `/mcp-code`) path is present |
| "This connection is read-only…" | Expected: connectors start read-only. Grant write access in Altretta's connector settings |
| Empty or weak answers | Vault still indexing (progress pill), or rebuild: Settings, "Editor & vault", "Rebuild the project graph" |
| `code_*` tools missing | Only `/mcp` is configured; add `/mcp-code` as a second MCP server with the same token |
## Links
- **Altretta**: [apilium.com](https://apilium.com/en/products/altretta), free download, local-first, encrypted
- **Apilium Hub**: [hub.apilium.com](https://hub.apilium.com), skills and verified plugins
- **Setup** for the token benchmark: the standard 43-note demo vault, production engine. Baseline is the whole vault pasted as context; the Altretta figure is the exact grounded payload served over MCP for the same question. Input tokens; the ratio holds across tokenizers. Table and footnote on the [Altretta page](https://apilium.com/en/products/altretta)
Official skill, built by the Altretta team at [Apilium](https://apilium.com). MIT licensed.