# mnemoclaw/immune architecture

> Architecture diagram of the GitHub repository mnemoclaw/immune, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/mnemoclaw/immune
- Repository: https://github.com/mnemoclaw/immune

## Overview

Immune is an adaptive memory system for AI-agent prompts: it retrieves positive strategies before generation, scans generated output for known or new errors, and updates memory from results. The README documents the overall workflow and capabilities; sampled adapter excerpts confirm hybrid retrieval, deduplication, session logging, and persistent storage. The adapter’s full command wiring and the scan instructions were not sampled, so uncertain implementation-level links are omitted.

Main entry points: [`immune-adapter.js`](https://github.com/mnemoclaw/immune/blob/master/immune-adapter.js) (JSON memories), [`immune-inject.js`](https://github.com/mnemoclaw/immune/blob/master/immune-inject.js) (Strategy injection), [`agents/immune-scan.md`](https://github.com/mnemoclaw/immune/blob/master/agents/immune-scan.md) (Immune scan)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_prompt["Prompt preparation"]
  node_hook["Prompt hook<br/>[immune-inject.js]"]
  node_domain["Domain detection<br/>[immune-inject.js]"]
  node_injection["Strategy injection<br/>[immune-inject.js]"]
end

subgraph group_learning["Scan and learning"]
  node_scan["Immune scan<br/>[immune-scan.md]"]
  node_correction["Error correction<br/>[immune-scan.md]"]
  node_learning_write["Pattern learning<br/>[immune-adapter.js]"]
  node_dedup["Pattern dedup<br/>[immune-adapter.js]"]
  node_scoring["Output scoring<br/>[immune-adapter.js]"]
  node_session["Session logging<br/>[immune-adapter.js]"]
end

subgraph group_retrieval["Memory retrieval"]
  node_search["Hybrid retrieval<br/>[immune-adapter.js]"]
  node_embedding["Local embeddings<br/>[immune-adapter.js]"]
  node_fts["FTS4 search<br/>[immune-adapter.js]"]
  node_fusion["RRF ranking<br/>[immune-adapter.js]"]
end

subgraph group_state["Memory state"]
  node_housekeeping["Memory housekeeping<br/>[immune-adapter.js]"]
  node_json[("JSON memories<br/>[immune-adapter.js]")]
  node_sqlite[("SQLite index<br/>[immune-adapter.js]")]
end

node_user(("Agent user"))
node_generation["Output generation"]
node_model{{"Compatible model"}}

node_user -->|"submits prompt"| node_hook
node_hook -->|"detects domains"| node_domain
node_domain -->|"selects strategies"| node_injection
node_injection -->|"reads strategies"| node_json
node_injection -->|"injects context"| node_user
node_user -->|"requests output"| node_generation
node_generation -->|"scans output"| node_scan
node_scan -.->|"checks errors"| node_model
node_scan -->|"reports errors"| node_correction
node_correction -->|"learns patterns"| node_learning_write
node_learning_write -->|"checks duplicates"| node_dedup
node_dedup -->|"updates memories"| node_json
node_search -->|"ranks semantically"| node_embedding
node_search -->|"finds keywords"| node_fts
node_embedding -->|"returns ranked matches"| node_fusion
node_fts -->|"returns ranked matches"| node_fusion
node_fusion -->|"loads patterns"| node_json
node_fts -->|"queries index"| node_sqlite
node_learning_write -->|"syncs index"| node_sqlite
node_scoring -->|"updates scores"| node_json
node_session -->|"writes context log"| node_json
node_session -->|"indexes session"| node_sqlite
node_housekeeping -->|"archives patterns"| node_json

click node_hook "https://github.com/mnemoclaw/immune/blob/master/immune-inject.js"
click node_domain "https://github.com/mnemoclaw/immune/blob/master/immune-inject.js"
click node_injection "https://github.com/mnemoclaw/immune/blob/master/immune-inject.js"
click node_scan "https://github.com/mnemoclaw/immune/blob/master/agents/immune-scan.md"
click node_correction "https://github.com/mnemoclaw/immune/blob/master/agents/immune-scan.md"
click node_learning_write "https://github.com/mnemoclaw/immune/blob/master/immune-adapter.js"
click node_search "https://github.com/mnemoclaw/immune/blob/master/immune-adapter.js"
click node_embedding "https://github.com/mnemoclaw/immune/blob/master/immune-adapter.js"
click node_fts "https://github.com/mnemoclaw/immune/blob/master/immune-adapter.js"
click node_fusion "https://github.com/mnemoclaw/immune/blob/master/immune-adapter.js"
click node_dedup "https://github.com/mnemoclaw/immune/blob/master/immune-adapter.js"
click node_scoring "https://github.com/mnemoclaw/immune/blob/master/immune-adapter.js"
click node_session "https://github.com/mnemoclaw/immune/blob/master/immune-adapter.js"
click node_housekeeping "https://github.com/mnemoclaw/immune/blob/master/immune-adapter.js"
click node_json "https://github.com/mnemoclaw/immune/blob/master/immune-adapter.js"
click node_sqlite "https://github.com/mnemoclaw/immune/blob/master/immune-adapter.js"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_hook,node_domain,node_injection,node_user toneBlue
class node_scan,node_correction,node_learning_write,node_dedup,node_scoring,node_session toneAmber
class node_search,node_embedding,node_fts,node_fusion toneMint
class node_housekeeping,node_json,node_sqlite toneRose
class node_generation,node_model toneIndigo
```

## Components

### Prompt preparation

- [Prompt hook](https://github.com/mnemoclaw/immune/blob/master/immune-inject.js): `immune-inject.js`
- [Domain detection](https://github.com/mnemoclaw/immune/blob/master/immune-inject.js): `immune-inject.js`
- [Strategy injection](https://github.com/mnemoclaw/immune/blob/master/immune-inject.js): `immune-inject.js`

### Scan and learning

- [Immune scan](https://github.com/mnemoclaw/immune/blob/master/agents/immune-scan.md): `agents/immune-scan.md`
- [Error correction](https://github.com/mnemoclaw/immune/blob/master/agents/immune-scan.md): `agents/immune-scan.md`
- [Pattern learning](https://github.com/mnemoclaw/immune/blob/master/immune-adapter.js): `immune-adapter.js`
- [Pattern dedup](https://github.com/mnemoclaw/immune/blob/master/immune-adapter.js): `immune-adapter.js`
- [Output scoring](https://github.com/mnemoclaw/immune/blob/master/immune-adapter.js): `immune-adapter.js`
- [Session logging](https://github.com/mnemoclaw/immune/blob/master/immune-adapter.js): `immune-adapter.js`

### Memory retrieval

- [Hybrid retrieval](https://github.com/mnemoclaw/immune/blob/master/immune-adapter.js): `immune-adapter.js`
- [Local embeddings](https://github.com/mnemoclaw/immune/blob/master/immune-adapter.js): `immune-adapter.js`
- [FTS4 search](https://github.com/mnemoclaw/immune/blob/master/immune-adapter.js): `immune-adapter.js`
- [RRF ranking](https://github.com/mnemoclaw/immune/blob/master/immune-adapter.js): `immune-adapter.js`

### Memory state

- [Memory housekeeping](https://github.com/mnemoclaw/immune/blob/master/immune-adapter.js): `immune-adapter.js`
- [JSON memories](https://github.com/mnemoclaw/immune/blob/master/immune-adapter.js): `immune-adapter.js`
- [SQLite index](https://github.com/mnemoclaw/immune/blob/master/immune-adapter.js): `immune-adapter.js`

### Other components

- **Agent user**
- **Output generation**
- **Compatible model**

## Connections

- Agent user → Prompt hook: submits prompt
- Prompt hook → Domain detection: detects domains
- Domain detection → Strategy injection: selects strategies
- Strategy injection → JSON memories: reads strategies
- Strategy injection → Agent user: injects context
- Agent user → Output generation: requests output
- Output generation → Immune scan: scans output
- Immune scan → Compatible model: checks errors
- Immune scan → Error correction: reports errors
- Error correction → Pattern learning: learns patterns
- Pattern learning → Pattern dedup: checks duplicates
- Pattern dedup → JSON memories: updates memories
- Hybrid retrieval → Local embeddings: ranks semantically
- Hybrid retrieval → FTS4 search: finds keywords
- Local embeddings → RRF ranking: returns ranked matches
- FTS4 search → RRF ranking: returns ranked matches
- RRF ranking → JSON memories: loads patterns
- FTS4 search → SQLite index: queries index
- Pattern learning → SQLite index: syncs index
- Output scoring → JSON memories: updates scores
- Session logging → JSON memories: writes context log
- Session logging → SQLite index: indexes session
- Memory housekeeping → JSON memories: archives patterns