Local-first document reasoning engine for navigating and understanding PDFs, audio, video, and markdown using hierarchical tree structures and AI-powered decision making.

Features

• Document Processing: Parse PDFs, audio, video, markdown, and web pages into navigable trees
• Hierarchical Navigation: Navigate documents like a file system with sections, pages, and timestamps
• AI Reasoning: Uses configurable providers (Gemini CLI/API or Claude Code) for intelligent multi-hop navigation and question answering
• Knowledge Graph: LLM-based entity and relationship extraction with incremental updates
• Local & Private: All processing happens locally with optional cloud transcription
• osgrep Integration: Optionally use osgrep for semantic code search

Quick Start

1. Install

   npm install -g @drydev-code/osreason

2. Index Documents

   cd my-documents
   osreason index .

3. Configure a reasoning provider

   osreason setup

4. Ask Questions

   osreason ask "What were the key decisions in the Q3 meeting?"

Commands

osreason index <path>

Index documents into the reasoning tree.

osreason index document.pdf         # Single PDF
osreason index recordings/          # Directory of audio/video
osreason index . --markdown-only    # Only markdown files
osreason index . --recursive        # Include subdirectories

Options: | Flag | Description | Default | |------|-------------|---------| | --pdf-only | Only process PDF files | false | | --audio-only | Only process audio files | false | | --video-only | Only process video files | false | | --markdown-only | Only process markdown files | false | | -r, --recursive | Process subdirectories | true | | -g, --build-graph | Build knowledge graph with LLM extraction | false | | --extract-provider | Provider for extraction (gemini-cli, gemini-api, claude-code) | auto | | -v, --verbose | Show detailed progress | false |

osreason ask "<query>"

Ask questions and get AI-powered answers with citations.

osreason ask "Summarize the main points"
osreason ask "What does section 3.2 say about authentication?" --trace
osreason ask "Find all mentions of budget" --json

Options: | Flag | Description | Default | |------|-------------|---------| | --trace | Show reasoning steps | false | | --json | Output JSON format | false | | --max-iterations | Max reasoning steps | 20 | | --model | Provider-specific model to use | gemini-2.5-flash |

osreason tree

Display the document tree structure (useful for debugging).

osreason tree                       # Show all documents
osreason tree --depth 2             # Limit depth
osreason tree --source meeting.pdf  # Specific file
osreason tree --json                # JSON output

osreason transcribe <file>

Transcribe audio or video files.

osreason transcribe meeting.mp3
osreason transcribe video.mp4 --model large
osreason transcribe podcast.wav --output srt

Options: | Flag | Description | Default | |------|-------------|---------| | --model | Whisper model (tiny/base/small/medium/large) | base | | --output | Output format (md, txt, srt, json, vtt) | md | | --language | Audio language | auto-detect |

osreason serve

Run the HTTP API server for integrations.

osreason serve                      # Start on port 3847
osreason serve --port 8080          # Custom port
osreason serve --ensure             # Start if not running

API Endpoints:

• POST /index - Index a document
• POST /ask - Start reasoning session (SSE streaming)
• GET /tree - Get tree structure
• GET /node/:id - Get node details
• GET /search?q=query - Full-text search
• GET /health - Health check

osreason graph

View and manage the knowledge graph.

osreason graph stats              # Show graph statistics
osreason graph entities           # List all entities
osreason graph entity "John Doe"  # Get entity details
osreason graph edges              # List all relationships
osreason graph search "project"   # Search entities

osreason graph-update <path>

Update the knowledge graph for specific files or directories.

osreason graph-update document.md       # Update single file
osreason graph-update notes/            # Update directory
osreason graph-update . --embed         # Include embeddings

Knowledge Graph

osreason can build a knowledge graph from your documents using LLM-based entity and relationship extraction.

Building the Graph

# Build graph during indexing
osreason index . --build-graph

# Or update graph for specific files
osreason graph-update document.md

How It Works

1. LLM Extraction: Uses AI to identify entities (people, organizations, concepts) and relationships
2. Incremental Updates: Only re-extracts when content changes (based on content hash)
3. Type Discovery: Automatically discovers entity and relationship types from your documents
4. Confidence Filtering: Filters low-confidence extractions (default threshold: 0.5)

Entity Types

The LLM automatically identifies entity types including:

• person - People mentioned in documents
• organization - Companies, teams, groups
• technology - Tools, frameworks, languages
• project - Projects, initiatives
• concept - Ideas, methodologies
• location - Places, regions
• event - Meetings, milestones

Using the Graph in Queries

When asking questions, the knowledge graph provides additional context:

osreason ask "Who works on Project Alpha?"
osreason ask "What technologies does the team use?"

Supported Formats

| Type | Extensions | Processing | |------|-----------|------------| | PDF | .pdf | pdf-parse, page structure detection | | Audio | .wav, .mp3, .m4a, .ogg, .flac | Whisper transcription | | Video | .mp4, .webm, .mkv, .mov | FFmpeg audio extraction + Whisper | | Markdown | .md, .mdx | unified/remark, heading hierarchy | | Text | .txt, .rst | Paragraph chunking | | Web | URLs | fetch + readability |

Claude Code Integration

Install osreason hooks for automatic watcher management:

osreason install-claude-code

This enables:

• Automatic watcher start when Claude Code sessions begin
• Watcher shutdown when sessions end
• Document reasoning skill available in Claude Code

MCP Server Mode

Run osreason as an MCP server over stdio:

osreason mcp

Run osreason as an MCP server over streamable HTTP:

osreason mcp --http --port 3848

Example MCP client config:

{
  "mcpServers": {
    "osreason": {
      "command": "osreason",
      "args": ["mcp"]
    }
  }
}

Core MCP tools:

• osreason_index
• osreason_ask
• osreason_tree
• osreason_search
• osreason_get_node

osreason_ask uses a reliable search-based answer path by default. Set use_reasoning: true if you want algorithm-driven reasoning.

For more details, see docs/mcp.md.

How It Works

osreason builds a hierarchical tree from your documents:

Meeting Recording (video)
├── 0:00-5:32 "Introduction"
│   ├── 0:00-1:20 "Welcome and agenda"
│   └── 1:20-5:32 "Team updates"
├── 5:32-15:00 "Main Discussion"
│   ├── 5:32-8:45 "Q3 Results"
│   └── 8:45-15:00 "Budget Planning"
└── 15:00-18:30 "Action Items"

When you ask a question, osreason uses a ReAct (Reasoning + Acting) loop:

1. Reason: AI analyzes the current position and available sections
2. Act: Navigate to relevant section or search for keywords
3. Observe: Read content and update understanding
4. Repeat: Until confident answer is found

Answers include citations: [Meeting Recording, 8:45]

Comparison: osgrep vs osreason

| Aspect | osgrep | osreason | |--------|--------|----------| | Domain | Source code | Documents | | Search | Semantic vectors | Hierarchical navigation | | Output | Code snippets | Answers with citations | | Use case | "Find auth middleware" | "Summarize the meeting" |

These tools are complementary: osreason can call osgrep for code-related questions.

Requirements

• Node.js >= 20.0.0
• One configured reasoning provider: gemini-cli, Claude Code, or Gemini API
• FFmpeg (for video processing)
• Whisper or an API-backed transcription plugin for local audio/video transcription

Development

git clone https://github.com/mattes337/osreason.git
cd osreason
npm install
npm run build
npm run typecheck
npm test

License

Licensed under the Apache License, Version 2.0.