Mykhailo Pavlov

About the Project

Anagnosi (from Greek ἀνάγνωσις — "recognition, reading") is a privacy-first, local-first Personal Knowledge Management (PKM) system that lets you ask natural language questions about your Markdown notes and receive AI-powered answers — without sending your data to the cloud.

Built with modern Python tooling and designed for developers, researchers, and knowledge workers who value privacy, control, and extensibility.

Why Anagnosi?

Feature	Benefit
Local-First	Your notes never leave your machine unless you configure it
RAG-Powered	Answers are grounded in your content, not generic training data
Incremental Sync	Only changed files are re-indexed — fast and efficient
Dual LLM Support	Use Ollama (recommended) or built-in Transformers models
Markdown Native	Works with your existing `.md` files — no format conversion
Tested & Linted	Full test coverage, Ruff linting, pre-commit hooks

Quick Start

Prerequisites

Python 3.12+
Poetry
Ollama (for anagnosi ask)

Installation

# 1. Clone the repository
git clone https://github.com/Pavloffm/Anagnosi.git
cd Anagnosi

# 2. Install dependencies
poetry install
poetry shell

# 3. Configure environment
cp .env.example .env
# Edit .env with your preferences

# 4. Initialize your vault
anagnosi init

Basic Usage

# Index your Markdown files
anagnosi sync

# Ask a question (using Ollama)
anagnosi ask "What projects am I working on?"

# Or use the built-in local LLM
anagnosi ask-local "Explain my Docker setup"

Architecture

Core Components

src/anagnosi/
├── rag/
│   ├── llm_client.py        # Ollama & Transformers LLM interfaces
│   ├── metadata_store.py    # SQLite tracking for incremental sync
│   ├── prompt_generator.py  # Context-aware prompt construction
│   └── rag.py               # Core RAG: indexing, retrieval, embedding
├── cli.py                   # Typer-based CLI with rich output
├── config.py                # Path configuration for vault structure
├── settings.py              # Pydantic settings with env var support
└── structure_initialization.py  # Vault directory/template setup

Data Flow

Indexing Pipeline

Markdown Files (.md)
        ↓
   Text Cleaning
        ↓
Markdown Header Splitting → Recursive Chunking
        ↓
   Embedding (BGE-small)
        ↓
   ChromaDB Vector Store
        ↓
SQLite Metadata Tracking (hash, mtime, chunk count)

Query Pipeline

User Question
        ↓
   Embed Query
        ↓
Vector Similarity Search (ChromaDB)
        ↓
Retrieve Top-K Context Chunks
        ↓
Prompt Assembly (System + Context + Query)
        ↓
LLM Generation (Ollama or Transformers)
        ↓
Formatted Answer with Source Citations

Configuration

Environment Variables (`.env`)

Variable	Default	Description
`APP_ROOT_PATH`	`.`	Base directory for the application
`HF_TOKEN`	`""`	Hugging Face token for model downloads
`DEBUG_MODE`	`false`	Enable verbose logging
`EMBEDDING_MODEL_NAME`	`BAAI/bge-small-en-v1.5`	Embedding model for RAG
`RAG_EMBEDDING_BATCH_SIZE`	`32`	Batch size for embedding generation
`RAG_CHUNK_SIZE`	`256`	Maximum tokens per chunk
`RAG_CHUNK_OVERLAP`	`32`	Overlap between consecutive chunks
`OLLAMA_BASE_URL`	`http://localhost:11434`	Ollama API endpoint
`OLLAMA_DEFAULT_MODEL`	`qwen3.5:4b`	Default LLM for queries
`OLLAMA_DEFAULT_TIMEOUT`	`120`	Request timeout (seconds)
`OLLAMA_DEFAULT_TEMPERATURE`	`0.1`	LLM creativity parameter
`OLLAMA_DEFAULT_NUM_CTX`	`4096`	Context window size

Vault Structure (after `anagnosi init`)

anagnosi_vault/
├── 0000_home/
│   └── 0000_home.md          # Central dashboard note
├── 0001_inbox/               # Unprocessed notes
├── 0002_calendar/
│   ├── 0000_daily/           # Daily journals
│   ├── 0001_weekly/          # Weekly reviews
│   ├── 0002_monthly/         # Monthly planning
│   ├── 0003_quarterly/       # Quarterly goals
│   └── 0004_yearly/          # Annual reflections
├── 0003_sources/             # Reference material
├── 0004_templates/           # Note templates (e.g., people-template.md)
├── 0005_attachments/         # Binary files, images, PDFs
├── 0006_peoples/             # Contact/person notes
└── 9999_archive/             # Deprecated/old notes

Indexing Scope: Currently, only .md files in the root of anagnosi_vault/ are indexed. Subdirectory files are organized for you but excluded from RAG unless moved to root.

CLI Commands

