convez.ai
MCP ServerBusca & PesquisaAvançado
Fortemi

Fortémi – Base de Conhecimento Inteligente Self-Hosted

Fortemi/fortemi

Base de conhecimento com IA que compreende significado e relações entre ideias

Ver no GitHub
BomPluginScore · de 0 a 100

Sistema de base de conhecimento self-hosted que combina busca semântica híbrida (pgvector + FTS + RRF), processamento multimodal (visão, transcrição de áudio, diarização de speaker) e geração automática de grafos de conhecimento. Funciona como MCP server com suporte a múltiplos provedores de LLM (Ollama, OpenAI, OpenRouter, llama.cpp), tudo construído em Rust + PostgreSQL.

Instalação

$npx convez-ai Fortemi/fortemi

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
30
Forks
5
Acompanhando
0
Saúde
50%
Último commit
há 3 dias
Versão
v2026.11.1
Issues abertas
4
Contribuidores
2

Casos de uso

  • Armazenar e pesquisar documentos, notas e mídias com compreensão semântica
  • Conectar automaticamente ideias e descobrir relações entre conhecimentos
  • Processar imagens, áudio, vídeos e extrair inteligência pesquisável
  • Deploy privado e self-hosted em hardware modesto (8GB VRAM)
  • Integrar agentes e UIs customizadas via 43 ferramentas MCP

Veredito

Fortémi é uma solução robusta e privada para quem precisa de busca semântica real, não apenas string matching. Sua arquitetura híbrida (pgvector + FTS + RRF) com processamento multimodal nativo o diferencia — excelente para equipes e agentes, mas exige conforto com DevOps (Rust, PostgreSQL, Docker).

README

A tradução para o português deste README ainda está na fila.

Fortémi

Pronounced: for-TAY-mee

Memory that understands.

An intelligent knowledge base that comprehends what you store — the meaning behind your notes, the relationships between ideas, and the context that connects them. Semantic search, automatic knowledge graphs, multimodal media processing, and 43 MCP agent tools. Built in Rust. Runs on a single GPU.

docker compose -f docker-compose.bundle.yml up -d

License Rust PostgreSQL MCP Docker

Get Started · Features · Architecture · MCP Server · API · Realtime Setup · Documentation · 🖥️ Desktop App (HotM)


🖥️ Looking for a desktop app, not just an API?

You're probably here because you want to use this — install HotM instead.

If you want…UseInstall
A native desktop app with editor, knowledge graph, capture, search, attachments — no Docker, no Postgres setup, no backend opsHotM (.deb / .msi / .dmg / .AppImage) — UI + Fortemi API bundled in one packageDownload HotM → run setup-linux.sh or setup-macos.sh → install the bundle
A headless server for agents over MCP, custom UIs, multi-user deployments, or air-gapped backendsFortemi (this repo) — Docker bundledocker compose -f docker-compose.bundle.yml up -d (see Quick Start below)

HotM ships the same matric-api from this repo as a bundled sidecar, so the two stay in lockstep on features. Single user with a laptop? HotM is the right answer. Team, fleet of agents, or backend service? Stay here.


What Fortémi Is

Fortémi is a self-hosted knowledge base that goes beyond storage. Most systems hold your data and wait for exact queries. Fortémi actively understands content: it finds conceptually relevant results even when you can't remember the right terminology, automatically discovers how new knowledge connects to everything else, and extracts searchable intelligence from images, audio, video, 3D models, emails, and spreadsheets.

If you've ever wished your notes could talk back — surfacing forgotten connections, answering questions from accumulated knowledge, and growing smarter with every piece of information — Fortémi is that system.

Built for privacy-first, edge-first deployment. No cloud dependency. Runs on commodity hardware with 8GB GPU VRAM. ~160k lines of Rust + 18k lines of MCP server (Node.js).


What Problems Does Fortémi Solve?

1. Search That Misses the Point

Traditional search requires you to guess the right keywords. If you stored a note about "retrieval-augmented generation" but search for "using AI to answer questions from documents," you get nothing.

Without Fortémi: Keyword-only search. You find things only when you remember exactly how you phrased them.

With Fortémi: Hybrid retrieval fuses BM25 full-text search with dense vector similarity and Reciprocal Rank Fusion (Cormack et al., 2009). Semantic search finds conceptually related content regardless of terminology. Multilingual support covers English, German, French, Spanish, Portuguese, Russian, CJK, emoji, and more — each with language-appropriate tokenization.

2. Knowledge Without Connections

Notes accumulate in folders. Ideas that should be connected sit in isolation. You know the answer is "somewhere in your notes" but can't find the thread.

Without Fortémi: Manual linking, tagging by memory, or grep-and-hope. Connections exist only in your head.

With Fortémi: Automatic semantic linking at >70% embedding similarity. A knowledge graph with recursive exploration, SNN similarity scoring, PFNET sparsification, and Louvain community detection — all with SKOS-derived labels. W3C SKOS vocabularies provide hierarchical concept organization. The graph grows organically as you add content.

3. Media Trapped in Files

A video recording contains knowledge — decisions, explanations, demonstrations — locked inside an opaque binary. An audio meeting has action items buried in hours of conversation. An email thread has attachments with critical context.

Without Fortémi: Media files are dark matter. Unsearchable. Undiscoverable. You re-watch entire recordings to find one moment.

