# zilliztech/memsearch architecture

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

- Interactive diagram: https://gitdiagram.com/zilliztech/memsearch
- Repository: https://github.com/zilliztech/memsearch

## Overview

MemSearch provides shared semantic memory for coding agents: plugins capture conversation turns into Markdown journals, the CLI indexes those files and serves search/expansion, and agents reuse recalled context across platforms. The runtime also includes transcript-based retrieval, live synchronization, optional reranking, durable-note maintenance, and memory-to-skill distillation. Core call edges use the supplied source index; plugin workflows and unsampled capabilities are included only where the README documents them.

Main entry points: [`src/memsearch/cli.py`](https://github.com/zilliztech/memsearch/blob/main/src/memsearch/cli.py) (CLI commands), [`src/memsearch/core.py`](https://github.com/zilliztech/memsearch/blob/main/src/memsearch/core.py) (Memory orchestrator), [`src/memsearch/io.py`](https://github.com/zilliztech/memsearch/blob/main/src/memsearch/io.py) (Markdown journals), [`plugins/opencode/index.ts`](https://github.com/zilliztech/memsearch/blob/main/plugins/opencode/index.ts) (OpenCode plugin)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_adapters["Agent integrations"]
  node_claude["Claude Code plugin"]
  node_codex["Codex plugin"]
  node_dsh["DSH plugin"]
  node_openclaw["OpenClaw plugin"]
  node_opencode["OpenCode plugin<br/>[index.ts]"]
end

subgraph group_runtime["Memory runtime"]
  node_journals["Markdown journals<br/>[io.py]"]
  node_cli["CLI commands<br/>[cli.py]"]
  node_config["Configuration<br/>[config.py]"]
  node_orchestrator["Memory orchestrator<br/>[core.py]"]
end

subgraph group_retrieval["Recall and indexing"]
  node_scanner["File scanner<br/>[scanner.py]"]
  node_chunker["Markdown chunker<br/>[chunker.py]"]
  node_embeddings["Embedding providers<br/>[__init__.py]"]
  node_vectorstore[("Milvus index<br/>[store.py]")]
  node_watcher["Live file watcher<br/>[watcher.py]"]
  node_reranker["Hybrid reranking<br/>[reranker.py]"]
  node_jev["Jev reranker<br/>[jev_reranker.py]"]
  node_transcripts["Transcript recall<br/>[transcript.py]"]
end

subgraph group_maintenance["Memory evolution"]
  node_compaction["Memory compaction<br/>[compact.py]"]
  node_maintenance["Durable-note maintenance<br/>[maintenance.py]"]
  node_skills["Skill distillation<br/>[skills.py]"]
end

node_agent(("Coding agents"))

node_agent -->|"uses"| node_claude
node_agent -->|"uses"| node_codex
node_agent -->|"uses"| node_dsh
node_agent -->|"uses"| node_openclaw
node_agent -->|"uses"| node_opencode
node_claude -->|"captures turns"| node_journals
node_codex -->|"captures turns"| node_journals
node_dsh -->|"captures turns"| node_journals
node_openclaw -->|"captures turns"| node_journals
node_opencode -->|"captures turns"| node_journals
node_agent -->|"runs recall"| node_cli
node_cli -->|"loads settings"| node_config
node_cli -->|"invokes indexing"| node_orchestrator
node_cli -->|"reads and expands"| node_vectorstore
node_cli -->|"provides transcript recall"| node_transcripts
node_orchestrator -->|"scans files"| node_scanner
node_orchestrator -->|"chunks content"| node_chunker
node_orchestrator -->|"creates vectors"| node_embeddings
node_orchestrator -->|"stores and searches"| node_vectorstore
node_orchestrator -->|"starts watching"| node_watcher
node_orchestrator -->|"reranks results"| node_reranker
node_reranker -->|"dispatches Jev"| node_jev
node_opencode -->|"runs memory commands"| node_cli
node_opencode -->|"reads recent context"| node_journals
node_cli -->|"offers compaction"| node_compaction
node_cli -->|"runs maintenance"| node_maintenance
node_cli -->|"manages skills"| node_skills
node_maintenance -->|"uses compaction"| node_compaction
node_maintenance -->|"maintains notes"| node_journals
node_skills -->|"distills workflows"| node_journals

click node_claude "https://github.com/zilliztech/memsearch/tree/main/plugins/claude-code"
click node_codex "https://github.com/zilliztech/memsearch/tree/main/plugins/codex"
click node_dsh "https://github.com/zilliztech/memsearch/tree/main/plugins/dsh"
click node_openclaw "https://github.com/zilliztech/memsearch/tree/main/plugins/openclaw"
click node_opencode "https://github.com/zilliztech/memsearch/blob/main/plugins/opencode/index.ts"
click node_journals "https://github.com/zilliztech/memsearch/blob/main/src/memsearch/io.py"
click node_cli "https://github.com/zilliztech/memsearch/blob/main/src/memsearch/cli.py"
click node_config "https://github.com/zilliztech/memsearch/blob/main/src/memsearch/config.py"
click node_orchestrator "https://github.com/zilliztech/memsearch/blob/main/src/memsearch/core.py"
click node_scanner "https://github.com/zilliztech/memsearch/blob/main/src/memsearch/scanner.py"
click node_chunker "https://github.com/zilliztech/memsearch/blob/main/src/memsearch/chunker.py"
click node_embeddings "https://github.com/zilliztech/memsearch/blob/main/src/memsearch/embeddings/__init__.py"
click node_vectorstore "https://github.com/zilliztech/memsearch/blob/main/src/memsearch/store.py"
click node_watcher "https://github.com/zilliztech/memsearch/blob/main/src/memsearch/watcher.py"
click node_reranker "https://github.com/zilliztech/memsearch/blob/main/src/memsearch/reranker.py"
click node_jev "https://github.com/zilliztech/memsearch/blob/main/src/memsearch/jev_reranker.py"
click node_transcripts "https://github.com/zilliztech/memsearch/blob/main/src/memsearch/transcript.py"
click node_compaction "https://github.com/zilliztech/memsearch/blob/main/src/memsearch/compact.py"
click node_maintenance "https://github.com/zilliztech/memsearch/blob/main/src/memsearch/maintenance.py"
click node_skills "https://github.com/zilliztech/memsearch/blob/main/src/memsearch/skills.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_claude,node_codex,node_dsh,node_openclaw,node_opencode toneBlue
class node_journals,node_cli,node_config,node_orchestrator toneAmber
class node_scanner,node_chunker,node_embeddings,node_vectorstore,node_watcher,node_reranker,node_jev,node_transcripts toneMint
class node_compaction,node_maintenance,node_skills toneRose
class node_agent toneIndigo
```

## Components

### Agent integrations

- [Claude Code plugin](https://github.com/zilliztech/memsearch/tree/main/plugins/claude-code): `plugins/claude-code`
- [Codex plugin](https://github.com/zilliztech/memsearch/tree/main/plugins/codex): `plugins/codex`
- [DSH plugin](https://github.com/zilliztech/memsearch/tree/main/plugins/dsh): `plugins/dsh`
- [OpenClaw plugin](https://github.com/zilliztech/memsearch/tree/main/plugins/openclaw): `plugins/openclaw`
- [OpenCode plugin](https://github.com/zilliztech/memsearch/blob/main/plugins/opencode/index.ts): `plugins/opencode/index.ts`

### Memory runtime

- [Markdown journals](https://github.com/zilliztech/memsearch/blob/main/src/memsearch/io.py): `src/memsearch/io.py`
- [CLI commands](https://github.com/zilliztech/memsearch/blob/main/src/memsearch/cli.py): `src/memsearch/cli.py`
- [Configuration](https://github.com/zilliztech/memsearch/blob/main/src/memsearch/config.py): `src/memsearch/config.py`
- [Memory orchestrator](https://github.com/zilliztech/memsearch/blob/main/src/memsearch/core.py): `src/memsearch/core.py`

### Recall and indexing

- [File scanner](https://github.com/zilliztech/memsearch/blob/main/src/memsearch/scanner.py): `src/memsearch/scanner.py`
- [Markdown chunker](https://github.com/zilliztech/memsearch/blob/main/src/memsearch/chunker.py): `src/memsearch/chunker.py`
- [Embedding providers](https://github.com/zilliztech/memsearch/blob/main/src/memsearch/embeddings/__init__.py): `src/memsearch/embeddings/__init__.py`
- [Milvus index](https://github.com/zilliztech/memsearch/blob/main/src/memsearch/store.py): `src/memsearch/store.py`
- [Live file watcher](https://github.com/zilliztech/memsearch/blob/main/src/memsearch/watcher.py): `src/memsearch/watcher.py`
- [Hybrid reranking](https://github.com/zilliztech/memsearch/blob/main/src/memsearch/reranker.py): `src/memsearch/reranker.py`
- [Jev reranker](https://github.com/zilliztech/memsearch/blob/main/src/memsearch/jev_reranker.py): `src/memsearch/jev_reranker.py`
- [Transcript recall](https://github.com/zilliztech/memsearch/blob/main/src/memsearch/transcript.py): `src/memsearch/transcript.py`

### Memory evolution

- [Memory compaction](https://github.com/zilliztech/memsearch/blob/main/src/memsearch/compact.py): `src/memsearch/compact.py`
- [Durable-note maintenance](https://github.com/zilliztech/memsearch/blob/main/src/memsearch/maintenance.py): `src/memsearch/maintenance.py`
- [Skill distillation](https://github.com/zilliztech/memsearch/blob/main/src/memsearch/skills.py): `src/memsearch/skills.py`

### Other components

- **Coding agents**

## Connections

- Coding agents → Claude Code plugin: uses (evidence: `README.md`)
- Coding agents → Codex plugin: uses (evidence: `README.md`)
- Coding agents → DSH plugin: uses (evidence: `README.md`)
- Coding agents → OpenClaw plugin: uses (evidence: `README.md`)
- Coding agents → OpenCode plugin: uses (evidence: `README.md`)
- Claude Code plugin → Markdown journals: captures turns (evidence: `README.md`)
- Codex plugin → Markdown journals: captures turns (evidence: `README.md`)
- DSH plugin → Markdown journals: captures turns (evidence: `README.md`)
- OpenClaw plugin → Markdown journals: captures turns (evidence: `README.md`)
- OpenCode plugin → Markdown journals: captures turns (evidence: `README.md`)
- Coding agents → CLI commands: runs recall (evidence: `README.md`)
- CLI commands → Configuration: loads settings (evidence: `src/memsearch/cli.py`)
- CLI commands → Memory orchestrator: invokes indexing (evidence: `src/memsearch/cli.py`)
- CLI commands → Milvus index: reads and expands (evidence: `src/memsearch/cli.py`)
- CLI commands → Transcript recall: provides transcript recall (evidence: `README.md`)
- Memory orchestrator → File scanner: scans files (evidence: `src/memsearch/core.py`)
- Memory orchestrator → Markdown chunker: chunks content (evidence: `src/memsearch/core.py`)
- Memory orchestrator → Embedding providers: creates vectors (evidence: `src/memsearch/core.py`)
- Memory orchestrator → Milvus index: stores and searches (evidence: `src/memsearch/core.py`)
- Memory orchestrator → Live file watcher: starts watching (evidence: `src/memsearch/core.py`)
- Memory orchestrator → Hybrid reranking: reranks results (evidence: `src/memsearch/core.py`)
- Hybrid reranking → Jev reranker: dispatches Jev (evidence: `src/memsearch/reranker.py`)
- OpenCode plugin → CLI commands: runs memory commands (evidence: `plugins/opencode/index.ts`)
- OpenCode plugin → Markdown journals: reads recent context
- CLI commands → Memory compaction: offers compaction (evidence: `src/memsearch/cli.py`)
- CLI commands → Durable-note maintenance: runs maintenance (evidence: `src/memsearch/cli.py`)
- CLI commands → Skill distillation: manages skills (evidence: `src/memsearch/cli.py`)
- Durable-note maintenance → Memory compaction: uses compaction (evidence: `src/memsearch/maintenance.py`)
- Durable-note maintenance → Markdown journals: maintains notes (evidence: `README.md`)
- Skill distillation → Markdown journals: distills workflows (evidence: `README.md`)
