maris 0.2.2

Local Multi-Agent Repository Intelligence System

MARIS

MARIS is a local-first, multi-agent repository intelligence system for understanding source code. It indexes repositories with language-aware parsers, stores repository knowledge locally, and uses local Ollama models for search, Q&A, documentation, impact analysis, and implementation prompt generation.

The goal is to help developers reason about codebases without sending source code to external services. MARIS focuses on repository understanding rather than code generation, while the Prompt Generator Agent helps convert that understanding into implementation-ready prompts for another coding agent.

Current Status

MARIS is an alpha-stage Python package.

Implemented:

• CLI entry point: maris
• Local storage with DuckDB metadata and LanceDB vectors
• Ollama-based embeddings and local model validation
• Parser implementations for Python, Java, Scala, Bash, JavaScript, TypeScript, Config files (YAML/JSON/TOML/INI), and Markdown
• Repository indexing, semantic search, symbol explanations, Q&A, documentation generation, and repository stats
• Git-based incremental indexing
• Impact analysis commands for impact, edge cases, test coverage, and breaking changes
• Prompt Generator Agent for turning a task or problem statement into a context-aware implementation prompt

Planned or incomplete:

• Kotlin, Go, and Rust parsers have tree-sitter grammars installed but parser implementations are not yet complete
• Git archaeology and architecture evolution agents are roadmap items
• Some secondary docs may lag the CLI; the root README should be treated as the current quick-start reference
• AGENT.md is contributor guidance and product direction, not an executable agent spec

Requirements

• Python 3.11+
• Ollama running locally
• Required Ollama models:
  • nomic-embed-text for embeddings
  • qwen2.5:7b by default for Q&A and documentation

Install or start Ollama separately, then pull the default models:

ollama pull nomic-embed-text
ollama pull qwen2.5:7b

Installation

For local development:

python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
pip install -r requirements-dev.txt
pip install -e .

Alternatively, use the setup script:

./setup.sh
source venv/bin/activate

Verify the CLI:

maris --help

Quick Start

Run MARIS from the repository you want to analyze. By default, MARIS stores project-specific data in .maris/ in the current working directory unless MARIS_DATA_DIR is set.

⚠️ Important: Index First

You must index your repository before using search, ask, explain, document, or prompt-generation workflows. MARIS does not auto-index; indexing is an explicit step that builds the knowledge base.

# Step 1: Index your repository (required first step)
maris index src/ --recursive

# Step 2: Verify indexing completed
maris stats

# Step 3: Now you can use other commands
# Search indexed symbols
maris search "RepositoryKnowledge"

# Ask questions about your codebase
maris ask "How does indexing work?"

# Explain specific symbols
maris explain IndexingAgent

# Generate documentation
maris document src/maris/agents/indexing_agent.py --output docs/indexing_agent.md

# Generate an implementation-ready prompt for another AI coding agent
maris prompt "Add a CLI command that prints repository indexing health as Markdown"

Incremental Indexing

After the initial index, use incremental indexing to update only changed files:

# Re-index only files that changed since last index
maris index --incremental

This is much faster than re-indexing the entire repository.

Impact analysis examples:

maris impact analyze --symbol "GitAgent.detect_changes"
maris impact edge-cases --file "src/maris/agents/git_agent.py"
maris impact tests --symbol "QAAgent.answer_question"
maris impact breaking-changes --symbol "RepositoryKnowledgeImpl"

Interactive Q&A:

maris interactive

Prompt generation examples:

maris prompt "Add a CLI command that prints repository indexing health as Markdown"
maris prompt "Add retry support to indexing" --context "Retry transient Ollama failures only"
maris prompt "Improve parser error handling" --output implementation-prompt.md

The generated prompt includes the original task, relevant code context, likely files, implementation requirements, edge cases to consider, test guidance, and an execution plan. It is designed to be handed to another AI coding agent.

CLI Reference

Global options:

maris --config-file .env --skip-validation COMMAND

Commands:

• maris index [PATH]: index a file or directory
• maris index --incremental: index files changed since the last indexed commit
• maris search QUERY: semantic symbol search
• maris explain SYMBOL_NAME: explain a symbol with relevant indexed context
• maris ask QUESTION: ask a natural-language repository question
• maris prompt TASK: generate an implementation-ready prompt for another AI coding agent
• maris impact analyze: analyze callers, callees, affected files, and recommendations
• maris impact edge-cases: detect likely edge case risks
• maris impact tests: inspect test coverage signals
• maris impact breaking-changes: detect potential breaking change risks
• maris document FILE_PATH: generate Markdown documentation for a file
• maris stats: show indexed symbol counts
• maris clear: clear indexed metadata and vectors
• maris interactive: start an interactive Q&A session

Use command help for exact options:

maris COMMAND --help
maris impact COMMAND --help

Configuration

Configuration is loaded in this order:

1. Environment variables with the MARIS_ prefix
2. .env in the current directory
3. ~/.maris/.env
4. Defaults

Common settings:

MARIS_DATA_DIR=.maris
MARIS_OLLAMA_HOST=http://localhost:11434
MARIS_EMBEDDING_MODEL=nomic-embed-text
MARIS_EMBEDDING_BATCH_SIZE=32
MARIS_QA_MODEL=qwen2.5:7b
MARIS_QA_TEMPERATURE=0.7
MARIS_QA_MAX_TOKENS=2048
MARIS_DOC_MODEL=qwen2.5:7b
MARIS_DOC_TEMPERATURE=0.3
MARIS_DOC_MAX_TOKENS=4096
MARIS_MAX_SEARCH_RESULTS=20
MARIS_MAX_CONTEXT_SYMBOLS=10
MARIS_ENABLE_CACHING=true
MARIS_PARALLEL_INDEXING=false
MARIS_LOG_LEVEL=INFO

For first-time setup, maris index ... --auto-pull can pull missing Ollama models automatically. Use --skip-validation only when you intentionally want to bypass Ollama and model checks.

Architecture

MARIS is organized around a shared repository knowledge layer:

Source repository
    -> Indexing Agent
    -> Repository Knowledge Layer
       -> DuckDB metadata store
       -> LanceDB vector store
       -> Ollama embeddings
    -> Specialized agents
       -> Q&A Agent
       -> Documentation Agent
       -> Git Agent
       -> Impact Analysis Agent
       -> Prompt Generator Agent

Core source layout:

src/maris/
  agents/       specialized agents and orchestrator
  cli/          Click-based CLI
  config/       configuration loading
  core/         domain models
  embeddings/   Ollama embedding service
  indexing/     Tree-sitter parsers and parser factory
  knowledge/    repository knowledge service
  storage/      DuckDB and LanceDB adapters
  utils/        shared validation helpers

Development

Run tests:

pytest

Run targeted tests:

pytest tests/test_python_parser.py
pytest tests/test_orchestrator_agent.py

Formatting and linting tools are configured in pyproject.toml:

black src tests
ruff check src tests

Contributor Guidance

AGENT.md contains contributor guidance and product direction. The key expectations are:

• Read .codex/project-profile.md before changing architecture or design direction
• Read relevant files in .codex/specs/ before changing behavior
• Preserve the local-first, retrieval-first, symbol-aware design
• Prefer deterministic workflows and specialized agents over broad autonomous loops
• Update specs when behavior, acceptance criteria, API contracts, or domain rules change

Additional Docs

• Installation Guide
• Configuration
• Architecture
• Project Walkthrough
• Git Agent
• Impact Analysis Agent
• Prompt Generator Agent
• Multi-Language Support