With Fortémi: 13 extraction adapters process images (vision), audio (Whisper transcription + pyannote speaker diarization), video (keyframe extraction + scene detection + transcript alignment), 3D models (multi-view rendering + vision description), emails (RFC 2822/MIME parsing), spreadsheets (xlsx/xls/ods), and archives (ZIP/tar/gz). Every piece of media becomes searchable knowledge with derived attachments (thumbnails, transcripts, caption files, sprite sheets).

4. One-Size-Fits-All Storage

Notes, meeting minutes, code documentation, research papers, and movie reviews all get the same treatment. A meeting note should emphasize decisions and action items; a research paper should highlight methodology and findings.

Without Fortémi: Everything processed identically. No content awareness.

With Fortémi: 131 document types with auto-detection from filename patterns and content analysis. Each type has tailored chunking strategies (syntactic for code, semantic for prose), content-specific revision prompts (meetings get Decisions/Action Items sections, research gets Methodology/Findings), and type-aware extraction pipelines.


Features

  • Hybrid search — BM25 + dense vectors + RRF fusion with MMR diversity reranking
  • Multilingual FTS — CJK bigrams, emoji trigrams, 6+ language stemmers, script auto-detection
  • Search operators — AND, OR, NOT, phrase search via websearch_to_tsquery
  • Knowledge graph — Automatic linking, recursive CTE exploration, SNN scoring, PFNET sparsification, Louvain community detection
  • W3C SKOS vocabularies — Hierarchical concept organization with semantic tagging
  • 131 document types — Auto-detection with content-type-aware chunking and revision
  • 13 extraction adapters — Image vision, audio transcription, speaker diarization, video scene analysis, 3D model rendering, email parsing, spreadsheet extraction, archive listing
  • Synchronous chat — Direct LLM conversation with GPU concurrency gating and multi-turn history
  • Multi-memory archives — Schema-isolated parallel memories with federated cross-archive search
  • Embedding sets — Matryoshka Representation Learning for 12x storage savings, auto-embed rules, two-stage retrieval
  • Multi-provider inference — Ollama, OpenAI, OpenRouter, llama.cpp with hot-swap runtime configuration
  • OAuth2 + API keys — Opt-in authentication with client credentials and authorization code grants
  • Public-key encryption — X25519/AES-256-GCM for secure note sharing
  • Real-time events — SSE + WebSocket + webhook notifications
  • Spatial-temporal search — PostGIS location + time range queries
  • TUS resumable uploads — tus v1.0.0 protocol for reliable large-file uploads
  • HTTP Range requests — Partial content download for large attachments
  • Thumbnail sprite sheets — CSS sprite grids with WebVTT maps for video seek-bar previews
  • 43 MCP agent tools — Model Context Protocol integration for AI agent workflows
  • Edge hardware — Runs on 8GB GPUs; scales with hardware profiles (edge, gpu-12gb, gpu-24gb)
  • Knowledge health dashboard — Orphan tags, stale notes, unlinked notes, cold spots, access frequency

How It Works

 ┌──────────────────────────────────────────────────────────────────────────┐
 │                              Fortémi                                     │
 │                                                                          │
 │  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐  │
 │  │  Ingest  │─▶│ Extract  │─▶│  Embed   │─▶│  Link    │─▶│  Store   │  │
 │  │          │  │          │  │          │  │          │  │          │  │
 │  │ Notes    │  │ Vision   │  │ Dense    │  │ Auto-    │  │ pgvector │  │
 │  │ Media    │  │ Audio    │  │ vectors  │  │ link     │  │ PostGIS  │  │
 │  │ Email    │  │ Video    │  │ BM25     │  │ Graph    │  │ FTS      │  │
 │  │ Archives │  │ 3D       │  │ index    │  │ build    │  │          │  │
 │  └──────────┘  └──────────┘  └──────────┘  └──────────┘  └──────────┘  │
 │                                                                          │
 │  ┌──────────────────────────────────────────────────────────────────┐    │
 │  │                         Search & Retrieve                        │    │
 │  │  BM25 full-text ─┐                                               │    │
 │  │  Dense vectors ──┼──▶ RRF Fusion ──▶ MMR Diversity ──▶ Results   │    │
 │  │  Graph traverse ─┘                                               │    │
 │  └──────────────────────────────────────────────────────────────────┘    │
 │                                                                          │
 │  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐  │
 │  │ REST API │  │ MCP Srvr │  │  Chat    │  │  Events  │  │  OAuth2  │  │
 │  │  :3000   │  │  :3001   │  │  (LLM)   │  │ SSE/WS   │  │ + Keys   │  │
 │  └──────────┘  └──────────┘  └──────────┘  └──────────┘  └──────────┘  │
 └──────────────────────────────────────────────────────────────────────────┘
  1. Ingest — Notes, files, and media enter via REST API or MCP tools
  2. Extract — 13 adapters pull text, metadata, scenes, transcripts, and descriptions from every content type
  3. Embed — Content is vectorized for semantic search and indexed for full-text search
  4. Link — Embedding similarity >70% creates automatic graph connections; SNN + PFNET refine topology
  5. Store — PostgreSQL with pgvector (vectors), PostGIS (spatial), FTS (text), and per-memory schema isolation
  6. Search — BM25 + dense + graph results fused via RRF and diversified via MMR

Quick Start

Pick the install path that matches what you're trying to do:

