Getting Started

🖥️ Want a desktop app, not an API?

If you want to use Fortemi as a knowledge base on your laptop — editor, graph, capture, search — install HotM instead. HotM is the first-party desktop application: a Linux .deb / Windows .msi / macOS .dmg / .AppImage that packages the React UI plus a bundled matric-api sidecar. No Docker, no Postgres setup, no backend ops.

One prereq script does the rest:

Linux: bash scripts/setup-linux.sh → install guide

macOS: bash scripts/setup-macos.sh → install guide

This page (and the rest of this repo) is for the headless backend — agents over MCP, custom UIs, multi-user deployments, air-gapped servers. If that's what you want, keep reading.

Looking to deploy Fortemi as a backend? See the Quickstart Guide for step-by-step deployment using published GHCR images, including prerequisite validation, hardware detection, and model selection. This page is a feature tour — it assumes you already have a running instance.

Note: Internal code and configurations use the name Fortémi — this is Fortémi.

This guide takes you from a running Fortemi instance to your first search result in 5 minutes. You'll create notes and explore hybrid search combining traditional keyword matching with AI-powered semantic understanding.

Prerequisites

Docker and Docker Compose (version 20.10 or later)
Optional: Ollama for AI features (embeddings, semantic search, auto-linking)
Optional: curl or any HTTP client for testing

Step 1: Start Fortemi

The Docker bundle runs PostgreSQL, the API server, and the MCP server in a single container. Start it with one command:

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

This automatically:

Initializes PostgreSQL 18 with pgvector and PostGIS extensions
Runs all database migrations
Starts the API on port 3000
Starts the MCP server on port 3001

Verify the deployment:

curl http://localhost:3000/health

You should see:

{
  "status": "healthy",
  "version": "2026.4.0",
  "database": "connected"
}

The interactive API documentation is available at http://localhost:3000/docs. This Swagger UI lets you explore all API endpoints and test them directly in your browser.

Step 2: Create Your First Notes

Let's create three notes covering different topics. These will demonstrate Fortemi's search, auto-tagging, and auto-linking capabilities.

When you create a note, Fortemi's NLP pipeline automatically:

Generates a title from the content
Tags with SKOS concepts (8-15 hierarchical tags covering domain, topic, methodology, etc.)
Extracts metadata (authors, year, language, etc.)
Generates embeddings for semantic search
Creates semantic links to related notes

All of this happens in the background — you just write content.

Note 1: Rust Ownership

curl -X POST http://localhost:3000/api/v1/notes \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Rust Ownership Model",
    "content": "Rust uses a unique ownership system to manage memory without garbage collection. Each value has a single owner, and when the owner goes out of scope, the value is dropped. This prevents memory leaks and data races at compile time.",
    "tags": ["programming/rust", "memory-management"]
  }'

Save the id from the response - you'll need it later.

Note 2: C++ Memory Management

curl -X POST http://localhost:3000/api/v1/notes \
  -H "Content-Type: application/json" \
  -d '{
    "title": "C++ Manual Memory Management",
    "content": "C++ requires explicit memory management using new and delete operators. Smart pointers like unique_ptr and shared_ptr provide RAII-based automatic cleanup. Memory leaks occur when allocated memory is not freed, while dangling pointers reference freed memory.",
    "tags": ["programming/cpp", "memory-management"]
  }'

Note 3: Knowledge Management Systems

curl -X POST http://localhost:3000/api/v1/notes \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Building a Personal Knowledge Graph",
    "content": "Effective knowledge management systems connect ideas through semantic relationships. Tools like Obsidian, Roam Research, and Fortemi enable networked thought by automatically linking related concepts. The key is balancing structure (tags, folders) with organic discovery (search, graph exploration).",
    "tags": ["research", "knowledge-management"]
  }'

Step 3: Search Your Notes

Full-text search works immediately without any AI setup. Let's search for "memory management":

curl "http://localhost:3000/api/v1/search?q=memory+management"

You'll see results ranked by BM25 relevance:

{
  "results": [
    {
      "note_id": "...",
      "title": "Rust Ownership Model",
      "score": 0.876,
      "snippet": "...ownership system to manage memory without garbage collection..."
    },
    {
      "note_id": "...",
      "title": "C++ Manual Memory Management",
      "score": 0.823,
      "snippet": "...explicit memory management using new and delete..."
    }
  ],
  "total": 2,
  "mode": "hybrid"
}