Command	Description	Options
`anagnosi init`	Create vault directory structure	—
`anagnosi sync`	Index Markdown files to vector DB	`--force`, `-f`
`anagnosi ask`	Query using Ollama LLM	`--top-k`, `--stream/--no-stream`
`anagnosi ask-local`	Query using local Transformers model	`--model`, `--device`, `--top-k`

Examples

# Force re-index all files
anagnosi sync --force

# Ask with custom context retrieval
anagnosi ask "Summarize my Q1 goals" --top-k 10 --no-stream

# Use a smaller local model on CPU
anagnosi ask-local "What is RAG?" \
  --model "HuggingFaceTB/SmolLM2-135M-Instruct" \
  --device "cpu" \
  --top-k 3

LLM Backend Options

Option 1: Ollama (Recommended)

Connect to local or remote Ollama instances
Supports streaming responses
Easy model management via ollama pull

# Local setup
ollama pull qwen3.5:4b
anagnosi ask "Hello, Anagnosi!"

# Remote server (e.g., GPU machine)
# In .env:
OLLAMA_BASE_URL=http://192.168.1.100:11434

Option 2: Built-in Transformers

No external server required
Uses Hugging Face transformers library
Ideal for offline/air-gapped environments

anagnosi ask-local "Explain my project structure" \
  --model "Qwen/Qwen2.5-1.5B-Instruct" \
  --device "cuda"  # or "cpu"

Tip: For best results, use instruction-tuned models with ChatML formatting support.

Development

Running Tests

# Full test suite
poetry run pytest

# With coverage report
poetry run pytest --cov=anagnosi --cov-report=html

# Single test file
poetry run pytest tests/unit/test_rag.py -v

# Check for deprecation warnings
poetry run pytest -W error::DeprecationWarning

Code Quality

# Lint with Ruff
poetry run ruff check src/ tests/

# Auto-fix fixable issues
poetry run ruff check --fix src/ tests/

# Pre-commit hooks
pre-commit install
pre-commit run --all-files

Debugging

# Enable debug logging
export DEBUG_MODE=true
# or add to .env: DEBUG_MODE=true

# View logs with loguru formatting
anagnosi sync 2>&1 | grep -E "DEBUG|INFO|ERROR"

Dependencies

Core

chromadb — Vector database for semantic search
langchain-* — Text splitting, document handling
sentence-transformers / HuggingFaceEmbeddings — Embedding generation
torch + transformers — Local LLM inference (optional backend)
pydantic-settings — Type-safe configuration management
typer + rich — Beautiful, interactive CLI

Development

pytest + pytest-cov — Testing and coverage
ruff — Fast Python linter/formatter
pre-commit — Git hook automation

Privacy & Security

All indexing and inference occur locally by default
No telemetry, analytics, or external API calls (unless configured)
Vector database (.vector_db/) stored in your vault, git-ignored
SQLite metadata uses WAL mode for crash resilience
File hashing (SHA-256) ensures integrity tracking

Best Practice: When using remote Ollama, restrict access to your LAN or use a reverse proxy with authentication.

Contributing

Fork the repository
Create a feature branch: git checkout -b feat/your-feature
Make changes + add tests
Run linting and tests: pre-commit run --all-files && poetry run pytest
Submit a Pull Request

Project Standards

Type hints required for all public functions
Docstrings for classes and complex logic
Tests for new features and bug fixes
Ruff rules: E, W, F, I, UP, B (ignoring line length and multi-statement lines)

File Reference

Key Files

File	Purpose
`src/anagnosi/rag/rag.py`	Core RAG logic: discovery, splitting, embedding, retrieval
`src/anagnosi/rag/metadata_store.py`	SQLite-based change detection for incremental sync
`src/anagnosi/rag/llm_client.py`	Unified interface for Ollama & Transformers LLMs
`src/anagnosi/cli.py`	CLI entrypoint with Typer, Rich output, streaming support
`src/anagnosi/settings.py`	Pydantic settings with `.env` loading and validation
`tests/unit/`	Comprehensive unit tests for all modules

Templates

src/templates/people-template.md — Frontmatter template for contact notes

Acknowledgments

LangChain — RAG orchestration framework
ChromaDB — Lightweight, embeddable vector store
Ollama — Simple local LLM serving
Hugging Face — Models, tokenizers, and embeddings
Typer — CLI development made easy
Loguru — Pain-free logging

Anagnosi — Privacy-First Personal Knowledge Base with RAG

About the Project

Why Anagnosi?

Quick Start

Prerequisites

Installation

Basic Usage

Architecture

Core Components

Data Flow

Indexing Pipeline

Query Pipeline

Configuration

Environment Variables (.env)

Vault Structure (after anagnosi init)

CLI Commands

Examples

LLM Backend Options

Option 1: Ollama (Recommended)

Option 2: Built-in Transformers

Development

Running Tests

Code Quality

Debugging

Dependencies

Core

Development

Privacy & Security

Contributing

Project Standards

File Reference

Key Files

Templates

Acknowledgments

Environment Variables (`.env`)

Vault Structure (after `anagnosi init`)