Skip to main content

minutes

PyPI Python Tests License

Distill any conversation into structured knowledge.

Local-first CLI for extracting decisions, ideas, questions, action items, concepts, and key terms from any conversation transcript. Works with Claude Code sessions, meeting transcripts, plain text, and markdown. Runs entirely offline with a local LLM—nothing leaves your machine.

Quick Start

# Using uv (recommended)
uv tool install take-minutes

# Or with pip
pip install take-minutes

# Run it
minutes process my-session.jsonl

See output in ./output/:

  • Markdown file with structured knowledge
  • SQLite index for future searches
  • Optionally: semantic embeddings for cross-session discovery

What It Extracts

Category Description Example
Decisions What was decided and why "Use SQLite instead of PostgreSQL for MVP (reason: no schema migrations needed)"
Ideas Concepts, suggestions, opportunities "Implement quiet hours to prevent 2am notifications"
Questions Open issues needing resolution "What's the deployment target—Raspberry Pi or cloud?"
Action Items Tasks assigned with owners "Write health endpoint monitor (owner: ops-pragmatist, deadline: Phase 1)"
Concepts Key technical or business ideas "3-tiered autonomy model: tier 1 (audit), tier 2 (approval), tier 3 (confirmation)"
Terms Abbreviations, jargon, domain terms "EDA = Event-Driven Architecture"

Prerequisites

minutes uses a local LLM for extraction. You need an OpenAI-compatible inference endpoint:

  • Ollama: ollama.com — simple local LLM runner
  • LM Studio: lmstudio.ai — GUI-based local inference
  • vLLM: docs.vllm.ai — high-throughput serving engine
  • OpenAI API or any OpenAI-compatible provider (set GATEWAY_URL env var)

For best results: use a 4B–7B model (e.g., Qwen 2.5 7B, Llama 3 8B).

Installation

Core (extraction only)

# Using uv (recommended)
uv tool install take-minutes

# Or with pip
pip install take-minutes
# Using uv
uv tool install "take-minutes[search]"

# Or with pip
pip install "take-minutes[search]"

One-line setup (downloads embedding model)

minutes setup

The setup command pre-downloads the embedding model (~420MB) so you aren't surprised by a mid-run download.

Usage

Process a single file

# Extract from Claude Code session
minutes process session.jsonl

# Extract from meeting transcript
minutes process meeting.txt -o ./my-minutes

# Skip deduplication check (force reprocess)
minutes process session.jsonl --no-dedup

# Verbose output for debugging
minutes process session.jsonl -v

Output:

  • output/YYYY-MM-DD-HH-MM-SS.md — structured knowledge in markdown
  • output/minutes.db — SQLite index with full-text search
  • output/sessions.json — metadata log for easy inspection

Batch process Claude Code sessions

Scan ~/.claude/projects/ and extract from all main-thread sessions:

# Process sessions from last 2 weeks, sorted by date (newest first)
minutes batch

# Filter by project key (substring match)
minutes batch --project persistence

# Change time range (ISO date or relative: 7d, 2w, 1m)
minutes batch --since 2w --sort size

# Dry run: show what would be processed
minutes batch --dry-run --min-size 100KB

# Skip embedding generation
minutes batch --no-embed

Output:

  • ~/.claude/minutes/{project_key}/ — project-specific minutes
  • ~/.claude/minutes/{project_key}/minutes.db — indexed extractions

Search across all processed sessions

# Keyword search
minutes search "budget decision"

# Filter by category (decision, idea, question, action_item, concept, term)
minutes search "authentication" --category decision

# Vector (semantic) search
minutes search "how do we handle failures?" --mode vector

# Hybrid (keyword + vector) search
minutes search "persistence strategy" --mode hybrid --limit 5

# Search specific project
minutes search "deployment" --project persistence

Returns ranked results with scores, context, and source session.

View configuration

minutes config
minutes config --env

Shows active settings: gateway URL, model, output directory, chunking parameters.

