# finesssee/memory-search architecture

> Architecture diagram of the GitHub repository finesssee/memory-search, 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/finesssee/memory-search
- Repository: https://github.com/finesssee/memory-search

## Overview

memory-search is a personal knowledge-base indexing and semantic-search CLI, with an HTTP API and agent integrations. The main workflow indexes configured files into SQLite, then accepts a query, expands it optionally, combines keyword and vector retrieval, reranks candidates, and formats results. Separate capabilities cover facts, session capture, context generation, collections, and IDE integrations. The graph follows documented behavior and indexed imports; unsampled commands and optional provider wiring are represented only where README evidence supports them.

Main entry points: [`src/core/indexer.ts`](https://github.com/finesssee/memory-search/blob/main/src/core/indexer.ts) (File indexer), [`src/core/searcher.ts`](https://github.com/finesssee/memory-search/blob/main/src/core/searcher.ts) (Hybrid search), [`src/core/embeddings.ts`](https://github.com/finesssee/memory-search/blob/main/src/core/embeddings.ts) (Embedding service), [`src/storage/db.ts`](https://github.com/finesssee/memory-search/blob/main/src/storage/db.ts) (SQLite index)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["User entry points"]
  node_cli["CLI startup<br/>[cli.ts]"]
  node_commands["Command router<br/>[index.ts]"]
  node_searchcmd["Search command<br/>[search.ts]"]
  node_indexcmd["Index command<br/>[index-cmd.ts]"]
end

subgraph group_indexing["Indexing pipeline"]
  node_indexer["File indexer<br/>[indexer.ts]"]
  node_chunker["Markdown chunker<br/>[chunker.ts]"]
  node_contextualizer["Chunk contextualizer<br/>[contextualizer.ts]"]
  node_annotations["Chunk annotations"]
  node_concepts["Concept extraction"]
end

subgraph group_retrieval["Search and AI"]
  node_searcher["Hybrid search<br/>[searcher.ts]"]
  node_expander["Query expansion<br/>[expander.ts]"]
  node_embeddings["Embedding service<br/>[embeddings.ts]"]
  node_reranker["Cross-encoder reranker<br/>[reranker.ts]"]
  node_local["Local LLM runtime<br/>[local-llm.ts]"]
end

subgraph group_state["Knowledge state"]
  node_database[("SQLite index<br/>[db.ts]")]
  node_facts[("Facts store<br/>[facts.ts]")]
end

subgraph group_integrations["Agent and service integrations"]
  node_hooks["Session capture<br/>[session-end.ts]"]
  node_hookshared["Capture utilities<br/>[index.ts]"]
  node_contextcmd["Context builder<br/>[context.ts]"]
  node_claudemd["CLAUDE.md sync<br/>[claude-md.ts]"]
  node_server["HTTP API<br/>[routes.ts]"]
  node_cursor["Cursor integration<br/>[cursor.ts]"]
end

node_user(("User"))
node_embedservice{{"Embedding endpoint"}}

node_user -->|"runs commands"| node_cli
node_cli -->|"dispatches"| node_commands
node_commands -->|"routes search"| node_searchcmd
node_commands -->|"routes indexing"| node_indexcmd
node_searchcmd -->|"calls search"| node_searcher
node_indexcmd -->|"starts indexing"| node_indexer
node_indexer -->|"chunks files"| node_chunker
node_indexer -->|"contextualizes chunks"| node_contextualizer
node_indexer -->|"embeds chunks"| node_embeddings
node_indexer -->|"stores index"| node_database
node_indexer -->|"detects types"| node_annotations
node_indexer -->|"extracts concepts"| node_concepts
node_searcher -->|"expands query"| node_expander
node_searcher -->|"embeds query"| node_embeddings
node_searcher -->|"retrieves candidates"| node_database
node_searcher -->|"reranks candidates"| node_reranker
node_embeddings -->|"caches vectors"| node_database
node_embeddings -->|"requests vectors"| node_embedservice
node_reranker -.->|"supports local mode"| node_local
node_embeddings -.->|"supports local mode"| node_local
node_hooks -->|"uses capture utilities"| node_hookshared
node_hooks -->|"stores session data"| node_database
node_hooks -->|"stores extracted facts"| node_facts
node_contextcmd -->|"builds from search"| node_searcher
node_contextcmd -->|"reads facts"| node_facts
node_contextcmd -->|"syncs context"| node_claudemd
node_server -->|"serves search"| node_searcher
node_server -->|"serves indexing"| node_indexer
node_server -->|"reads status and chunks"| node_database
node_user -->|"installs integration"| node_cursor

click node_cli "https://github.com/finesssee/memory-search/blob/main/src/cli.ts"
click node_commands "https://github.com/finesssee/memory-search/blob/main/src/commands/index.ts"
click node_searchcmd "https://github.com/finesssee/memory-search/blob/main/src/commands/search.ts"
click node_indexcmd "https://github.com/finesssee/memory-search/blob/main/src/commands/index-cmd.ts"
click node_indexer "https://github.com/finesssee/memory-search/blob/main/src/core/indexer.ts"
click node_chunker "https://github.com/finesssee/memory-search/blob/main/src/core/chunker.ts"
click node_contextualizer "https://github.com/finesssee/memory-search/blob/main/src/core/contextualizer.ts"
click node_annotations "https://github.com/finesssee/memory-search/blob/main/src/core/observation-detector.ts"
click node_concepts "https://github.com/finesssee/memory-search/blob/main/src/core/concept-extractor.ts"
click node_searcher "https://github.com/finesssee/memory-search/blob/main/src/core/searcher.ts"
click node_expander "https://github.com/finesssee/memory-search/blob/main/src/core/expander.ts"
click node_embeddings "https://github.com/finesssee/memory-search/blob/main/src/core/embeddings.ts"
click node_reranker "https://github.com/finesssee/memory-search/blob/main/src/core/reranker.ts"
click node_local "https://github.com/finesssee/memory-search/blob/main/src/core/local-llm.ts"
click node_database "https://github.com/finesssee/memory-search/blob/main/src/storage/db.ts"
click node_facts "https://github.com/finesssee/memory-search/blob/main/src/storage/facts.ts"
click node_hooks "https://github.com/finesssee/memory-search/blob/main/src/hooks/session-end.ts"
click node_hookshared "https://github.com/finesssee/memory-search/blob/main/src/hooks/index.ts"
click node_contextcmd "https://github.com/finesssee/memory-search/blob/main/src/commands/context.ts"
click node_claudemd "https://github.com/finesssee/memory-search/blob/main/src/integrations/claude-md.ts"
click node_server "https://github.com/finesssee/memory-search/blob/main/src/server/routes.ts"
click node_cursor "https://github.com/finesssee/memory-search/blob/main/src/integrations/cursor.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_commands,node_searchcmd,node_indexcmd,node_user toneBlue
class node_indexer,node_chunker,node_contextualizer,node_annotations,node_concepts toneAmber
class node_searcher,node_expander,node_embeddings,node_reranker,node_local toneMint
class node_database,node_facts toneRose
class node_hooks,node_hookshared,node_contextcmd,node_claudemd,node_server,node_cursor,node_embedservice toneIndigo
```

## Components

### User entry points

- [CLI startup](https://github.com/finesssee/memory-search/blob/main/src/cli.ts): `src/cli.ts`
- [Command router](https://github.com/finesssee/memory-search/blob/main/src/commands/index.ts): `src/commands/index.ts`
- [Search command](https://github.com/finesssee/memory-search/blob/main/src/commands/search.ts): `src/commands/search.ts`
- [Index command](https://github.com/finesssee/memory-search/blob/main/src/commands/index-cmd.ts): `src/commands/index-cmd.ts`

### Indexing pipeline

- [File indexer](https://github.com/finesssee/memory-search/blob/main/src/core/indexer.ts): `src/core/indexer.ts`
- [Markdown chunker](https://github.com/finesssee/memory-search/blob/main/src/core/chunker.ts): `src/core/chunker.ts`
- [Chunk contextualizer](https://github.com/finesssee/memory-search/blob/main/src/core/contextualizer.ts): `src/core/contextualizer.ts`
- [Chunk annotations](https://github.com/finesssee/memory-search/blob/main/src/core/observation-detector.ts): `src/core/observation-detector.ts`
- [Concept extraction](https://github.com/finesssee/memory-search/blob/main/src/core/concept-extractor.ts): `src/core/concept-extractor.ts`

### Search and AI

- [Hybrid search](https://github.com/finesssee/memory-search/blob/main/src/core/searcher.ts): `src/core/searcher.ts`
- [Query expansion](https://github.com/finesssee/memory-search/blob/main/src/core/expander.ts): `src/core/expander.ts`
- [Embedding service](https://github.com/finesssee/memory-search/blob/main/src/core/embeddings.ts): `src/core/embeddings.ts`
- [Cross-encoder reranker](https://github.com/finesssee/memory-search/blob/main/src/core/reranker.ts): `src/core/reranker.ts`
- [Local LLM runtime](https://github.com/finesssee/memory-search/blob/main/src/core/local-llm.ts): `src/core/local-llm.ts`

### Knowledge state

- [SQLite index](https://github.com/finesssee/memory-search/blob/main/src/storage/db.ts): `src/storage/db.ts`
- [Facts store](https://github.com/finesssee/memory-search/blob/main/src/storage/facts.ts): `src/storage/facts.ts`

### Agent and service integrations

- [Session capture](https://github.com/finesssee/memory-search/blob/main/src/hooks/session-end.ts): `src/hooks/session-end.ts`
- [Capture utilities](https://github.com/finesssee/memory-search/blob/main/src/hooks/index.ts): `src/hooks/index.ts`
- [Context builder](https://github.com/finesssee/memory-search/blob/main/src/commands/context.ts): `src/commands/context.ts`
- [CLAUDE.md sync](https://github.com/finesssee/memory-search/blob/main/src/integrations/claude-md.ts): `src/integrations/claude-md.ts`
- [HTTP API](https://github.com/finesssee/memory-search/blob/main/src/server/routes.ts): `src/server/routes.ts`
- [Cursor integration](https://github.com/finesssee/memory-search/blob/main/src/integrations/cursor.ts): `src/integrations/cursor.ts`

### Other components

- **User**
- **Embedding endpoint**

## Connections

- User → CLI startup: runs commands (evidence: `README.md`)
- CLI startup → Command router: dispatches (evidence: `src/cli.ts`)
- Command router → Search command: routes search (evidence: `src/commands/index.ts`)
- Command router → Index command: routes indexing (evidence: `src/commands/index.ts`)
- Search command → Hybrid search: calls search (evidence: `src/commands/search.ts`)
- Index command → File indexer: starts indexing (evidence: `README.md`)
- File indexer → Markdown chunker: chunks files (evidence: `src/core/indexer.ts`)
- File indexer → Chunk contextualizer: contextualizes chunks (evidence: `src/core/indexer.ts`)
- File indexer → Embedding service: embeds chunks (evidence: `src/core/indexer.ts`)
- File indexer → SQLite index: stores index (evidence: `src/core/indexer.ts`)
- File indexer → Chunk annotations: detects types (evidence: `src/core/indexer.ts`)
- File indexer → Concept extraction: extracts concepts (evidence: `src/core/indexer.ts`)
- Hybrid search → Query expansion: expands query (evidence: `src/core/searcher.ts`)
- Hybrid search → Embedding service: embeds query (evidence: `src/core/searcher.ts`)
- Hybrid search → SQLite index: retrieves candidates (evidence: `src/core/searcher.ts`)
- Hybrid search → Cross-encoder reranker: reranks candidates (evidence: `src/core/searcher.ts`)
- Embedding service → SQLite index: caches vectors (evidence: `src/core/embeddings.ts`)
- Embedding service → Embedding endpoint: requests vectors (evidence: `src/core/embeddings.ts`)
- Cross-encoder reranker → Local LLM runtime: supports local mode (evidence: `README.md`)
- Embedding service → Local LLM runtime: supports local mode (evidence: `README.md`)
- Session capture → Capture utilities: uses capture utilities (evidence: `src/hooks/session-end.ts`)
- Session capture → SQLite index: stores session data (evidence: `src/hooks/session-end.ts`)
- Session capture → Facts store: stores extracted facts (evidence: `src/hooks/session-end.ts`)
- Context builder → Hybrid search: builds from search (evidence: `src/commands/context.ts`)
- Context builder → Facts store: reads facts (evidence: `src/commands/context.ts`)
- Context builder → CLAUDE.md sync: syncs context (evidence: `src/commands/context.ts`)
- HTTP API → Hybrid search: serves search (evidence: `src/server/routes.ts`)
- HTTP API → File indexer: serves indexing (evidence: `src/server/routes.ts`)
- HTTP API → SQLite index: reads status and chunks (evidence: `src/server/routes.ts`)
- User → Cursor integration: installs integration (evidence: `README.md`)
