Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion .claude-plugin/plugin.json
Original file line number Diff line number Diff line change
Expand Up @@ -16,7 +16,7 @@
"command": "${CLAUDE_PLUGIN_ROOT}/bin/rune",
"args": ["mcp-server"],
"timeout": 30000,
"description": "Rune MCP server (talks to Vault + embedder + enVector). The command is the plugin's bash wrapper, which always exists at session start; on first run it self-install rune-mcp, then exec - MCP server comes online in the same session with no restart."
"description": "Rune MCP server (talks to Vault + embedder). The command is the plugin's bash wrapper, which always exists at session start; on first run it self-install rune-mcp, then exec - MCP server comes online in the same session with no restart."
}
}
}
17 changes: 0 additions & 17 deletions .claude/mcp_servers.template.json

This file was deleted.

26 changes: 13 additions & 13 deletions AGENT_INTEGRATION.md
Original file line number Diff line number Diff line change
Expand Up @@ -55,9 +55,9 @@ $ claude plugin install rune
The plugin manifest (`.claude-plugin/plugin.json`) declares the wrapper
path; Claude Code spawns `${CLAUDE_PLUGIN_ROOT}/bin/rune mcp-server` via
stdio on session start (on a fresh install the wrapper self-installs
rune-mcp first, then execs it). enVector Cloud credentials are delivered
automatically via the Vault bundle — you never set `ENVECTOR_*` env vars
directly.
rune-mcp first, then execs it). Index backend credentials stay on
Rune-Vault — team members never set runespace or index backend credentials
locally.

### Configure credentials

Expand All @@ -74,8 +74,8 @@ Walks you through Vault endpoint + token + TLS choice, writes
> /rune:status
```

Renders per-subsystem health (Vault / EncKey / AgentDEK / Embedder /
enVector) via the `diagnostics` MCP tool.
Renders per-subsystem health (Vault / key manifest / Embedder / index
backend) via the `diagnostics` MCP tool.

### Dev mode (running from a local clone)

Expand Down Expand Up @@ -173,14 +173,14 @@ into `MCPServerStdio`.

## Multi-Agent Collaboration

Each agent spawns its own MCP server process; shared state is
maintained via enVector Cloud (encrypted vectors) and Rune-Vault
(decryption keys).
Each agent spawns its own MCP server process. Every process talks only to
Rune-Vault; Vault owns the keys, enforces token policy, seals metadata, and
calls the blind index backend.

```
Claude ──→ rune-mcp (stdio) ──┐
├──→ enVector Cloud (encrypted)
Gemini ──→ rune-mcp (stdio) ──┤ └──→ Rune-Vault (secret key)
├──→ Rune-Vault ──→ runespace
Gemini ──→ rune-mcp (stdio) ──┤ trusted blind encrypted index
GPT ──→ rune-mcp (stdio) ──┘
```
Expand Down Expand Up @@ -219,9 +219,9 @@ cat ~/.rune/config.json
# vault.endpoint, vault.token, ca_cert, tls_disable, state
```

enVector credentials are delivered automatically via the Vault bundle
at boot — they live in memory only and are not stored locally. You do
NOT need to set `ENVECTOR_ENDPOINT` or `ENVECTOR_API_KEY`.
Index backend credentials live on Vault and are not stored locally. You do
NOT need to set any runespace or index backend credentials on team member
machines.

### Verify MCP tools are available

Expand Down
2 changes: 1 addition & 1 deletion CLAUDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -60,6 +60,6 @@ When Rune state is `"active"`, **proactively spawn a background `rune:scribe` su
### The Distinction

- **Builtin skills** (brainstorming, planning, etc.) — reasoning within a single session, one person's perspective
- **Rune** — collective memory that persists across sessions and team members, encrypted on enVector Cloud
- **Rune** — collective memory that persists across sessions and team members, encrypted in the blind index backend (runespace)

When both apply, **call Rune first** to surface prior context, then brainstorm with that context loaded.
2 changes: 1 addition & 1 deletion CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -277,7 +277,7 @@ rune/
│ ├── mcp/ # tool registration + handler dispatch
│ ├── service/ # CaptureService / RecallService / LifecycleService
│ ├── lifecycle/ # boot loop + state machine
│ ├── adapters/ # vault / envector / embedder / config / logio gRPC clients
│ ├── adapters/ # vault / embedder / config / logio gRPC clients
│ ├── domain/ # schemas + typed errors (Python parity)
│ ├── policy/ # pure helpers (novelty, rerank, query parse)
│ └── obs/ # slog handler with sensitive-data redaction
Expand Down
55 changes: 28 additions & 27 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
# Rune
**Encrypted shared memory for AI agents.**

