# neagi/reefiki architecture

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

- Interactive diagram: https://gitdiagram.com/neagi/reefiki
- Repository: https://github.com/neagi/reefiki

## Overview

REEFIKI is a local, multi-project wiki memory for AI agents. Its principal workflow distills session material: capture into an inbox, filter for reusable knowledge, save it as typed Markdown wiki pages, then link and index those pages so a later agent can retrieve context. Supporting capabilities include onboarding and project setup, review and promotion governance, health checks, and a read-only local operations dashboard. Some subsystem links are based on README descriptions because their implementation was not sampled; those are marked unverified where appropriate.

Main entry points: [`scripts/reefiki_core/review_queues.py`](https://github.com/neagi/reefiki/blob/main/scripts/reefiki_core/review_queues.py) (Review queues), [`scripts/reefiki_core/index_search.py`](https://github.com/neagi/reefiki/blob/main/scripts/reefiki_core/index_search.py) (Search index), [`scripts/reefiki_core/ops_dashboard/snapshot.py`](https://github.com/neagi/reefiki/blob/main/scripts/reefiki_core/ops_dashboard/snapshot.py) (Workspace snapshot), [`scripts/reefiki_core/selection_gate.py`](https://github.com/neagi/reefiki/blob/main/scripts/reefiki_core/selection_gate.py) (Knowledge filter)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_memory["Memory workflow"]
  node_inbox["Project inbox"]
  node_filter["Knowledge filter<br/>[selection_gate.py]"]
  node_save["Memory save<br/>[save.py]"]
  node_wiki["Markdown wiki"]
  node_markdown["Markdown parsing<br/>[markdown.py]"]
  node_wiki_write["Wiki writing<br/>[wiki_write.py]"]
end

subgraph group_retrieval["Recall and indexing"]
  node_index[("Search index<br/>[index_search.py]")]
  node_memory_pack["Context packing<br/>[memory_pack.py]"]
  node_lookup["Memory lookup<br/>[memory_lookup.py]"]
end

subgraph group_governance["Governance and safety"]
  node_review["Review queues<br/>[review_queues.py]"]
  node_promotion["Memory promotion<br/>[promotion.py]"]
  node_safety["Policy safety<br/>[__init__.py]"]
  node_health["Health checks<br/>[health.py]"]
end

subgraph group_workspace["Workspace operations"]
  node_onboarding["Project onboarding<br/>[onboarding.py]"]
  node_workspace_init["Workspace setup<br/>[init_workspace.py]"]
  node_cli["REEFIKI CLI<br/>[reefiki.py]"]
end

subgraph group_dashboard["Operations dashboard"]
  node_dashboard_server["Dashboard server<br/>[server.py]"]
  node_snapshot["Workspace snapshot<br/>[snapshot.py]"]
end

node_agent(("AI agent"))
node_dashboard_user(("Local operator"))

node_agent -->|"captures material"| node_inbox
node_inbox -->|"screens for reuse"| node_filter
node_filter -->|"selects knowledge"| node_save
node_save -.->|"writes pages"| node_wiki_write
node_wiki_write -->|"creates pages"| node_wiki
node_wiki -.->|"indexes pages"| node_index
node_index -.->|"searches memory"| node_lookup
node_lookup -.->|"packs context"| node_memory_pack
node_memory_pack -.->|"returns context"| node_agent
node_agent -.->|"reviews candidates"| node_review
node_review -.->|"queues knowledge"| node_promotion
node_safety -.->|"checks inputs"| node_filter
node_health -->|"checks queues"| node_review
node_onboarding -.->|"guides setup"| node_workspace_init
node_agent -->|"runs commands"| node_cli
node_cli -.->|"dispatches setup"| node_workspace_init
node_dashboard_user -->|"requests status"| node_dashboard_server
node_dashboard_server -->|"serves snapshot"| node_snapshot
node_snapshot -->|"reads health"| node_health
node_snapshot -->|"reads queues"| node_review
node_index -->|"parses pages"| node_markdown
node_markdown -->|"parses page format"| node_wiki

click node_filter "https://github.com/neagi/reefiki/blob/main/scripts/reefiki_core/selection_gate.py"
click node_save "https://github.com/neagi/reefiki/blob/main/scripts/reefiki_core/save.py"
click node_markdown "https://github.com/neagi/reefiki/blob/main/scripts/reefiki_core/markdown.py"
click node_wiki_write "https://github.com/neagi/reefiki/blob/main/scripts/reefiki_core/wiki_write.py"
click node_index "https://github.com/neagi/reefiki/blob/main/scripts/reefiki_core/index_search.py"
click node_memory_pack "https://github.com/neagi/reefiki/blob/main/scripts/reefiki_core/memory_pack.py"
click node_lookup "https://github.com/neagi/reefiki/blob/main/scripts/reefiki_core/memory_lookup.py"
click node_review "https://github.com/neagi/reefiki/blob/main/scripts/reefiki_core/review_queues.py"
click node_promotion "https://github.com/neagi/reefiki/blob/main/scripts/reefiki_core/promotion.py"
click node_safety "https://github.com/neagi/reefiki/blob/main/scripts/reefiki_memory/__init__.py"
click node_health "https://github.com/neagi/reefiki/blob/main/scripts/reefiki_core/health.py"
click node_onboarding "https://github.com/neagi/reefiki/blob/main/scripts/reefiki_core/onboarding.py"
click node_workspace_init "https://github.com/neagi/reefiki/blob/main/scripts/reefiki_core/init_workspace.py"
click node_cli "https://github.com/neagi/reefiki/blob/main/scripts/reefiki.py"
click node_dashboard_server "https://github.com/neagi/reefiki/blob/main/scripts/reefiki_core/ops_dashboard/server.py"
click node_snapshot "https://github.com/neagi/reefiki/blob/main/scripts/reefiki_core/ops_dashboard/snapshot.py"

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_inbox,node_filter,node_save,node_wiki,node_markdown,node_wiki_write toneBlue
class node_index,node_memory_pack,node_lookup toneAmber
class node_review,node_promotion,node_safety,node_health toneMint
class node_onboarding,node_workspace_init,node_cli toneRose
class node_dashboard_server,node_snapshot,node_agent,node_dashboard_user toneIndigo
```

## Components

### Memory workflow

- **Project inbox**
- [Knowledge filter](https://github.com/neagi/reefiki/blob/main/scripts/reefiki_core/selection_gate.py): `scripts/reefiki_core/selection_gate.py`
- [Memory save](https://github.com/neagi/reefiki/blob/main/scripts/reefiki_core/save.py): `scripts/reefiki_core/save.py`
- **Markdown wiki**
- [Markdown parsing](https://github.com/neagi/reefiki/blob/main/scripts/reefiki_core/markdown.py): `scripts/reefiki_core/markdown.py`
- [Wiki writing](https://github.com/neagi/reefiki/blob/main/scripts/reefiki_core/wiki_write.py): `scripts/reefiki_core/wiki_write.py`

### Recall and indexing

- [Search index](https://github.com/neagi/reefiki/blob/main/scripts/reefiki_core/index_search.py): `scripts/reefiki_core/index_search.py`
- [Context packing](https://github.com/neagi/reefiki/blob/main/scripts/reefiki_core/memory_pack.py): `scripts/reefiki_core/memory_pack.py`
- [Memory lookup](https://github.com/neagi/reefiki/blob/main/scripts/reefiki_core/memory_lookup.py): `scripts/reefiki_core/memory_lookup.py`

### Governance and safety

- [Review queues](https://github.com/neagi/reefiki/blob/main/scripts/reefiki_core/review_queues.py): `scripts/reefiki_core/review_queues.py`
- [Memory promotion](https://github.com/neagi/reefiki/blob/main/scripts/reefiki_core/promotion.py): `scripts/reefiki_core/promotion.py`
- [Policy safety](https://github.com/neagi/reefiki/blob/main/scripts/reefiki_memory/__init__.py): `scripts/reefiki_memory/__init__.py`
- [Health checks](https://github.com/neagi/reefiki/blob/main/scripts/reefiki_core/health.py): `scripts/reefiki_core/health.py`

### Workspace operations

- [Project onboarding](https://github.com/neagi/reefiki/blob/main/scripts/reefiki_core/onboarding.py): `scripts/reefiki_core/onboarding.py`
- [Workspace setup](https://github.com/neagi/reefiki/blob/main/scripts/reefiki_core/init_workspace.py): `scripts/reefiki_core/init_workspace.py`
- [REEFIKI CLI](https://github.com/neagi/reefiki/blob/main/scripts/reefiki.py): `scripts/reefiki.py`

### Operations dashboard

- [Dashboard server](https://github.com/neagi/reefiki/blob/main/scripts/reefiki_core/ops_dashboard/server.py): `scripts/reefiki_core/ops_dashboard/server.py`
- [Workspace snapshot](https://github.com/neagi/reefiki/blob/main/scripts/reefiki_core/ops_dashboard/snapshot.py): `scripts/reefiki_core/ops_dashboard/snapshot.py`

### Other components

- **AI agent**
- **Local operator**

## Connections

- AI agent → Project inbox: captures material (evidence: `README.md`)
- Project inbox → Knowledge filter: screens for reuse (evidence: `README.md`)
- Knowledge filter → Memory save: selects knowledge (evidence: `README.md`)
- Memory save → Wiki writing: writes pages
- Wiki writing → Markdown wiki: creates pages (evidence: `README.md`)
- Markdown wiki → Search index: indexes pages
- Search index → Memory lookup: searches memory
- Memory lookup → Context packing: packs context
- Context packing → AI agent: returns context
- AI agent → Review queues: reviews candidates
- Review queues → Memory promotion: queues knowledge
- Policy safety → Knowledge filter: checks inputs
- Health checks → Review queues: checks queues (evidence: `scripts/reefiki_core/health.py`)
- Project onboarding → Workspace setup: guides setup
- AI agent → REEFIKI CLI: runs commands (evidence: `scripts/reefiki.py`)
- REEFIKI CLI → Workspace setup: dispatches setup (evidence: `scripts/reefiki.py`)
- Local operator → Dashboard server: requests status (evidence: `scripts/reefiki_core/ops_dashboard/server.py`)
- Dashboard server → Workspace snapshot: serves snapshot (evidence: `scripts/reefiki_core/ops_dashboard/server.py`)
- Workspace snapshot → Health checks: reads health (evidence: `scripts/reefiki_core/ops_dashboard/snapshot.py`)
- Workspace snapshot → Review queues: reads queues (evidence: `scripts/reefiki_core/ops_dashboard/snapshot.py`)
- Search index → Markdown parsing: parses pages (evidence: `scripts/reefiki_core/index_search.py`)
- Markdown parsing → Markdown wiki: parses page format (evidence: `scripts/reefiki_core/markdown.py`)
