# rfranr/memory-cli architecture

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

- Interactive diagram: https://gitdiagram.com/rfranr/memory-cli
- Repository: https://github.com/rfranr/memory-cli

## Overview

RAG-CLI is a local command-line tool for syncing a category taxonomy, classifying and indexing text/files/URLs, and searching or filtering indexed chunks. The main workflow is taxonomy sync followed by document input, chunking, embedding and category matching, then persistence; search embeds a query and retrieves nearest chunks. The core application wires use cases to SQLite stores and an HTTP embedding service. Several use-case and adapter details are represented from README and source-index references rather than inspected excerpts.

Main entry points: [`src/core/core.ts`](https://github.com/rfranr/memory-cli/blob/main/src/core/core.ts) (App composition), [`src/application/index-document.ts`](https://github.com/rfranr/memory-cli/blob/main/src/application/index-document.ts) (Index documents), [`src/infrastructure/embedding/http-embedding-client.ts`](https://github.com/rfranr/memory-cli/blob/main/src/infrastructure/embedding/http-embedding-client.ts) (HTTP embeddings), [`src/infrastructure/database/sqlite-category-store.ts`](https://github.com/rfranr/memory-cli/blob/main/src/infrastructure/database/sqlite-category-store.ts) (Category SQLite store)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["CLI and composition"]
  node_cli["Command interface<br/>[program.ts]"]
  node_core["App composition<br/>[core.ts]"]
  node_config["Runtime config<br/>[config.ts]"]
end

subgraph group_usecases["Document workflows"]
  node_classify["Classify documents"]
  node_index["Index documents<br/>[index-document.ts]"]
  node_taxonomy["Sync taxonomy<br/>[taxonomy-sync.ts]"]
  node_search["Semantic search"]
  node_find["Filtered find<br/>[find-documents.ts]"]
  node_stats["Database stats<br/>[stats.ts]"]
  node_ports["Domain contracts<br/>[ports.ts]"]
  node_input["Input reader"]
end

subgraph group_adapters["Infrastructure adapters"]
  node_taxonomy_loader["YAML taxonomy loader"]
  node_embedding["HTTP embeddings"]
  node_category_store[("Category SQLite store")]
  node_vector_store[("Document vector store")]
end

subgraph group_shared["Shared runtime"]
  node_chunker["Text chunking<br/>[chunk-text.ts]"]
  node_progress["Progress reporting<br/>[progress.ts]"]
  node_metadata["Index metadata<br/>[index-metadata.ts]"]
end

node_user(("CLI user"))
node_embedding_service{{"Embedding endpoint"}}

node_user -->|"runs commands"| node_cli
node_cli -->|"creates app"| node_core
node_core -->|"builds config"| node_config
node_core -->|"dispatches classify"| node_classify
node_core -->|"dispatches index"| node_index
node_core -->|"dispatches sync"| node_taxonomy
node_core -->|"dispatches search"| node_search
node_core -->|"dispatches find"| node_find
node_core -->|"dispatches stats"| node_stats
node_classify -->|"reads input"| node_input
node_index -->|"reads input"| node_input
node_index -->|"chunks text"| node_chunker
node_index -.->|"embeds chunks"| node_embedding
node_index -.->|"matches categories"| node_category_store
node_index -.->|"stores chunks"| node_vector_store
node_classify -.->|"embeds input"| node_embedding
node_classify -.->|"searches categories"| node_category_store
node_taxonomy -.->|"loads YAML"| node_taxonomy_loader
node_taxonomy -.->|"embeds categories"| node_embedding
node_taxonomy -.->|"upserts categories"| node_category_store
node_search -->|"embeds query"| node_embedding
node_search -->|"searches vectors"| node_vector_store
node_find -->|"filters chunks"| node_vector_store
node_stats -.->|"reads document stats"| node_vector_store
node_stats -.->|"reads category stats"| node_category_store
node_core -->|"initializes stores"| node_vector_store
node_core -->|"initializes stores"| node_category_store
node_core -->|"constructs client"| node_embedding
node_embedding -->|"POSTs input"| node_embedding_service
node_index -->|"reports progress"| node_progress
node_core -.->|"validates store metadata"| node_metadata
node_ports -.->|"defines contract"| node_category_store
node_ports -.->|"defines contract"| node_vector_store
node_ports -.->|"defines contract"| node_embedding

click node_cli "https://github.com/rfranr/memory-cli/blob/main/src/cli/program.ts"
click node_core "https://github.com/rfranr/memory-cli/blob/main/src/core/core.ts"
click node_config "https://github.com/rfranr/memory-cli/blob/main/src/config/config.ts"
click node_classify "https://github.com/rfranr/memory-cli/blob/main/src/application/classify-document.ts"
click node_index "https://github.com/rfranr/memory-cli/blob/main/src/application/index-document.ts"
click node_taxonomy "https://github.com/rfranr/memory-cli/blob/main/src/application/taxonomy-sync.ts"
click node_search "https://github.com/rfranr/memory-cli/blob/main/src/application/search-documents.ts"
click node_find "https://github.com/rfranr/memory-cli/blob/main/src/application/find-documents.ts"
click node_stats "https://github.com/rfranr/memory-cli/blob/main/src/application/stats.ts"
click node_ports "https://github.com/rfranr/memory-cli/blob/main/src/domain/ports.ts"
click node_input "https://github.com/rfranr/memory-cli/blob/main/src/application/classify-document.ts"
click node_chunker "https://github.com/rfranr/memory-cli/blob/main/src/shared/chunk-text.ts"
click node_progress "https://github.com/rfranr/memory-cli/blob/main/src/shared/progress.ts"
click node_metadata "https://github.com/rfranr/memory-cli/blob/main/src/shared/index-metadata.ts"
click node_taxonomy_loader "https://github.com/rfranr/memory-cli/blob/main/src/infrastructure/taxonomy/yaml-taxonomy-loader.ts"
click node_embedding "https://github.com/rfranr/memory-cli/blob/main/src/infrastructure/embedding/http-embedding-client.ts"
click node_category_store "https://github.com/rfranr/memory-cli/blob/main/src/infrastructure/database/sqlite-category-store.ts"
click node_vector_store "https://github.com/rfranr/memory-cli/blob/main/src/infrastructure/database/sqlite-vector-store.ts"

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_core,node_config,node_user toneBlue
class node_classify,node_index,node_taxonomy,node_search,node_find,node_stats,node_ports,node_input toneAmber
class node_taxonomy_loader,node_embedding,node_category_store,node_vector_store toneMint
class node_chunker,node_progress,node_metadata toneRose
class node_embedding_service toneIndigo
```

## Components

### CLI and composition

- [Command interface](https://github.com/rfranr/memory-cli/blob/main/src/cli/program.ts): `src/cli/program.ts`
- [App composition](https://github.com/rfranr/memory-cli/blob/main/src/core/core.ts): `src/core/core.ts`
- [Runtime config](https://github.com/rfranr/memory-cli/blob/main/src/config/config.ts): `src/config/config.ts`

### Document workflows

- [Classify documents](https://github.com/rfranr/memory-cli/blob/main/src/application/classify-document.ts): `src/application/classify-document.ts`
- [Index documents](https://github.com/rfranr/memory-cli/blob/main/src/application/index-document.ts): `src/application/index-document.ts`
- [Sync taxonomy](https://github.com/rfranr/memory-cli/blob/main/src/application/taxonomy-sync.ts): `src/application/taxonomy-sync.ts`
- [Semantic search](https://github.com/rfranr/memory-cli/blob/main/src/application/search-documents.ts): `src/application/search-documents.ts`
- [Filtered find](https://github.com/rfranr/memory-cli/blob/main/src/application/find-documents.ts): `src/application/find-documents.ts`
- [Database stats](https://github.com/rfranr/memory-cli/blob/main/src/application/stats.ts): `src/application/stats.ts`
- [Domain contracts](https://github.com/rfranr/memory-cli/blob/main/src/domain/ports.ts): `src/domain/ports.ts`
- [Input reader](https://github.com/rfranr/memory-cli/blob/main/src/application/classify-document.ts): `src/application/classify-document.ts`

### Infrastructure adapters

- [YAML taxonomy loader](https://github.com/rfranr/memory-cli/blob/main/src/infrastructure/taxonomy/yaml-taxonomy-loader.ts): `src/infrastructure/taxonomy/yaml-taxonomy-loader.ts`
- [HTTP embeddings](https://github.com/rfranr/memory-cli/blob/main/src/infrastructure/embedding/http-embedding-client.ts): `src/infrastructure/embedding/http-embedding-client.ts`
- [Category SQLite store](https://github.com/rfranr/memory-cli/blob/main/src/infrastructure/database/sqlite-category-store.ts): `src/infrastructure/database/sqlite-category-store.ts`
- [Document vector store](https://github.com/rfranr/memory-cli/blob/main/src/infrastructure/database/sqlite-vector-store.ts): `src/infrastructure/database/sqlite-vector-store.ts`

### Shared runtime

- [Text chunking](https://github.com/rfranr/memory-cli/blob/main/src/shared/chunk-text.ts): `src/shared/chunk-text.ts`
- [Progress reporting](https://github.com/rfranr/memory-cli/blob/main/src/shared/progress.ts): `src/shared/progress.ts`
- [Index metadata](https://github.com/rfranr/memory-cli/blob/main/src/shared/index-metadata.ts): `src/shared/index-metadata.ts`

### Other components

- **CLI user**
- **Embedding endpoint**

## Connections

- CLI user → Command interface: runs commands (evidence: `README.md`)
- Command interface → App composition: creates app (evidence: `src/cli/program.ts`)
- App composition → Runtime config: builds config (evidence: `src/core/core.ts`)
- App composition → Classify documents: dispatches classify (evidence: `src/core/core.ts`)
- App composition → Index documents: dispatches index (evidence: `src/core/core.ts`)
- App composition → Sync taxonomy: dispatches sync (evidence: `src/core/core.ts`)
- App composition → Semantic search: dispatches search (evidence: `src/core/core.ts`)
- App composition → Filtered find: dispatches find (evidence: `src/core/core.ts`)
- App composition → Database stats: dispatches stats (evidence: `src/core/core.ts`)
- Classify documents → Input reader: reads input (evidence: `src/application/classify-document.ts`)
- Index documents → Input reader: reads input (evidence: `src/application/index-document.ts`)
- Index documents → Text chunking: chunks text (evidence: `src/application/index-document.ts`)
- Index documents → HTTP embeddings: embeds chunks
- Index documents → Category SQLite store: matches categories
- Index documents → Document vector store: stores chunks
- Classify documents → HTTP embeddings: embeds input
- Classify documents → Category SQLite store: searches categories
- Sync taxonomy → YAML taxonomy loader: loads YAML (evidence: `src/application/taxonomy-sync.ts`)
- Sync taxonomy → HTTP embeddings: embeds categories
- Sync taxonomy → Category SQLite store: upserts categories
- Semantic search → HTTP embeddings: embeds query (evidence: `README.md`)
- Semantic search → Document vector store: searches vectors (evidence: `README.md`)
- Filtered find → Document vector store: filters chunks (evidence: `README.md`)
- Database stats → Document vector store: reads document stats
- Database stats → Category SQLite store: reads category stats
- App composition → Document vector store: initializes stores (evidence: `src/core/core.ts`)
- App composition → Category SQLite store: initializes stores (evidence: `src/core/core.ts`)
- App composition → HTTP embeddings: constructs client (evidence: `src/core/core.ts`)
- HTTP embeddings → Embedding endpoint: POSTs input (evidence: `src/infrastructure/embedding/http-embedding-client.ts`)
- Index documents → Progress reporting: reports progress (evidence: `src/application/index-document.ts`)
- App composition → Index metadata: validates store metadata
- Domain contracts → Category SQLite store: defines contract (evidence: `src/infrastructure/database/sqlite-category-store.ts`)
- Domain contracts → Document vector store: defines contract (evidence: `src/infrastructure/database/sqlite-vector-store.ts`)
- Domain contracts → HTTP embeddings: defines contract (evidence: `src/infrastructure/embedding/http-embedding-client.ts`)