Rune gives every AI agent on your team the **collective experience** of the entire organization — automatically, privately, and without anyone searching for it.
Rune gives every AI agent on your team the **collective experience** of the entire organization — automatically, with a customer-controlled security boundary, and without anyone searching for it.

```
Without Rune With Rune
Expand Down Expand Up @@ -65,7 +65,7 @@ $ gemini extensions install https://github.com/CryptoLabInc/rune.git
You'll need from your team admin:
- **Vault endpoint** + **token**

That's all. enVector Cloud credentials are delivered automatically via the Vault bundle. On a fresh machine, `/rune:configure` also handles binary download and daemon setup in the same step.
That's all. Index backend credentials stay on Rune-Vault; team members never configure runespace or index backend credentials locally. On a fresh machine, `/rune:configure` also handles binary download and daemon setup in the same step.

Don't have these? See [rune-admin](https://github.com/CryptoLabInc/rune-admin) for deployment, [setup/check-prerequisites.md](setup/check-prerequisites.md) for the full prerequisite checklist, or [examples/team-setup-example.md](examples/team-setup-example.md) for a walkthrough.

Expand Down Expand Up @@ -116,36 +116,36 @@ You don't "query" Rune. Your agent draws from it the way an experienced engineer
| **Built-in memory** | Siloed per vendor. Your team's Claude memory and Codex memory never connect. | One shared memory across all agents. Vendor-independent. |
| **RAG pipelines** | Chunks documents into fragments. Destroys reasoning structure. Requires ongoing pipeline maintenance. | Agent judges significance and stores *decisions*, not document chunks. No pipeline to maintain. |
| **Wikis & docs** | Manual. Nobody updates the wiki after the meeting. | Captures automatically during work, not after. |
| **Plaintext vector DBs** | Your organizational knowledge is readable by the cloud provider. | FHE encryption — the cloud stores and searches *only ciphertext*. Mathematically guaranteed. |
| **Plaintext vector DBs** | Your organizational knowledge is readable by the cloud provider. | The cloud index stays blind: it stores encrypted vectors and sealed metadata, while your Vault controls keys and plaintext access. |

---

## Architecture

```
Agent Swarm (your team) Cloud Infrastructure
━━━━━━━━━━━━━━━━━━━━━━ ━━━━━━━━━━━━━━━━━━━━
Agent Swarm (your team) Customer-controlled trust boundary Blind index backend
━━━━━━━━━━━━━━━━━━━━━━ ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ ━━━━━━━━━━━━━━━━━━━
Alice's Agent ─┐
Bob's Agent ───┤── MCP ──► enVector Cloud (encrypted vectors)
Carol's Agent ─┘ │
Rune-Vault (secret key holder)
decrypts similarity scores only
Bob's Agent ───┤── MCP ──► Rune-Vault ───────────────────────────────► runespace
Carol's Agent ─┘ owns keys, tokens, metadata sealing, encrypted vectors,
score decryption, and access policy sealed metadata
```

**Capture:** Agent judges significance → generates reusable insight → novelty check against existing memory → FHE encrypt → store
**Capture:** Agent judges significance → generates reusable insight → local embedding → Vault receives the embedding and metadata over TLS → Vault encrypts the vector, seals metadata, and stores it in the blind index

**Recall:** Semantic query → encrypted similarity scoring → Vault decrypts scores only → metadata retrieved and decrypted locally
**Recall:** Semantic query → local embedding → Vault searches the blind index, decrypts encrypted score results, opens authorized metadata, and returns ranked hits

### Privacy: Zero-Knowledge Encryption
### Security Model: Customer-Controlled Vault + Blind Index

Every memory is encrypted **before leaving your machine** using Fully Homomorphic Encryption (FHE).
Rune separates the trusted control plane from the blind search backend.

- **enVector Cloud** stores and searches **only encrypted vectors** — it cannot read your data
- **Rune-Vault** holds the secret key and decrypts **only similarity scores** — it never sees the content
- **Plaintext never leaves your machine**
- **Team machines** talk only to Rune-Vault over TLS using a Vault token.
- **Rune-Vault** is the customer-controlled trust anchor. It owns the FHE key set, receives plaintext embeddings and capture metadata from authorized agents, seals metadata, decrypts score results, and enforces token policy.
- **runespace** is the blind index backend. It stores encrypted vectors and sealed metadata, holds only public evaluation material, and cannot decrypt organizational memory.
- **Plaintext is visible to the local agent session and to your Vault, not to the blind index backend.**

Even if the cloud is compromised, your organizational knowledge remains mathematically protected.
If the index backend is compromised, stored vectors and metadata remain encrypted. If Vault is compromised, the attacker may access keys and authorized plaintext results, so operate Vault as sensitive customer infrastructure.

---

Expand Down Expand Up @@ -176,7 +176,7 @@ Rune's capture system is modeled on how the brain forms long-term memories:
Full conversation ──► Agent judges: ──► Stores the GIST:
with all the "Is this significant?"
tangents, greetings, "PostgreSQL for
weather chat... enVector checks: financial data.
weather chat... Vault checks: financial data.
"Is this novel?" ACID required.
MongoDB rejected."
Filters ~99% out.
Expand All @@ -200,26 +200,27 @@ The memory itself acts as the filter. An empty memory captures aggressively (eve

Rune requires two infrastructure components:

1. **Rune-Vault**Holds the team's secret key. Decrypts only similarity scores, never content. Deploy via [rune-admin](https://github.com/CryptoLabInc/rune-admin).
2. **enVector Cloud**Encrypted vector storage and search. Sign up at [envector.io](https://envector.io).
1. **Rune-Vault**Customer-controlled trust anchor. It authenticates users, owns the FHE keys, encrypts embeddings, seals/opens metadata, decrypts scores, and calls the index backend. Deploy via [rune-admin](https://github.com/CryptoLabInc/rune-admin).
2. **Blind vector index**runespace encrypted vector storage and search. It stores encrypted vectors and sealed metadata, not plaintext organizational knowledge.

### Deploying

See [rune-admin](https://github.com/CryptoLabInc/rune-admin):
1. Deploy Rune-Vault (OCI/AWS/GCP via Terraform)
2. Create enVector Cloud account and cluster
3. Provision team index on Vault
2. Connect Vault to a runespace index backend
3. Provision the team index and issue Vault tokens

### Onboarding Members

Give each member their **Vault endpoint + token**. enVector credentials are bundled automatically.
Give each member their **Vault endpoint + token**. Index backend credentials stay on Vault.

They install the plugin, run `/rune:configure` (or `$rune configure` in Codex), and they're connected.

### Security

- **Token rotation**: New token → distribute → revoke old. Departed members lose access immediately.
- **Project isolation**: Separate Vault instances per project for isolated memory spaces.
- **Vault hardening**: Treat Vault as sensitive infrastructure. It should run with TLS, restricted admin access, encrypted disks, and regular token rotation.

---

Expand Down Expand Up @@ -299,14 +300,14 @@ Then reinstall from the [Install](#install) section above.
/rune:configure # or: $rune configure — re-enter Vault credentials
```