Search Modes

Fortemi supports three search strategies:

Hybrid (default): Combines full-text search and semantic similarity using Reciprocal Rank Fusion.

curl "http://localhost:3000/api/v1/search?q=memory+management&mode=hybrid"

Full-text search (FTS): Pure keyword matching with BM25 ranking. Best for exact phrases or code snippets.

curl "http://localhost:3000/api/v1/search?q=memory+management&mode=fts"

Semantic search: Pure vector similarity. Best for conceptual queries. Requires embeddings (see Step 4).

curl "http://localhost:3000/api/v1/search?q=memory+management&mode=semantic"

Semantic search returns an error until you generate embeddings in Step 4.

Query Syntax

Fortemi supports advanced query operators:

# Match all words (AND)
curl "http://localhost:3000/api/v1/search?q=rust+ownership"

# Match either word (OR)
curl "http://localhost:3000/api/v1/search?q=rust+OR+cpp"

# Exclude words (NOT)
curl "http://localhost:3000/api/v1/search?q=memory+-garbage"

# Exact phrase match
curl "http://localhost:3000/api/v1/search?q=%22garbage+collection%22"

See the Search Operators Guide for advanced filtering and ranking techniques.

Step 4: Add Intelligence with Ollama

AI features (semantic search, auto-linking, revision suggestions) require embeddings generated by a local or remote LLM. We'll use Ollama for local inference.

Install Ollama

# Linux or macOS
curl -fsSL https://ollama.ai/install.sh | sh

# Verify installation
ollama --version

For Windows, download from https://ollama.ai/download.

Pull the Embedding Model

Fortemi defaults to nomic-embed-text, a high-quality 768-dimension model optimized for retrieval:

ollama pull nomic-embed-text

This downloads approximately 274MB and runs inference on your CPU or GPU.

Optional: Pull a Generation Model

For AI-powered note revision and summarization:

ollama pull llama3.2:3b

See the Embedding Model Selection Guide for alternative models and trade-offs.

Generate Embeddings

Fortemi automatically generates embeddings when notes are created if Ollama is running. For existing notes, trigger embedding jobs manually:

# Get all note IDs
curl http://localhost:3000/api/v1/notes | jq -r '.notes[].id'

# Generate embeddings for a specific note
curl -X POST http://localhost:3000/api/v1/jobs \
  -H "Content-Type: application/json" \
  -d '{
    "note_id": "YOUR_NOTE_ID",
    "job_type": "embedding"
  }'

Or generate embeddings for all notes in a tag:

# Embed all notes tagged "programming"
curl -X POST http://localhost:3000/api/v1/embedding-sets/default/embed \
  -H "Content-Type: application/json" \
  -d '{
    "tag_filter": "programming"
  }'

Check job status:

curl http://localhost:3000/api/v1/jobs

Test Semantic Search

Once embeddings exist, semantic search finds conceptually related notes even with different terminology:

# Finds both Rust and C++ notes despite different wording
curl "http://localhost:3000/api/v1/search?q=preventing+memory+leaks&mode=semantic"

Hybrid mode (default) now combines both keyword matching and semantic similarity for optimal results.

Automatic Semantic Linking

Fortemi automatically creates bidirectional links between notes with >70% semantic similarity. Check links for your Rust ownership note:

# Replace {id} with the note ID from Step 2
curl http://localhost:3000/api/v1/graph/{id}/explore

You should see a link to the C++ memory management note because both discuss memory safety, even though they use different terminology (ownership vs. pointers, dropped vs. freed).

The knowledge graph response shows:

{
  "node": {
    "id": "...",
    "title": "Rust Ownership Model",
    "tags": ["programming/rust", "memory-management"]
  },
  "links": [
    {
      "target_id": "...",
      "target_title": "C++ Manual Memory Management",
      "similarity": 0.78,
      "link_type": "semantic"
    }
  ]
}

Step 5: Organize with Tags and Collections

Hierarchical Tags

Tags use / for hierarchy, enabling filtered searches:

# Find all programming notes
curl "http://localhost:3000/api/v1/search?q=*&tags=programming"

# Find only Rust notes
curl "http://localhost:3000/api/v1/search?q=*&tags=programming/rust"

