Introduction to Nyansa

Relevant source files

The following files were used as context for generating this wiki page:

• README.md
• CONTRIBUTING.md
• docker-compose.yml
• services/memory-api/README.md
• services/memory-api/src/domain.ts
• services/memory-api/src/markdown/parse.ts
• services/memory-api/src/ingest/ingest.ts

Nyansa is a self-hosted AI "second brain" that operates on private infrastructure. It integrates local Large Language Models (LLMs), a vector store, and a workflow engine with an Obsidian vault. The system ensures that notes, models, and data remain under user control by utilizing a Docker Compose stack of local services.
Sources: README.md:9-13

The project provides Retrieval-Augmented Generation (RAG) over a private vault, enabling semantic search and AI-assisted workflows. It prioritizes privacy-first local development where all components work offline by default.
Sources: README.md:25-31, CONTRIBUTING.md:46-48

System Architecture

Nyansa runs as a multi-container application within a dedicated Docker network. It uses Caddy as a reverse proxy to provide secure access via public domains or Tailscale tailnets. All internal services, such as the vector store and LLM inference engine, remain isolated from the public internet.
Sources: README.md:55-83, docker-compose.yml:18-20

Core Components

The stack consists of several specialized services working together to process and query information.

Component	Image	Role
n8n	n8nio/n8n	Workflow automation and AI agent orchestration.
Ollama	ollama/ollama	Local LLM inference for chat and embeddings.
Qdrant	qdrant/qdrant	Vector database for storing and searching note embeddings.
memory-api	Custom Node.js	TypeScript service for vault ingestion and semantic search.
PostgreSQL	postgres	Persistence layer for n8n workflow state.
Open WebUI	open-webui	Browser-based interface for interacting with Ollama.

Sources: README.md:87-104, docker-compose.yml:148-301

Data Flow Diagram

The following diagram illustrates the relationship between the Obsidian vault, the processing services, and the user interface.

RAG and memory-api Logic

The memory-api service transforms Markdown notes from the Obsidian vault into searchable vectors. It performs incremental indexing by monitoring content hashes and only re-processing changed files.
Sources: services/memory-api/README.md:5-10, services/memory-api/src/ingest/ingest.ts:79-90

Note Processing Pipeline

1. Parsing: The system extracts YAML frontmatter, ATX headings, tags, and [[wikilinks]]. It resolves the note title based on frontmatter, the first H1 heading, or the filename.
2. Chunking: Section splitting occurs at ATX headings. Paragraphs are packed into chunks up to a configurable CHUNK_MAX_CHARS (default 1500) while keeping code blocks whole where possible.
3. Embedding: Each chunk is embedded using the nomic-embed-text model via Ollama.
4. Storage: Chunks are stored in Qdrant as points. Each point contains the vector and a payload with metadata like path, title, and section.

Sources: services/memory-api/README.md:54-78, services/memory-api/src/markdown/parse.ts:13-43, services/memory-api/src/markdown/chunk.ts:25-46

Ingestion Flow

The Ingestor class manages the lifecycle of vault synchronization.

API and Search

The memory-api provides internal endpoints for managing the index and performing semantic queries. Access requires a Bearer token for authentication.
Sources: services/memory-api/README.md:12-16, services/memory-api/src/config.ts:7-8

Primary Endpoints

• POST /ingest: Triggers a vault scan. It supports incremental (default) or full modes.
• POST /search: Queries the vector store. It accepts a JSON body with the query string, a result limit, and optional tag filters.

Sources: services/memory-api/README.md:23-52

Search Response Structure

Search results return ranked "hits" that include the similarity score and source metadata.

{
  "query": "string",
  "results": [
    {
      "score": 0.95,
      "path": "folder/note.md",
      "title": "Note Title",
      "section": "Parent > Subheading",
      "text": "The actual text content of the chunk..."
    }
  ]
}

Sources: services/memory-api/src/domain.ts:63-74, services/memory-api/README.md:42-52

Security and Deployment

Nyansa implements a "verifiable security" model. It uses docker-compose.yml to ensure that sensitive services like PostgreSQL and Ollama do not publish ports to the host. Access is strictly controlled via Caddy.
Sources: README.md:107-115, docker-compose.yml:130-143

Deployment uses an immutable release folder strategy. A git push triggers a build, backup, and health check sequence. The system supports three hardware profiles: cpu, gpu-nvidia, and gpu-amd, which adjust the Ollama container configuration to match available resources.
Sources: README.md:139-152, docker-compose.yml:256-285

Conclusion

Nyansa provides a private, integrated environment for managing knowledge through AI. By combining n8n's workflow orchestration with a custom RAG pipeline in memory-api, the system allows users to interact with their Obsidian notes semantically while maintaining total data sovereignty on local infrastructure.
Sources: README.md:9-13, CONTRIBUTING.md:20-25