feat(plugins): ADR-098 Part 1 (slice 2/4) — encryption-at-rest notes for memory plugins

Adds ADR-096 references to ruflo-rag-memory and ruflo-rvf — the two
plugins whose write surfaces (.swarm/memory.db and
.claude-flow/sessions/*.json) are now opt-in encrypted at rest.

ruflo-rag-memory/README.md:
  New "Encryption at rest (ruflo 3.6.25+)" section before "Memory
  Namespaces". Covers:
  - Each .swarm/memory.db write encrypted with fresh 12-byte IV via
    writeFileRestricted({encrypt:true})
  - Reads use readFileMaybeEncrypted(path, null) — RFE1 magic-byte
    sniff for backward compat (legacy plaintext memory.db still works)
  - Embeddings encrypted along with the SQLite blob — no separate
    column-level encryption needed for Phase 1
  - Tamper detection: flipped byte fails GCM auth, throws on read
  - ruflo doctor -c encryption reports gate state

ruflo-rvf/README.md:
  New section between Features and Commands explaining session
  persistence's relationship to the encryption gate:
  - Off-by-default: plaintext JSON at mode 0600 (legacy behavior)
  - On: AES-256-GCM session saves, transparent decrypt on restore
  - Important caveat: when exporting RVF files for cross-machine
    transfer, the gate doesn't apply to the exported bytes — that's
    transport security, separate from at-rest. Sealed-box backups
    are the next phase per ADR-096.

Plugin versions:
  ruflo-rag-memory  0.1.0 → 0.2.0 (minor — capability sync)
  ruflo-rvf         0.1.0 → 0.2.0 (minor — capability sync)

ADR-098 Part 1 progress: 2/4 slices done. Remaining:
  - slice 3: ruflo-cost-tracker — federation budget breaker pairing,
    federation_spend events
  - slice 4: ruflo-agentdb + ruflo-knowledge-graph — G7 controllers
This commit is contained in:
Reuven committed 2026-05-03 22:05:33 -04:00
1 parent 6a40574745
commit 6130f4061c
4 files changed
+24 -2

No files matched your search

@@ -1,7 +1,7 @@
{
"name": "ruflo-rag-memory",
"description": "RuVector memory with HNSW search, AgentDB, and semantic retrieval",
"version": "0.1.0",
"version": "0.2.0",
"author": {
"name": "ruvnet",
"url": "https://github.com/ruvnet"
+11
View File
@@ -73,6 +73,17 @@ Claude Code Auto-Memory (~/.claude/projects/*/memory/*.md)
Semantic Search (150x-12,500x faster)
```
## Encryption at rest (ruflo 3.6.25+)
The AgentDB SQLite blob written by this plugin (`.swarm/memory.db`) supports opt-in AES-256-GCM encryption at rest per [ADR-096](../../v3/docs/adr/ADR-096-encryption-at-rest.md). When `CLAUDE_FLOW_ENCRYPT_AT_REST=1` and `CLAUDE_FLOW_ENCRYPTION_KEY` is set:
- Each write of `.swarm/memory.db` is encrypted with a fresh 12-byte IV (`writeFileRestricted({encrypt:true})`).
- Reads use `readFileMaybeEncrypted(path, null)` — magic-byte sniff (`RFE1`) so legacy plaintext memory.db files keep working unchanged during the migration window.
- Embeddings are encrypted along with the rest of the SQLite blob — no separate column-level encryption needed for Phase 1.
- A flipped byte fails GCM auth and produces a decrypt error rather than silent corruption.
Verify gate state with `ruflo doctor -c encryption`. Off by default; flipping it on doesn't require a migration step (legacy plaintext bytes are sniffed on read; first write after enable rewrites the DB encrypted).
## Memory Namespaces
| Namespace | Purpose | Example Key |
+1 -1
View File
@@ -1,7 +1,7 @@
{
"name": "ruflo-rvf",
"description": "RVF format for portable agent memory, session persistence, and cross-platform transfer",
"version": "0.1.0",
"version": "0.2.0",
"author": {
"name": "ruvnet",
"url": "https://github.com/ruvnet"
+11
View File
@@ -17,6 +17,17 @@ RVF format for portable agent memory, session persistence, and cross-platform tr
- **Claude memory bridge**: Import Claude Code auto-memories into AgentDB
- **Format migration**: Upgrade RVF files across versions
## Encryption at rest (ruflo 3.6.25+)
Sessions persisted by this plugin land at `.claude-flow/sessions/*.json`, which are written through `fs-secure.writeFileRestricted({encrypt:true})` per [ADR-096](../../v3/docs/adr/ADR-096-encryption-at-rest.md). Behavior under the gate:
- **Off by default** (`CLAUDE_FLOW_ENCRYPT_AT_REST` unset / falsy) — sessions are plaintext JSON at mode 0600, same as ruflo 3.6.24 and earlier.
- **On** (`CLAUDE_FLOW_ENCRYPT_AT_REST=1` + `CLAUDE_FLOW_ENCRYPTION_KEY` set to 64-char hex or 44-char base64) — each session save is AES-256-GCM with `RFE1` magic-byte prefix. Session restore transparently decrypts via the magic sniff; legacy plaintext sessions still load unchanged during migration.
When **exporting RVF files for cross-machine transfer**, the encryption gate does NOT apply to the exported bytes — the encryption is at-rest on the *originating* host. If the RVF is itself sensitive, transport security (sealed boxes / signed blobs) is the next phase per the ADR roadmap.
Confirm the gate state with `ruflo doctor -c encryption`.
## Commands
- `/rvf` -- Memory stats, saved sessions, storage metrics