# asekepc/mind-skill architecture

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

- Interactive diagram: https://gitdiagram.com/asekepc/mind-skill
- Repository: https://github.com/asekepc/mind-skill

## Overview

Mind Skill is a local-first project-memory tool for coding agents. A user initializes a project, then an agent records checkpoints and source-backed architecture facts; lifecycle hooks can capture progress and deliver a compact handoff, while CLI and MCP provide explicit read/write access. The map separates onboarding and agent integration from memory workflows, persistence, and optional mirrors. Major documented features such as manifest scanning, import/export, search, and Claude Mem support are represented. Some command and hook relationships rely on the source index or README because those implementations were only partly sampled.

Main entry points: [`skills/mind-skill/lib/store.cjs`](https://github.com/asekepc/mind-skill/blob/main/skills/mind-skill/lib/store.cjs) (Memory service), [`skills/mind-skill/scripts/mind.cjs`](https://github.com/asekepc/mind-skill/blob/main/skills/mind-skill/scripts/mind.cjs) (Mind CLI), [`skills/mind-skill/lib/packet.cjs`](https://github.com/asekepc/mind-skill/blob/main/skills/mind-skill/lib/packet.cjs) (Handoff packet), [`skills/mind-skill/lib/hooks.cjs`](https://github.com/asekepc/mind-skill/blob/main/skills/mind-skill/lib/hooks.cjs) (Lifecycle hooks)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_integration["Agent Integration"]
  node_cli["Mind CLI<br/>[mind.cjs]"]
  node_entry["CLI entry<br/>[mind.cjs]"]
  node_installer["Agent installer<br/>[install.cjs]"]
  node_hook["Lifecycle hooks<br/>[hooks.cjs]"]
  node_dispatcher["Hook dispatcher<br/>[dispatch.cjs]"]
  node_mcp["MCP server<br/>[mcp.cjs]"]
  node_skill["Agent instructions<br/>[SKILL.md]"]
end

subgraph group_workflow["Memory Workflows"]
  node_store["Memory service<br/>[store.cjs]"]
  node_scanner["Manifest scanner<br/>[scan.cjs]"]
  node_handoff["Handoff packet<br/>[packet.cjs]"]
  node_io["Safe file utilities<br/>[io.cjs]"]
end

subgraph group_persistence["Local Persistence"]
  node_project["Project facts"]
  node_task["Task state"]
  node_eventlog["Change journal"]
end

subgraph group_mirrors["Optional Mirrors"]
  node_sqlite[("SQLite mirror<br/>[sqlite.cjs]")]
  node_claude["Claude Mem mirror<br/>[claude-mem.cjs]"]
end

node_user(("Project user"))
node_agent(("Coding agent"))
node_claude_service["Claude Mem worker"]
node_project_files["Project manifests"]
node_mcp_client(("MCP client"))

node_user -->|"runs commands"| node_cli
node_entry -->|"delegates to"| node_cli
node_cli -->|"invokes"| node_store
node_cli -->|"configures agents"| node_installer
node_cli -->|"builds context"| node_handoff
node_cli -.->|"serves protocol"| node_mcp
node_user -->|"asks to preserve"| node_agent
node_agent -->|"follows"| node_skill
node_installer -->|"installs hooks"| node_dispatcher
node_dispatcher -->|"dispatches events"| node_hook
node_hook -->|"records progress"| node_store
node_hook -->|"creates packet"| node_handoff
node_hook -->|"delivers context"| node_agent
node_mcp_client -->|"sends tools"| node_mcp
node_mcp -->|"reads and writes"| node_store
node_mcp -->|"formats context"| node_handoff
node_store -->|"refreshes facts"| node_scanner
node_scanner -->|"scans manifests"| node_project_files
node_store -->|"persists safely"| node_io
node_scanner -->|"checks source files"| node_io
node_store -->|"updates facts"| node_project
node_store -->|"updates checkpoints"| node_task
node_store -.->|"journals changes"| node_eventlog
node_handoff -->|"selects facts"| node_project
node_handoff -->|"selects progress"| node_task
node_store -->|"syncs mirror"| node_sqlite
node_store -->|"queues saves"| node_claude
node_claude -->|"posts notes"| node_claude_service
node_cli -.->|"exports data"| node_sqlite
node_cli -.->|"imports data"| node_store

click node_cli "https://github.com/asekepc/mind-skill/blob/main/skills/mind-skill/scripts/mind.cjs"
click node_entry "https://github.com/asekepc/mind-skill/blob/main/bin/mind.cjs"
click node_installer "https://github.com/asekepc/mind-skill/blob/main/skills/mind-skill/lib/install.cjs"
click node_hook "https://github.com/asekepc/mind-skill/blob/main/skills/mind-skill/lib/hooks.cjs"
click node_dispatcher "https://github.com/asekepc/mind-skill/blob/main/skills/mind-skill/lib/dispatch.cjs"
click node_mcp "https://github.com/asekepc/mind-skill/blob/main/skills/mind-skill/lib/mcp.cjs"
click node_skill "https://github.com/asekepc/mind-skill/blob/main/skills/mind-skill/SKILL.md"
click node_store "https://github.com/asekepc/mind-skill/blob/main/skills/mind-skill/lib/store.cjs"
click node_scanner "https://github.com/asekepc/mind-skill/blob/main/skills/mind-skill/lib/scan.cjs"
click node_handoff "https://github.com/asekepc/mind-skill/blob/main/skills/mind-skill/lib/packet.cjs"
click node_io "https://github.com/asekepc/mind-skill/blob/main/skills/mind-skill/lib/io.cjs"
click node_sqlite "https://github.com/asekepc/mind-skill/blob/main/skills/mind-skill/lib/sqlite.cjs"
click node_claude "https://github.com/asekepc/mind-skill/blob/main/skills/mind-skill/lib/claude-mem.cjs"

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_cli,node_entry,node_installer,node_hook,node_dispatcher,node_mcp,node_skill,node_user,node_mcp_client toneBlue
class node_store,node_scanner,node_handoff,node_io toneAmber
class node_project,node_task,node_eventlog toneMint
class node_sqlite,node_claude,node_claude_service toneRose
class node_agent,node_project_files toneIndigo
```

## Components

### Agent Integration

- [Mind CLI](https://github.com/asekepc/mind-skill/blob/main/skills/mind-skill/scripts/mind.cjs): `skills/mind-skill/scripts/mind.cjs`
- [CLI entry](https://github.com/asekepc/mind-skill/blob/main/bin/mind.cjs): `bin/mind.cjs`
- [Agent installer](https://github.com/asekepc/mind-skill/blob/main/skills/mind-skill/lib/install.cjs): `skills/mind-skill/lib/install.cjs`
- [Lifecycle hooks](https://github.com/asekepc/mind-skill/blob/main/skills/mind-skill/lib/hooks.cjs): `skills/mind-skill/lib/hooks.cjs`
- [Hook dispatcher](https://github.com/asekepc/mind-skill/blob/main/skills/mind-skill/lib/dispatch.cjs): `skills/mind-skill/lib/dispatch.cjs`
- [MCP server](https://github.com/asekepc/mind-skill/blob/main/skills/mind-skill/lib/mcp.cjs): `skills/mind-skill/lib/mcp.cjs`
- [Agent instructions](https://github.com/asekepc/mind-skill/blob/main/skills/mind-skill/SKILL.md): `skills/mind-skill/SKILL.md`

### Memory Workflows

- [Memory service](https://github.com/asekepc/mind-skill/blob/main/skills/mind-skill/lib/store.cjs): `skills/mind-skill/lib/store.cjs`
- [Manifest scanner](https://github.com/asekepc/mind-skill/blob/main/skills/mind-skill/lib/scan.cjs): `skills/mind-skill/lib/scan.cjs`
- [Handoff packet](https://github.com/asekepc/mind-skill/blob/main/skills/mind-skill/lib/packet.cjs): `skills/mind-skill/lib/packet.cjs`
- [Safe file utilities](https://github.com/asekepc/mind-skill/blob/main/skills/mind-skill/lib/io.cjs): `skills/mind-skill/lib/io.cjs`

### Local Persistence

- **Project facts**
- **Task state**
- **Change journal**

### Optional Mirrors

- [SQLite mirror](https://github.com/asekepc/mind-skill/blob/main/skills/mind-skill/lib/sqlite.cjs): `skills/mind-skill/lib/sqlite.cjs`
- [Claude Mem mirror](https://github.com/asekepc/mind-skill/blob/main/skills/mind-skill/lib/claude-mem.cjs): `skills/mind-skill/lib/claude-mem.cjs`

### Other components

- **Project user**
- **Coding agent**
- **Claude Mem worker**
- **Project manifests**
- **MCP client**

## Connections

- Project user → Mind CLI: runs commands (evidence: `skills/mind-skill/scripts/mind.cjs`)
- CLI entry → Mind CLI: delegates to (evidence: `bin/mind.cjs`)
- Mind CLI → Memory service: invokes (evidence: `skills/mind-skill/scripts/mind.cjs`)
- Mind CLI → Agent installer: configures agents (evidence: `skills/mind-skill/scripts/mind.cjs`)
- Mind CLI → Handoff packet: builds context (evidence: `skills/mind-skill/scripts/mind.cjs`)
- Mind CLI → MCP server: serves protocol (evidence: `skills/mind-skill/scripts/mind.cjs`)
- Project user → Coding agent: asks to preserve (evidence: `README.md`)
- Coding agent → Agent instructions: follows (evidence: `README.md`)
- Agent installer → Hook dispatcher: installs hooks (evidence: `skills/mind-skill/lib/install.cjs`)
- Hook dispatcher → Lifecycle hooks: dispatches events (evidence: `skills/mind-skill/lib/dispatch.cjs`)
- Lifecycle hooks → Memory service: records progress (evidence: `skills/mind-skill/lib/hooks.cjs`)
- Lifecycle hooks → Handoff packet: creates packet (evidence: `skills/mind-skill/lib/hooks.cjs`)
- Lifecycle hooks → Coding agent: delivers context (evidence: `README.md`)
- MCP client → MCP server: sends tools (evidence: `README.md`)
- MCP server → Memory service: reads and writes (evidence: `skills/mind-skill/lib/mcp.cjs`)
- MCP server → Handoff packet: formats context (evidence: `skills/mind-skill/lib/mcp.cjs`)
- Memory service → Manifest scanner: refreshes facts (evidence: `skills/mind-skill/lib/store.cjs`)
- Manifest scanner → Project manifests: scans manifests (evidence: `skills/mind-skill/lib/scan.cjs`)
- Memory service → Safe file utilities: persists safely (evidence: `skills/mind-skill/lib/store.cjs`)
- Manifest scanner → Safe file utilities: checks source files (evidence: `skills/mind-skill/lib/scan.cjs`)
- Memory service → Project facts: updates facts (evidence: `skills/mind-skill/lib/store.cjs`)
- Memory service → Task state: updates checkpoints (evidence: `skills/mind-skill/lib/store.cjs`)
- Memory service → Change journal: journals changes
- Handoff packet → Project facts: selects facts (evidence: `skills/mind-skill/lib/packet.cjs`)
- Handoff packet → Task state: selects progress (evidence: `skills/mind-skill/lib/packet.cjs`)
- Memory service → SQLite mirror: syncs mirror (evidence: `skills/mind-skill/lib/store.cjs`)
- Memory service → Claude Mem mirror: queues saves (evidence: `skills/mind-skill/lib/store.cjs`)
- Claude Mem mirror → Claude Mem worker: posts notes (evidence: `skills/mind-skill/lib/claude-mem.cjs`)
- Mind CLI → SQLite mirror: exports data (evidence: `skills/mind-skill/scripts/mind.cjs`)
- Mind CLI → Memory service: imports data (evidence: `skills/mind-skill/scripts/mind.cjs`)