Fortemi enforces strict tag filtering. When you specify tags=programming/rust, you'll never see results tagged with programming/cpp or research, ensuring data isolation.

See the Tags Guide for advanced taxonomy management.

Collections

Group related notes into collections (folders):

# Create a collection
curl -X POST http://localhost:3000/api/v1/collections \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Programming Languages",
    "description": "Comparative notes on language memory models"
  }'

# Add notes to the collection
curl -X POST http://localhost:3000/api/v1/collections/{collection_id}/notes \
  -H "Content-Type: application/json" \
  -d '{
    "note_id": "YOUR_RUST_NOTE_ID"
  }'

Collections support nested hierarchies and can have their own tags and metadata.

SKOS Semantic Taxonomy (Automatic)

Fortemi implements W3C SKOS (Simple Knowledge Organization System) with automatic concept tagging. When you created the notes above, the NLP pipeline already generated SKOS concept tags for each one. Check what was auto-generated:

# View auto-generated concept tags for a note
curl "http://localhost:3000/api/v1/notes/{id}/concepts"

You'll see concepts like domain/programming, topic/memory-management, technique/ownership-model — all created automatically with proper broader/narrower hierarchies.

The SKOS management tools are primarily for curation — reviewing auto-generated concepts, promoting candidates to "controlled" status, and merging duplicates. Manual concept creation is only needed for organizational structures the AI can't infer (like project names or client identifiers).

See the Tags Guide for SKOS curation workflows and governance.

Step 6: Explore Version History

Fortemi maintains complete version history for all notes. Every update creates a new immutable version.

Update a Note

# Update the Rust note to add borrowing details
curl -X PATCH http://localhost:3000/api/v1/notes/{id} \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Rust uses a unique ownership system to manage memory without garbage collection. Each value has a single owner, and when the owner goes out of scope, the value is dropped. Borrowing allows temporary references without transferring ownership, enforced by the borrow checker at compile time. This prevents memory leaks and data races."
  }'

View Version History

curl http://localhost:3000/api/v1/notes/{id}/versions

Response shows all versions with timestamps and content diffs:

{
  "versions": [
    {
      "version_number": 2,
      "created_at": "2026-02-03T14:32:18Z",
      "content": "Rust uses a unique ownership system...[updated]",
      "changed_fields": ["content"]
    },
    {
      "version_number": 1,
      "created_at": "2026-02-03T14:15:42Z",
      "content": "Rust uses a unique ownership system...[original]",
      "changed_fields": []
    }
  ]
}

Restore a Previous Version

# Restore version 1
curl -X POST http://localhost:3000/api/v1/notes/{id}/versions/1/restore

This creates version 3 with version 1's content, preserving the complete audit trail.

Step 7: Working with Multiple Memories

Fortemi supports parallel memory archives for organizing different projects or knowledge domains. Each memory operates as an isolated namespace with complete data separation.

Create a Memory

curl -X POST http://localhost:3000/api/v1/memories \
  -H "Content-Type: application/json" \
  -d '{
    "name": "work-notes",
    "description": "Work-related documentation"
  }'

Switch Between Memories

Use the X-Fortemi-Memory header to operate on a specific memory:

# Create note in work memory
curl -X POST http://localhost:3000/api/v1/notes \
  -H "Content-Type: application/json" \
  -H "X-Fortemi-Memory: work-notes" \
  -d '{
    "title": "Project Meeting Notes",
    "content": "# Q1 Planning Meeting\n\nDiscussed roadmap priorities..."
  }'

# Search in work memory
curl "http://localhost:3000/api/v1/search?q=meeting" \
  -H "X-Fortemi-Memory: work-notes"

Without the header, operations default to the "default" memory. All your previous notes from Steps 2-6 are in the default memory.

Search Across Memories

Search multiple memories simultaneously with unified result ranking:

curl -X POST http://localhost:3000/api/v1/search/federated \
  -H "Content-Type: application/json" \
  -d '{
    "query": "project documentation",
    "memories": ["default", "work-notes"]
  }'

Results include memory attribution showing which memory each result came from. This enables cross-project discovery while maintaining data isolation.

See the Multi-Memory Guide for comprehensive documentation on memory management, cloning, and federated search.

What's Next?