Supported Formats

  • Claude Code JSONL (native) — ~/.claude/projects/*/session.jsonl
  • Plain text / Markdown — conversation transcripts, meeting notes
  • Coming soon: ChatGPT export, Codex CLI, Cline, Cursor

Auto-detection: process command detects format by file extension or content. Override with --format:

minutes process transcript.srt --format text

Configuration

Create a .env file in your working directory:

# LLM backend
GATEWAY_URL=http://localhost:8800/v1
GATEWAY_MODEL=qwen3-4b

# Output
OUTPUT_DIR=./minutes-output/

# Chunking (for long transcripts)
MAX_CHUNK_SIZE=12000      # tokens per chunk
CHUNK_OVERLAP=200         # token overlap between chunks

# Retry logic
MAX_RETRIES=3

# Glossary (optional YAML file for cross-referencing)
GLOSSARY_PATH=./glossary.yaml

# Prompts (optional file paths for custom extraction prompts)
SYSTEM_PROMPT=./prompts/system.txt
EXTRACTION_PROMPT=./prompts/extraction.txt

# Debug
VERBOSE=true

View active config:

minutes config

Architecture

Input (JSONL / TXT / MD)
         ↓
    Parser (extract messages/text)
         ↓
   Chunker (split into LLM-friendly chunks)
         ↓
  LLM Extraction (local model extracts structured data)
         ↓
Deduplication (fuzzy match across chunks)
         ↓
  SQLite Index (FTS5 full-text search)
         ↓
Embeddings (sentence-transformers, optional)
         ↓
Semantic Search (FAISS + embeddings)

How It Works

  1. Parse: Read input file (JSONL, plaintext, markdown) and extract dialogue or transcript text
  2. Chunk: Split text into overlapping chunks to fit LLM context window (~12K tokens by default)
  3. Extract: Send each chunk to local LLM with structured schema; collect decisions, ideas, questions, action items, concepts, terms
  4. Deduplicate: Fuzzy-match extracted items across chunks; keep unique items
  5. Index: Store in SQLite with FTS5 indexing for keyword search; optionally generate embeddings for semantic/hybrid search

Output is a single markdown file with all extractions, plus a queryable SQLite database.

Example Workflow

Scenario: Strategic planning sessions

  1. Extract from session:

    minutes process 2026-02-22-strategy.jsonl -o ./strategy-minutes
    
  2. Review markdown:

    cat ./strategy-minutes/2026-02-22-07-32-38.md
    
  3. Cross-reference with glossary (if provided):

    # Your GLOSSARY_PATH contains definitions for SRE, NIST AI RMF, EU AI Act
    # Output markdown shows which extracted concepts are in glossary vs unknown
    
  4. Batch process all recent sessions:

    minutes batch --since 1m --project strategy --sort date
    
  5. Search for related decisions across all sessions:

    minutes search "idempotency" --category decision --mode hybrid
    

Requirements

  • Python 3.10+
  • Local LLM running on GATEWAY_URL (default: http://localhost:8800/v1)
  • Optional: Sentence Transformers for semantic search (pip install "take-minutes[search]")

Tips

  • Cold start: First extraction takes longer due to model loading. Subsequent runs are faster.
  • Large transcripts: Automatically chunks long inputs; adjust MAX_CHUNK_SIZE if needed.
  • Private data: All processing is local; nothing sent to external APIs (unless you configure GATEWAY_URL to an external provider).
  • Incremental indexing: Reprocessing same file is skipped unless you use --no-dedup.
  • Searching: Use --mode hybrid for best results (combines keyword + semantic search).

License

MIT

Metadata

Release files for take-minutes 0.4.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for take-minutes 0.4.0
File Size Uploaded Provenance Actions
take_minutes-0.4.0.tar.gz 66.6 kB With provenance Details for take_minutes-0.4.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for take-minutes 0.4.0
File Interpreter ABI Platform Actions
take_minutes-0.4.0-py3-none-any.whl Python 3 none any Details for take_minutes-0.4.0-py3-none-any.whl

Total release size: 118.8 kB

Release files / take_minutes-0.4.0.tar.gz

Download URL take_minutes-0.4.0.tar.gz
Size 66.6 kB
Tags Source
SHA-256 checksum
How to use checksums
5770df85bd5a7efca53627d2b40f9541ed838af49076d5eb69d8cbc4fa19018b
BLAKE2b-256 checksum
How to use checksums
b7761d4ab1be2437cc23eda690752e126182e458d234aa961568f31cdf9190ca
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/6.1.0 CPython/3.13.7

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Feb 25, 2026.

Transparency log

Release files / take_minutes-0.4.0-py3-none-any.whl

Download URL take_minutes-0.4.0-py3-none-any.whl
Size 52.2 kB
Tags Python 3
SHA-256 checksum
How to use checksums
db2803f32e0bebcf3f8ff2161e807a85a94c1324d878b6f90849c75801b7d049
BLAKE2b-256 checksum
How to use checksums
b0108b660dbf391e619c6ed38cb9ac107ea9e76d051e79cc0a73e700637636b2
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/6.1.0 CPython/3.13.7

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Feb 25, 2026.

Transparency log

Security for take-minutes 0.4.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for take_minutes-0.4.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Feb 25, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page