Skip to content

Running from Source

Clone and Install

git clone https://github.com/mcoliver/knowmarks.git
cd knowmarks

uv sync --all-extras

With pip

python -m venv .venv
source .venv/bin/activate
pip install -e '.[all,embeddings,dev]'

Development Workflow

Run the CLI

km save https://example.com --note "Test item"
km find "example"
km status

Run the Dashboard

km serve

The dashboard serves static files from src/knowmarks/web/static/. Changes to HTML, CSS, and JS are picked up on page refresh — no build step needed.

Run the MCP Server

km mcp

Or test it directly:

km-mcp

Run Tests

pytest
pytest -v                         # Verbose output
pytest tests/test_config.py       # Specific file
pytest -k "test_search"           # By test name

Lint

ruff check src/
ruff format --check src/

Project Structure

knowmarks/
├── src/knowmarks/
│   ├── cli.py              # Click CLI (km command)
│   ├── config.py           # Configuration and paths
│   ├── core/               # Business logic
│   │   ├── db.py           # SQLite schema, CRUD, FTS5
│   │   ├── embed.py        # Embedding providers
│   │   ├── extract.py      # Content extraction
│   │   ├── ingest.py       # Pipeline orchestration
│   │   ├── search.py       # Hybrid search + RRF
│   │   ├── cluster.py      # Semantic clustering
│   │   ├── freshness.py    # Vitality scoring
│   │   ├── classify.py     # Content type classification
│   │   ├── projects.py     # Project grouping
│   │   ├── curated.py      # Curated collections
│   │   ├── llm.py          # LLM client
│   │   ├── probes.py       # Staleness probes
│   │   └── connectors/     # Import connectors
│   ├── web/
│   │   ├── app.py          # FastAPI routes
│   │   ├── api_v1.py       # REST API v1
│   │   └── static/         # Dashboard HTML/CSS/JS
│   └── mcp/
│       └── server.py       # MCP tools
├── tests/                  # Test suite
├── extension/              # Chrome extension
├── docs/                   # Documentation (MkDocs)
├── pyproject.toml          # Package configuration
├── Dockerfile              # Full Docker image
├── Dockerfile.slim         # Slim Docker image
└── docker-compose.yml      # Docker Compose