You want to…UseWhere to start
Build features end-to-end on a dev box (API + UI + local LLM, single-command up/down)Local workstation stack (this repo's ./workstation wrapper)QUICKSTART.md — five steps, no Docker experience required
Run a headless backend on a server (Docker, GPU, no UI)Docker bundle (docker-compose.bundle.yml)Docker Bundle section below
Use Fortémi as a desktop app on your laptopHotM (UI + bundled API as a single installer)HotM releases — .deb / .msi / .dmg / .AppImage
Compile from source for hacking on the Rust cratesFrom-source buildFrom Source below + CONTRIBUTING.md

HotM setup scripts (run after downloading the installer):

Local Workstation (developer-friendly Docker stack)

The fastest way to get the full backend + UI + local LLM running on your own machine. One unified Docker stack, one wrapper script, no manual postgres or compose juggling.

# Clone both repos as siblings (or skip HotM if you only want the API)
git clone https://git.integrolabs.net/Fortemi/fortemi.git
git clone https://git.integrolabs.net/Fortemi/HotM.git
cd fortemi

# Pre-flight check
./workstation doctor

# Bring everything up (postgres + matric-api + ollama + HotM agent-proxy + UI)
./workstation up

# Pull the two models the stack uses (~7 GB)
./workstation models pull

# Open the UI at http://localhost:4180

./workstation help lists every subcommand (status, logs, shell, psql, reset, models, …). Need only the API without HotM? Skip cloning HotM and run ./workstation up --backend-only.

Want a different LLM than Ollama? Run ./workstation configure-llm for an interactive picker covering vLLM (on host), real OpenAI, OpenRouter, llama.cpp (on host), or staying with Ollama. Writes .env.workstation (gitignored, mode 600); compose loads it automatically on next up. No Dockerfile or compose edits needed.

Full walkthrough with expected output for every step is in QUICKSTART.md; operations reference (including a dedicated "LLM backend selection" section with vLLM specifics) is in WORKSTATION-SETUP.md.

Docker Bundle (headless backend deployment)

All-in-one container with PostgreSQL, Redis, API server, MCP server, and Open3D renderer. Runs on any GPU with 6GB+ VRAM.

Prerequisite: Ollama on the host

Fortémi expects an inference provider. The default is host-installed Ollama — the bundle reaches out to your host's Ollama daemon via host.docker.internal:11434. For other providers (OpenAI, OpenRouter, llama.cpp, custom OpenAI-compatible) see Bring Your Own LLM below.

One-time host setup (Linux/macOS):

# 1. Install Ollama if you don't have it
curl -fsSL https://ollama.com/install.sh | sh

# 2. Pull the two models the bundle defaults to
ollama pull qwen3.5:9b           # ~6.5 GB — generation + vision
ollama pull nomic-embed-text     # ~280 MB — embeddings

Critical on Linux: the systemd Ollama service binds 127.0.0.1 by default and rejects container traffic. The Docker bundle can't reach it without one extra step:

# Make host Ollama accept connections from Docker containers
sudo mkdir -p /etc/systemd/system/ollama.service.d
sudo tee /etc/systemd/system/ollama.service.d/override.conf <<'EOF'
[Service]
Environment="OLLAMA_HOST=0.0.0.0"
EOF
sudo systemctl daemon-reload
sudo systemctl restart ollama

On macOS the Ollama desktop app handles this automatically. On Windows with WSL2, follow the Linux steps inside WSL.

If you skip the systemd override, the bundle will start and the API will be healthy, but GET /health will report capabilities.inference.available: false — no chat, no embeddings, no auto-linking. Full-text search still works.

Bring it up

mkdir -p fortemi && cd fortemi
curl -fsSL -o docker-compose.bundle.yml \
  https://raw.githubusercontent.com/fortemi/fortemi/main/docker-compose.bundle.yml

# Create .env with your hardware profile
echo 'COMPOSE_PROFILES=edge' > .env          # 6-8GB VRAM (RTX 3060/4060/5060)
# echo 'COMPOSE_PROFILES=gpu-12gb' > .env    # 12-16GB VRAM (RTX 4070/5070)
# echo 'COMPOSE_PROFILES=gpu-24gb' > .env    # 24GB+ VRAM (RTX 4090/5090)

docker compose -f docker-compose.bundle.yml up -d

Wait ~30 seconds for first-time initialization, then verify:

curl http://localhost:3000/health
# → {"status":"healthy","capabilities":{"inference":{"available":true,...},...}}

If inference.available is false, you likely missed the OLLAMA_HOST=0.0.0.0 step above — see Troubleshooting below.

Ports: 3000 (API + Swagger UI at /docs), 3001 (MCP), 8080 (Open3D renderer). If host port 3001 is taken on your machine, set MCP_HOST_PORT=3002 in .env to remap; API_HOST_PORT does the same for the API.

The bundle automatically initializes PostgreSQL, runs all migrations, auto-registers MCP OAuth credentials, starts Redis, and launches all services. The Fortémi documentation knowledge base (the "support archive") is not loaded by default — see Support Archive below to add it with one command.

Guided installer: installer/scripts/ provides 8 shell scripts for step-by-step deployment, plus a setup.manifest.yaml for the AIWG installer framework.

Clean reset: docker compose -f docker-compose.bundle.yml down -v && docker compose -f docker-compose.bundle.yml up -d

From Source

# Prerequisites: Rust 1.70+, PostgreSQL 18+ with pgvector + PostGIS, Ollama (optional)
psql -c "CREATE EXTENSION IF NOT EXISTS vector;"
psql -c "CREATE EXTENSION IF NOT EXISTS postgis;"
for f in migrations/*.sql; do psql -d matric -f "$f"; done
DATABASE_URL="postgres://matric:matric@localhost/matric" cargo run --release -p matric-api

First build fails with "missing graph"? Fortemi uses sqlx::query! compile-time checks. Either export DATABASE_URL=... against a Postgres with migrations applied, or generate offline metadata once with cargo sqlx prepare --workspace and build with SQLX_OFFLINE=true. See CONTRIBUTING.md → sqlx compile-time query checks.

Try It

# Store a note
curl -X POST http://localhost:3000/api/v1/notes \
  -H "Content-Type: application/json" \
  -d '{"title": "RAG Architecture", "content": "Retrieval-augmented generation combines..."}'

# Hybrid search (BM25 + semantic + RRF)
curl "http://localhost:3000/api/v1/search?q=using+AI+to+answer+questions+from+documents"

# Chat with your knowledge
curl -X POST http://localhost:3000/api/v1/chat \
  -H "Content-Type: application/json" \
  -d '{"message": "What do I know about retrieval architectures?"}'

# Browse all endpoints
open http://localhost:3000/docs

See Getting Started for the full walkthrough.


Architecture

┌──────────────────┬──────────────────────────────────────────────┐
│  matric-api      │ Axum HTTP REST API with OpenAPI/Swagger       │
├──────────────────┼──────────────────────────────────────────────┤
│  matric-search   │ Hybrid retrieval (BM25 + dense + RRF)         │
├──────────────────┼──────────────────────────────────────────────┤
│  matric-jobs     │ Async NLP pipeline (embed, revise, link,      │
│                  │ extract, diarize, chunk)                       │
├──────────────────┼──────────────────────────────────────────────┤
│  matric-inference│ Multi-provider LLM abstraction                │
│                  │ (Ollama, OpenAI, OpenRouter, llama.cpp)        │
├──────────────────┼──────────────────────────────────────────────┤
│  matric-db       │ PostgreSQL + pgvector + PostGIS repositories   │
│                  │ (sqlx, 106 migrations)                         │
├──────────────────┼──────────────────────────────────────────────┤
│  matric-crypto   │ X25519/AES-256-GCM public-key encryption      │
├──────────────────┼──────────────────────────────────────────────┤
│  matric-core     │ Core types, traits, and error handling         │
├──────────────────┼──────────────────────────────────────────────┤
│  mcp-server      │ MCP agent integration (Node.js, 43/205 tools) │
└──────────────────┴──────────────────────────────────────────────┘

Directory Structure

fortemi/
├── crates/
│   ├── matric-api/          # Axum HTTP API server (routes, handlers, middleware)
│   ├── matric-core/         # Core types, traits, models
│   ├── matric-crypto/       # Public-key encryption (X25519/AES-256-GCM)
│   ├── matric-db/           # PostgreSQL repositories (sqlx)
│   ├── matric-inference/    # Multi-provider inference abstraction
│   ├── matric-jobs/         # Background job worker (NLP pipeline)
│   └── matric-search/       # Hybrid search (FTS + semantic + RRF)
├── mcp-server/              # MCP server (Node.js, 43 core tools)
├── migrations/              # 106 PostgreSQL migrations
├── docker/                  # Docker entrypoints and configs
├── build/                   # CI Dockerfiles (testdb, builder)
├── installer/               # Guided installer scripts
├── docs/                    # 65+ documentation files
│   ├── content/             # Feature and operations guides
│   ├── research/            # Research background
│   └── releases/            # Release announcements
└── docker-compose.bundle.yml  # All-in-one deployment

See Architecture for detailed system design with research citations.


API Endpoints

Full REST API with OpenAPI/Swagger documentation at /docs.

Core Resources

EndpointMethodDescription
/api/v1/notesGET, POSTList and create notes
/api/v1/notes/{id}GET, PUT, DELETERead, update, delete notes
/api/v1/searchGETHybrid search (BM25 + semantic + RRF)
/api/v1/search/federatedPOSTCross-archive federated search
/api/v1/chatPOSTSynchronous LLM chat with knowledge context
/api/v1/tagsGET, POSTTag management
/api/v1/collectionsGET, POSTCollection/folder hierarchy
/api/v1/graphGETKnowledge graph exploration
/api/v1/graph/maintenancePOSTGraph quality pipeline (normalize, SNN, PFNET)

Media & Attachments

EndpointMethodDescription
/api/v1/notes/{id}/attachmentsPOSTUpload file attachment
/api/v1/attachments/{id}/contentGETDownload with HTTP Range support
/api/v1/uploadPOSTTUS resumable upload (tus v1.0.0)

Inference & Configuration

EndpointMethodDescription
/api/v1/inference/configGET, POST, DELETEView/override/reset inference providers
/api/v1/inference/test-connectionPOSTTest backend connectivity
/api/v1/archivesGET, POSTMulti-memory archive management

Metadata & Health

EndpointMethodDescription
/api/v1/conceptsGET, POSTW3C SKOS concept management
/api/v1/concepts/schemes/{id}/export/turtleGETSKOS Turtle export
/api/v1/embeddingsGET, POSTEmbedding set management
/healthGETSystem health with capability report
/docsGETSwagger UI
/openapi.yamlGETOpenAPI specification

See API Reference for all endpoints with request/response examples.


MCP Server

43 core agent tools via Model Context Protocol. Docker bundle exposes MCP on port 3001 with automatic OAuth credential management.

Connect

{
  "mcpServers": {
    "fortemi": { "url": "https://your-domain.com/mcp" }
  }
}

Core Tools (43)

Discriminated-union pattern for agent-friendly interaction:

ToolWhat It Does
capture_knowledgeCreate, update, and manage notes
searchHybrid search with tag filtering and federation
record_provenanceTrack knowledge lineage and sourcing
manage_tagsTag lifecycle and vocabulary management
manage_collectionCollection hierarchy operations
manage_conceptsW3C SKOS concept and scheme management
manage_embeddingsEmbedding set configuration and lifecycle
manage_archivesMulti-memory archive operations
manage_encryptionPublic-key encryption and key management
manage_backupsBackup and restore operations
manage_jobsBackground job monitoring
manage_inferenceProvider configuration and model selection
manage_attachmentsFile upload, metadata, and retrieval
trigger_graph_maintenanceGraph quality pipeline
explore_graphKnowledge graph traversal
get_knowledge_healthDashboard for orphans, stale notes, cold spots
select_memory / get_active_memoryMulti-memory context switching
purge_note / purge_notes / purge_all_notesDestructive cleanup

Set MCP_TOOL_MODE=full for all 205 granular tools. See MCP Guide · MCP Deployment.


Search Capabilities

Query Syntax

hello world        # Match all words (AND)
apple OR orange    # Match either word
apple -orange      # Exclude word
"hello world"      # Match exact phrase

Multilingual Support

ScriptStrategyLanguages
LatinFull stemmingEnglish, German, French, Spanish, Portuguese, Russian
CJKBigram/trigram character matchingChinese, Japanese, Korean
Emoji & symbolsTrigram substring matchingUniversal
Arabic, Cyrillic, Greek, HebrewBasic tokenizationVarious

Search Modes

ModeDescription
Hybrid (default)BM25 + dense vectors + RRF fusion
SemanticDense vector similarity only
Full-textBM25 keyword matching only
GraphTraverse knowledge graph connections
FederatedSearch across multiple memory archives

See Search Guide · Multilingual FTS · Search Operators.


Media Processing

Extraction Adapters (13)

AdapterInputOutput
VisionImages (PNG, JPEG, WebP, etc.)Scene descriptions via Ollama vision LLM
Audio TranscriptionAudio files (MP3, WAV, FLAC, etc.)Timestamped transcripts via Whisper
Speaker DiarizationAudio with multiple speakersSpeaker-labeled captions via pyannote
Video MultimodalVideo files (MP4, MKV, WebM, etc.)Keyframes + scene detection + transcript alignment
3D ModelGLB/glTF filesMulti-view rendered images + vision description
EmailEML/MSG filesRFC 2822/MIME parsing + embedded attachment extraction
SpreadsheetXLSX/XLS/ODS filesMarkdown tables per sheet
ArchiveZIP/tar/gz filesFile listing + text content extraction
PDFPDF documentsText extraction with layout preservation
Media OptimizerVideo/audioFaststart, web-compatible remux, 720p preview
ThumbnailVideoCSS sprite grids + WebVTT maps for seek-bar previews
GLiNERTextNamed entity extraction (concepts, topics)
Fast/Standard NLPTextConcept extraction cascade (granite4:3b → gpt-oss:20b)

Extraction Pipeline

 Upload ──▶ Type Detection ──▶ Adapter Selection ──▶ Extract ──▶ Embed ──▶ Link
                │                                       │
                ▼                                       ▼
         131 document types                    Derived attachments
         auto-detected from                    (thumbnails, transcripts,
         filename + content                     captions, sprite sheets)

Hardware Profiles

ProfileGPU VRAMAudio/DiarizationGen ModelExample GPUs
edge (default)6-8GBCPUqwen3.5:9bRTX 3060 8GB, 4060, 5060
gpu-12gb12-16GBGPUqwen3.5:9bRTX 3060 12GB, 4070, 5070
gpu-24gb24GB+GPUconfigurableRTX 3090, 4090, 5090

Resource Requirements

Idle footprint of the default Docker bundle:

ComponentIdle RAMNotes
PostgreSQL 18~500 MBrequired
Redis~256 MBrequired
qwen3.5:9b (fast gen + vision)~8 GB VRAM/RAMset MATRIC_FAST_GEN_MODEL= to disable
nomic-embed-text (embeddings)~500 MBrequired for indexing
Whisper (gpu-12gb+ profile)~2 GBoptional
GLiNER (gpu-12gb+ profile)~1 GBoptional
Default bundle total~10 GBwith qwen3.5:9b loaded
Minimal profile total~2 GBqwen2.5:3b, no support archive

The Docker bundle does not auto-load the bundled support archive — it mirrors the native build path. See Support Archive below to opt in (one command).

Operators on tight resources can stack the minimal overlay:

docker compose -f docker-compose.bundle.yml -f docker-compose.minimal.yml up -d

The minimal overlay swaps the fast-extraction model to qwen2.5:3b, caps JOB_MAX_CONCURRENT=1, and trims MAX_MEMORIES=2. Target idle ~2 GB. Trade-off: chat quality with qwen2.5:3b is materially lower than the default — this is for "make it run on my laptop", not production.


Support Archive (fortemi-docs)

The bundle ships a pre-built .shard of the Fortémi documentation as an in-product knowledge base — same content as the docs site, but searchable through the same /api/v1/search endpoint as your own notes. Off by default (the Docker bundle mirrors the native build path; neither auto-seeds). Opt in when you want it.

Add it with one command (running instance)

docker compose -f docker-compose.bundle.yml \
  exec fortemi /app/seed-support-archive.sh

Idempotent — re-running is a no-op once seeded (a flag file on the persistent pgdata volume tracks state). Takes ~10–30 seconds depending on disk speed.

Auto-seed on first boot

If you know up front you want the docs available, set this in .env before running docker compose ... up:

LOAD_SUPPORT_MEMORY=true

The seed runs in the background after the API reports healthy.

Querying the archive

The seeded data lives at memory fortemi-docs. Reach it with the X-Fortemi-Memory header:

# Full-text search (works immediately after seeding)
curl -H 'X-Fortemi-Memory: fortemi-docs' \
  'http://localhost:3000/api/v1/search?q=hybrid+search'

# List notes
curl -H 'X-Fortemi-Memory: fortemi-docs' \
  'http://localhost:3000/api/v1/notes?limit=10'

MCP tool clients can scope to the archive via the memory argument on most tools.

Add semantic search over the archive (additional opt-in)

The seed populates Postgres tsvector (FTS) only — no embeddings, so the archive is queryable without an inference provider. To enable semantic search over the docs:

curl -X POST http://localhost:3000/api/v1/notes/reprocess \
  -H 'X-Fortemi-Memory: fortemi-docs' \
  -H 'Content-Type: application/json' \
  -d '{"steps":["embedding"],"revision_mode":"none"}'

Adds "linking" to steps for auto-linking; drops revision_mode:"none" to also AI-revise notes. Cost depends on your configured inference provider (see Multi-Provider Inference for routing).

Refreshing on upgrade

The bundle ships a fresh .shard baked into each release image (auto-rebuilt in CI from the source tree at the tagged commit; see #652). On upgrade the seed flag persists with your data, so the docs archive stays at whatever version you originally seeded. To pick up the latest docs after an image upgrade:

# Drop the existing archive and re-seed from the upgraded image
docker compose -f docker-compose.bundle.yml exec fortemi \
  curl -fsS -X DELETE http://localhost:3000/api/v1/archives/fortemi-docs
docker compose -f docker-compose.bundle.yml exec fortemi \
  rm -f /var/lib/postgresql/data/.fortemi-docs-seeded
docker compose -f docker-compose.bundle.yml \
  exec fortemi /app/seed-support-archive.sh

Your own data in other archives is unaffected.

Skipping or disabling

  • Don't enable it: do nothing. Default is off.
  • Force-skip even if LOAD_SUPPORT_MEMORY=true is set: DISABLE_SUPPORT_MEMORY=true (legacy override; useful if you're inheriting an .env from before the opt-in flip).

Troubleshooting (Docker + Ollama)

capabilities.inference.available: false on /health

The bundle started but can't reach Ollama. Three common causes:

  1. Ollama not installed — ollama list from your host shell errors → install via curl -fsSL https://ollama.com/install.sh | sh.
  2. Ollama bound to 127.0.0.1 only (Linux systemd default) — containers can reach the host gateway but Ollama refuses. Verify with:
    # From inside the bundle:
    docker compose -f docker-compose.bundle.yml exec fortemi \
      curl -fsS --max-time 3 http://host.docker.internal:11434/api/version
    # Connection refused → systemd override is missing
    
    Fix with the OLLAMA_HOST=0.0.0.0 systemd drop-in from Prerequisite: Ollama on the host.
  3. Models not pulled — ollama list on the host shows neither qwen3.5:9b nor nomic-embed-text → pull them. The probe doesn't fail on missing models (the daemon is reachable; the model load happens at first request) but you'll get 404s on the first generation call.

Bundle port collision

The bundle binds host ports 3000 (API) and 3001 (MCP). On a host already running something on those ports:

# In .env
API_HOST_PORT=3010
MCP_HOST_PORT=3011

Container-side ports stay fixed; only the host mapping changes. ISSUER_URL must match the host-facing address (e.g. http://localhost:3010).

Connecting to a remote Ollama instead of host

Edit .env:

OLLAMA_BASE=http://your-remote-ollama-host:11434

The bundle's extra_hosts: host.docker.internal:host-gateway only matters when reaching the local host. For remote hosts, use the real DNS name or IP. If TLS is in the path, prefix with https://.

Using something other than Ollama entirely

Three native alternatives ship as first-class profiles in MATRIC_INFERENCE_DEFAULT: openai, openrouter, llamacpp. See Bring Your Own LLM.


Multi-Provider Inference

Fortemi treats every advertised provider as a first-class peer. The runtime is driven by a static provider profile catalog — the four v1 entries below cover hosted (OpenAI, OpenRouter), local-daemon (Ollama), and bring-your-own-server (llama.cpp) inference, all reachable via the same hot-swap API.

Provider profiles (v1)

ProviderBackend protocolAPI keyEmbeddingsDefault model
OllamaOllama-native (/api/generate)noneyesqwen3.5:9b / nomic-embed-text
OpenAIOpenAI-compatible (/v1/*)requiredyesgpt-4o-mini / text-embedding-3-small
OpenRouterOpenAI-compatiblerequirednoanthropic/claude-sonnet-4 / (none)
llama.cppOpenAI-compatibleoptionaldepends on build(operator-set)

Adding new well-known providers (vLLM, LiteLLM, LocalAI, Groq, Together, …) is a 5-line addition to crates/matric-inference/src/provider_profiles.rs with no enum or parser changes.

Provider-qualified slugs

qwen3:8b                                    → default provider
ollama:qwen3:8b                             → explicit Ollama
openai:gpt-4o                               → OpenAI
openrouter:anthropic/claude-sonnet-4        → OpenRouter
llamacpp:qwen2.5-7b-instruct                → llama.cpp

Runtime reconfiguration

Hot-swap any provider's credentials, model, or routing via POST /api/v1/inference/config — no restart required. Configuration precedence: db_override → env → default. Two safety primitives:

  • ?dry_run=true — validate the merged config and return the effective state without persisting or hot-swapping. Useful for operator UIs running pre-flight checks.
  • ?atomic=true — probe every backend the request touches before committing. On any probe failure: 503 + structured failures: [...] array; the live registry and DB stay on the previous good config. Avoids the brief error window where a half-applied swap serves bad creds.
# Validate without applying
curl -X POST http://localhost:3000/api/v1/inference/config?dry_run=true \
  -H 'Content-Type: application/json' \
  -d '{"openrouter":{"api_key":"sk-or-v1-...","generation_model":"anthropic/claude-3.5-sonnet"}}'

# Atomic swap — abort if any probe fails
curl -X POST 'http://localhost:3000/api/v1/inference/config?atomic=true' \
  -H 'Content-Type: application/json' \
  -d '{"openrouter":{"api_key":"sk-or-v1-..."}}'

Independent embedding/generation routing

OpenRouter doesn't expose embeddings; Groq is API-only with no local model; some operators want to keep embeddings on-device for privacy while paying for hosted chat. Set MATRIC_EMBEDDING_PROVIDER (or the embedding_backend field on POST /api/v1/inference/config) to route embedding calls through a different provider than the active default.

# .env: chat through OpenRouter, embed locally via Ollama
MATRIC_INFERENCE_DEFAULT=openrouter
MATRIC_EMBEDDING_PROVIDER=ollama
OPENROUTER_API_KEY=sk-or-v1-...

The runtime validates the override against the catalog at boot and on every POST /config call: pointing embedding_backend at OpenRouter (which has no embedding capability) returns 400 with a descriptive error before persisting.

Bring Your Own LLM

Ollama is the default for the Docker bundle, but it is one option among four — Fortemi does not require Ollama. Pick a profile and set the matching .env block:

# Native llama.cpp profile (recommended for self-hosted local inference)
MATRIC_INFERENCE_DEFAULT=llamacpp
LLAMACPP_BASE_URL=http://host.docker.internal:8080/v1
LLAMACPP_GEN_MODEL=qwen2.5-7b-instruct
# LLAMACPP_API_KEY=...           # only if llama-server launched with --api-key

# Native OpenAI proper
MATRIC_INFERENCE_DEFAULT=openai
OPENAI_API_KEY=sk-...
OPENAI_GEN_MODEL=gpt-4o-mini

# Native OpenRouter (chat only — pair with MATRIC_EMBEDDING_PROVIDER for embed)
MATRIC_INFERENCE_DEFAULT=openrouter
OPENROUTER_API_KEY=sk-or-v1-...
OPENROUTER_GEN_MODEL=anthropic/claude-sonnet-4
MATRIC_EMBEDDING_PROVIDER=ollama

OpenRouter routing rules and analytics use HTTP-Referer and X-Title headers; Fortemi defaults them to https://fortemi.io / Fortemi. Override per-app for downstream tools that ship Fortemi as a sidecar:

OPENROUTER_HTTP_REFERER=https://your-app.example.com
OPENROUTER_APP_NAME=Your App

To run a llama.cpp sidecar alongside the bundle, place a GGUF model at ./models/model.gguf and bring up both compose files:

docker compose -f docker-compose.bundle.yml -f docker-compose.llamacpp.yml up -d

docker-compose.llamacpp.yml ships the ghcr.io/ggerganov/llama.cpp:server image with the OpenAI-compatible protocol exposed at :8080/v1. See the file header for tunables (LLAMACPP_MODEL_FILE, LLAMACPP_CTX_SIZE, LLAMACPP_GPU_LAYERS).

Custom OpenAI-compatible endpoints (vLLM, LiteLLM, LocalAI, on-prem providers not yet in the catalog) keep working via the legacy escape hatch:

MATRIC_INFERENCE_DEFAULT=openai
OPENAI_BASE_URL=http://your-host:8000/v1
OPENAI_API_KEY=anything-or-real-key

Disabling Ollama entirely: set MATRIC_INFERENCE_DEFAULT to anything other than ollama and leave OLLAMA_BASE unset. The Ollama backend isn't constructed when it isn't the default or embedding override, so a dead host.docker.internal:11434 won't be probed.


Multi-Memory Archives

Parallel memory archives with schema-level isolation for tenant separation, project segmentation, or context switching.

  • X-Fortemi-Memory header selects target memory per request
  • Default memory maps to public schema (no header needed)
  • 14 shared tables (auth, jobs, config) + 41 per-memory tables (notes, tags, embeddings, etc.)
  • POST /api/v1/archives creates new archives with automatic schema cloning
  • POST /api/v1/search/federated searches across multiple archives simultaneously

See Multi-Memory Guide · Agent Strategies.


Authentication

Authentication is fail-closed by default via REQUIRE_AUTH=true. Anonymous local sidecar/dev mode requires setting both REQUIRE_AUTH=false and I_UNDERSTAND_NO_AUTH=true.

MethodHow
OAuth2Client credentials or authorization code via /oauth/token
API KeysCreate via POST /api/v1/api-keys, use as Bearer token

Public endpoints (always accessible): /health, /docs, /openapi.yaml, /oauth/*, /.well-known/*

See Authentication Guide.


Configuration

Key variables (see full reference for all ~27 variables):

VariableDefaultDescription
COMPOSE_PROFILESedgeHardware profile: edge, gpu-12gb, gpu-24gb
DATABASE_URLpostgres://localhost/matricPostgreSQL connection
PORT3000API server port
REQUIRE_AUTHtrueRequire OAuth2/API key auth on protected routes
ISSUER_URLhttps://localhost:3000OAuth2 issuer URL (required for OAuth/MCP)
OLLAMA_BASEhttp://localhost:11434Ollama API endpoint
OLLAMA_GEN_MODELqwen3.5:9bGeneration + vision model
OLLAMA_EMBED_MODELnomic-embed-textEmbedding model
WHISPER_BASE_URLhttp://whisper:8000Audio transcription endpoint
MAX_MEMORIES10Max archives (scale with RAM: 10→8GB, 50→16GB, 200→32GB, 500→64GB+)
MCP_TOOL_MODEcorecore (43 tools) or full (205 tools)

Security Model

FeatureDescription
Opt-in authOAuth2 (client credentials + auth code) and API keys
Schema isolationPer-memory PostgreSQL schemas for tenant separation
PKE encryptionX25519/AES-256-GCM public-key encryption for notes
MCP credential auto-managementAuto-registers OAuth client on startup; credentials persisted across restarts
Input validationRequest validation at API boundary
TUS checksumsIntegrity verification on resumable uploads
Edge deploymentNo cloud dependency; runs entirely self-hosted

Development

# Install pre-commit hooks (first time)
./scripts/install-hooks.sh

# Run tests
cargo test --workspace

# Format + lint
cargo fmt && cargo clippy -- -D warnings

# Run with debug logging
RUST_LOG=debug cargo run -p matric-api

Database

  • PostgreSQL 18 with pgvector + PostGIS extensions
  • Connection: postgres://matric:matric@localhost/matric
  • 106 migrations in migrations/ directory
  • Extensions created by entrypoint/CI as superuser

Testing

cargo test                    # Unit tests
cargo test --workspace        # All crates

Tests run against real PostgreSQL (not mocks). CI provides dedicated test containers with pgvector + PostGIS. See Testing Guide.

Versioning

CalVer: YYYY.M.PATCH (e.g., 2026.4.0). Git tags use v prefix: v2026.4.0. See Releasing.


Documentation

Getting Started

Features

Operations

Technical


References

  • Cormack, G.V., Clarke, C.L.A., & Büttcher, S. (2009). "Reciprocal rank fusion outperforms condorcet and individual rank learning methods." SIGIR '09.
  • Lewis, P. et al. (2020). "Retrieval-augmented generation for knowledge-intensive NLP tasks." NeurIPS 2020.
  • Reimers, N. & Gurevych, I. (2019). "Sentence-BERT: Sentence embeddings using siamese BERT-networks." EMNLP 2019.
  • Malkov, Y.A. & Yashunin, D.A. (2020). "Efficient and robust approximate nearest neighbor search using HNSW." IEEE TPAMI.
  • Hogan, A. et al. (2021). "Knowledge graphs." ACM Computing Surveys.
  • Kusupati, A. et al. (2022). "Matryoshka representation learning." NeurIPS 2022.
  • Miles, A. & Bechhofer, S. (2009). "SKOS simple knowledge organization system reference." W3C Recommendation.

See docs/research/ for detailed paper analyses.


Related Projects

  • AIWG — Multi-agent AI framework with 43 Fortémi MCP tools
  • Agentic Sandbox — Runtime isolation for persistent AI agent processes
  • HotM (GitHub mirror) — first-party desktop app for Fortemi (React 19 SPA + bundled matric-api sidecar; Linux .deb / Windows .msi / macOS .dmg / .AppImage)

License

BSL-1.1 (Business Source License 1.1) — converts to AGPL-3.0 on the Change Date (February 16, 2030).

Free as a workstation tool. You may run Fortémi at no cost as a single-user workstation tool on your own local machine (localhost / single-workstation deployment) — including for your own commercial work — and for development and testing of applications that integrate with it.

Server deployments require a commercial license. Deploying Fortémi as a multi-user, networked, hosted, or otherwise shared server requires a commercial license from the Licensor. (Think SQL Server Express vs. SQL Server: the workstation edition is free; running it as a server is licensed.)

See BSL-LICENSE for the full terms and the Additional Use Grant, and LICENSE.txt for the Change License.


Back to Top

Made with determination by Joseph Magly

Ver o original no GitHub

Bom para

Relacionados