Goal	Guide
Understand deployment architectures	Architecture
Configure search and AI features	Search Guide, Inference Backends
Deploy to production	Deployment and Migrations
Connect AI assistants (Claude Code)	MCP Server
Set up OAuth authentication	Authentication
Troubleshoot MCP issues	MCP Troubleshooting
Optimize performance	Operations Guide
Configure multilingual search	Multilingual FTS
Plan hardware requirements	Hardware Planning
Monitor in real-time	Real-Time Events
Explore advanced features	File Attachments, PKE Encryption
Organize with multiple memories	Multi-Memory Guide

Explore the API

The full API reference is available at http://localhost:3000/docs. Key endpoints to explore:

POST /api/v1/notes - Create notes with optional file attachments
GET /api/v1/search - Hybrid search with tag filtering
GET /api/v1/graph/{id}/explore - Traverse the knowledge graph
POST /api/v1/ai/revise - AI-powered note revision
POST /api/v1/export/markdown - Export to Markdown with YAML frontmatter
GET /api/v1/document-types - View 131 pre-configured document types
POST /api/v1/memories - Create and manage memory archives
POST /api/v1/search/federated - Search across multiple memories

See the API Documentation for detailed endpoint specifications and examples.

Example Workflows

Research Workflow:

Import papers as file attachments with auto-chunking
Generate embeddings for semantic search
Tag with hierarchical taxonomy (e.g., research/ml/nlp)
Explore auto-generated links between related papers
Create synthesis notes linking to chunks

See Workflows Guide for detailed scenarios.

Software Documentation:

Create notes from code comments or README files
Use document types for automatic chunking (e.g., code/rust, code/python)
Tag by project and component
Search with operators: error handling -logging
Export knowledge graph for architecture diagrams

See Document Types Guide for optimization strategies.

Cleaning Up

Stop Fortemi (Keep Data)

docker compose -f docker-compose.bundle.yml down

This stops the container but preserves all data in Docker volumes. Start again with up -d.

Wipe All Data

# WARNING: Deletes all notes, tags, embeddings, and configurations
docker compose -f docker-compose.bundle.yml down -v

The -v flag removes volumes, giving you a clean slate. Useful for testing or starting fresh.

View Logs

# Follow logs in real-time
docker compose -f docker-compose.bundle.yml logs -f

# View last 100 lines
docker compose -f docker-compose.bundle.yml logs --tail=100

Troubleshooting

Health Check Fails

If curl http://localhost:3000/health returns an error:

Check container status: docker compose -f docker-compose.bundle.yml ps
View logs: docker compose -f docker-compose.bundle.yml logs matric
Verify ports are not in use: lsof -i :3000 (Linux/macOS)

Semantic Search Returns "No embeddings found"

You need to generate embeddings first (Step 4). Verify Ollama is running:

# Check Ollama status
curl http://localhost:11434/api/tags

# Verify model is available
ollama list | grep nomic-embed-text

If Ollama is running inside Docker, update OLLAMA_BASE in docker-compose.bundle.yml:

environment:
  - OLLAMA_BASE=http://host.docker.internal:11434  # Default
  # Or for Linux without host.docker.internal:
  # - OLLAMA_BASE=http://172.17.0.1:11434

Automatic Linking Not Working

Auto-linking requires:

Embeddings generated for both notes
Semantic similarity >70% (configurable)
Notes in the same embedding set (default: "default")

Check embedding status:

# View embedding sets
curl http://localhost:3000/api/v1/embedding-sets

# Check if note has embeddings
curl http://localhost:3000/api/v1/notes/{id}

See the Embedding Sets Guide for advanced configuration.

Docker Container Exits Immediately

Common causes:

Port conflict: Another service using 3000 or 3001

Volume permission issues: Delete volumes and recreate

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

Invalid environment variables: Check .env file syntax

View detailed error logs:

docker compose -f docker-compose.bundle.yml logs matric

For more troubleshooting guidance, see MCP Troubleshooting and Operations Guide.

Next Steps

Now that you have Fortemi running and understand the basics:

Customize for your use case: Adjust embedding models, search parameters, and document types in the configuration
Integrate with your workflow: Connect Fortemi to your note-taking tools, IDEs, or AI assistants via the API
Scale up: Review Hardware Planning for production deployments
Secure your instance: Configure OAuth authentication following the Authentication Guide

Welcome to AI-enhanced knowledge management with Fortemi.

FilesExpand file tree

getting-started.md

Latest commit

History