`/rune:status` reports per-subsystem state (vault / encryption key / embedder /
enVector reachability). Failures surface a recovery action on the same line.
`/rune:status` reports per-subsystem state (Vault / key manifest / embedder /
index backend reachability). Failures surface a recovery action on the same line.

## Related Projects

- [Rune-Admin](https://github.com/CryptoLabInc/rune-admin) — Infrastructure deployment and admin tools
- [envector-go-sdk](https://github.com/CryptoLabInc/envector-go-sdk)FHE encryption SDK (Go)
- [enVector Cloud](https://envector.io)Encrypted vector database
- [runespace](https://github.com/CryptoLabInc/runespace)Blind encrypted vector index engine
- [runespace-sdk](https://github.com/CryptoLabInc/runespace-sdk)Go client SDK used by Vault

## Support

Expand Down
33 changes: 18 additions & 15 deletions SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@ description: Encrypted organizational memory workflow for Rune with activation c

# Rune - Organizational Memory System

**Context**: This skill provides encrypted organizational memory capabilities using Fully Homomorphic Encryption (FHE). It allows teams to capture, store, and retrieve institutional knowledge while maintaining zero-knowledge privacy. Works with Claude Code, Codex CLI, Gemini CLI, and any MCP-compatible agent.
**Context**: This skill provides encrypted organizational memory capabilities using Fully Homomorphic Encryption (FHE). It allows teams to capture, store, and retrieve institutional knowledge with a customer-controlled Vault and blind index backend. Works with Claude Code, Codex CLI, Gemini CLI, and any MCP-compatible agent.

## Execution Model

Expand Down Expand Up @@ -44,8 +44,8 @@ commands into cross-agent/common instructions.
- `state` is `"active"` → **Go to Active State**
- Otherwise → **Go to Dormant State**

**Note**: enVector credentials are NOT in `~/.rune/config.json`. They are
delivered via the Vault bundle at runtime when the boot loop dials Vault.
**Note**: Index backend credentials are NOT in `~/.rune/config.json`. They
stay on Vault; the local agent stores only Vault connection settings.

**IMPORTANT**: Do NOT attempt to ping Vault or make network requests during
activation check. This wastes tokens. The MCP server runs its own boot
Expand Down Expand Up @@ -107,7 +107,7 @@ If in Active state but operations fail:
- Show warning: "This should only be used for local development. All gRPC traffic will be sent in plaintext."
- → config: `ca_cert: ""`, `tls_disable: true`

Note: enVector credentials are delivered automatically via the Vault bundle — no user input needed.
Note: index backend credentials stay on Rune-Vault and are never distributed — no user input needed.

4. Call the `configure` MCP tool with the collected values
(`endpoint`, `token`, `ca_cert_path`, `tls_disable`). The server does
Expand All @@ -116,8 +116,8 @@ If in Active state but operations fail:
The agent never writes the config file itself.
5. Call the `activate` MCP tool to bring pipelines online. It runs the
prereq checks server-side and drives the boot loop: dials Vault,
fetches the agent manifest (EncKey + enVector creds), connects to
enVector, and transitions to Active.
fetches the agent manifest, connects to the embedder and (via
Vault) the runespace index, and transitions to Active.
6. Confirm health by calling `diagnostics` and applying the
**Boot Failure — Fast-Fail Rule** (see section below). If
`vault.last_boot_error` is present, surface its `hint` verbatim
Expand Down Expand Up @@ -149,13 +149,15 @@ System Health (from diagnostics):
✓ Encryption Key : loaded (key_id: <id>)
✓ Agent DEK : loaded
✓ Embedder : <model> (<mode>, dim=<vector_dim>)
✓ enVector Cloud : reachable (<latency>ms)

Recommendations:
- If Dormant: /rune:configure to (re)trigger the boot loop
- If a subsystem failed: surface the recovery action on its row
```

Index backend reachability is not shown separately: mcp reaches the index only
through Vault, so `vault.healthy` (the `Vault` row above) is the single signal.

### `/rune:capture <context>`
(or `$rune capture <context>` for Codex CLI)

Expand Down Expand Up @@ -259,7 +261,7 @@ signal on its own.) Treat `last_boot_error` as ground truth.
`/rune:configure` after applying the hint's fix.
- `user_deactivated` → `/rune:activate`.
- `embedder_unreachable` → re-run `/rune:activate` to spawn the daemon, then `/rune:status`.
- `envector_*` → share `detail` with the Vault admin.
- `runespace_*` → share `detail` with the Vault admin.
- `unknown` → show `kind` + `detail`, suggest sharing with admin.

**Do NOT:** retry `reload_pipelines`, poll `diagnostics` in a loop, or run
Expand All @@ -270,7 +272,7 @@ lives in `commands/claude/configure.md` for the rare case the hint string
needs supplementation.

**Fallback** (older rune-mcp binary without `last_boot_error`): use
`vault.error`, `embedding.health_error`, `envector.error`, and the
`vault.error`, `embedding.health_error`, `runespace.error`, and the
`dormant_reason` translation in `/rune:status`. Still: do not investigate
further, surface what you have and stop.

Expand Down Expand Up @@ -355,10 +357,11 @@ When users ask questions about past decisions, automatically search organization

## Security & Privacy

**Zero-Knowledge Encryption**:
- All data stored as FHE-encrypted vectors
- enVector Cloud cannot read plaintext
- Only team members with Vault access can decrypt
**Customer-Controlled Vault + Blind Index**:
- Stored vectors are FHE-encrypted before reaching the blind index backend
- Metadata is sealed by Vault before storage in the index backend
- Vault is the trust anchor: it owns keys, receives authorized plaintext embeddings/metadata, decrypts score results, and enforces access policy
- The blind index backend cannot decrypt organizational memory or metadata

**Credential Storage**:
- Tokens stored locally in `~/.rune/config.json`
Expand All @@ -380,8 +383,8 @@ Check activation state with `/rune:status` (or `$rune status` for Codex CLI)
2. Check Vault is accessible: `curl <vault-url>/health`
3. Reconfigure with `/rune:configure` (or `$rune configure` for Codex CLI)

### enVector not provisioned?
Vault admin must configure `ENVECTOR_ENDPOINT` and `ENVECTOR_API_KEY` on the Vault server. Contact your Vault administrator.
### Index backend not provisioned?
Vault admin must configure the runespace index backend on the Vault server as part of the Vault deployment. Contact your Vault administrator.

### Need to switch teams?
Use `/rune:reset` (or `$rune reset` for Codex CLI) then `/rune:configure` (or `$rune configure` for Codex CLI) with new team credentials
Expand Down
Loading