perstarkse/minne: Self-Hosted Knowledge Graph with AI-Assisted Linking

perstarkse/minne: Self-Hosted Knowledge Graph with AI-Assisted Linking

Developers and researchers who capture information constantly face a familiar trade-off: manual note-taking tools like Obsidian and Logseq demand tedious linking to build connections, while fully automated systems sacrifice control over how ideas relate. perstarkse/minne addresses this gap directly—a Rust-built, self-hosted knowledge base that combines effortless content capture with AI-assisted relationship discovery, while preserving full manual curation when you want it.

What is perstarkse/minne?

perstarkse/minne (Swedish for "memory") is an open-source personal knowledge management (PKM) and read-it-later application maintained by Per Stark. Built in Rust with the Axum web framework, it reached 257 GitHub stars and 10 forks as of its last commit on July 8, 2026. The project is licensed under the GNU Affero General Public License v3.0 (AGPL-3.0), reflecting its commitment to user freedom and data sovereignty.

At its core, Minne is a graph-powered knowledge base inspired by the Zettelkasten method. Unlike traditional tools that rely entirely on manual [[wikilinks]], Minne uses SurrealDB—a multi-model database supporting graph, document, and vector operations—to automatically discover connections between notes, URLs, PDFs, images, and audio files. The system processes content through an OpenAI-compatible API with structured outputs, extracting entities and relationships without requiring users to maintain rigid tagging conventions.

What distinguishes Minne in the current PKM landscape is its deliberate hybrid approach. The maintainer explicitly designed it after finding existing solutions polarizing: manual tools became "a hindrance," while automated systems "miss important context or create relationships I wouldn't have chosen myself." This middle-ground philosophy—AI handles extraction, humans retain veto and editing power—resonates with developers skeptical of black-box automation.

The technical architecture reinforces this credibility. Server-side rendering with HTMX (not a heavy JavaScript^{↗ Bright Coding Blog} SPA) keeps the interface lightweight, while the embedded Servo engine and PDFium handle web scraping and document rendering without external dependencies.

Key Features

Hybrid AI-Manual Graph Construction Minne offers three relationship-building modes: fully manual entity and link creation, fully automatic AI extraction, or a hybrid where AI suggests connections for user approval. This flexibility is central to the tool's design philosophy.

Hybrid Retrieval System Search combines vector similarity (semantic meaning) with full-text search (exact term matching). An optional FastEmbed reranking stage—powered by fastembed-rs—rescues results with a cross-encoder for improved relevance, though this trades ~1.1GB of cached model data and additional CPU per query.

Multi-Modal Content Ingestion Beyond text notes and URLs, Minne processes PDFs, audio files, and images into the knowledge graph. Web content extraction uses an embedded Servo engine rather than fragile external scraping services.

Conversational AI Interface A dedicated chat mode lets users "explore concepts, find connections, or reason about your knowledge" through natural language, with the AI analyzing queries against the entire knowledge base rather than returning raw search results.

Visual Graph Explorer An interactive D3.js-based visualization renders knowledge entities as navigable nodes, with relationship types distinguished by connection style. This addresses a common pain point in PKM tools: making the graph structure actually inspectable.

Scratchpad Capture A lightweight quick-capture feature for transient thoughts, with explicit promotion to permanent knowledge-base entries when ready—reducing friction without cluttering the main graph.

Flexible Deployment Architecture Three build targets: main (combined server + worker), server (web-only), and worker (background processing only). This supports resource-optimized deployments where ingestion and query serving scale independently.

Use Cases

Research Knowledge Synthesis Academic researchers or investigative journalists can dump URLs, PDFs, and interview transcripts into Minne, then use the chat interface to trace thematic connections across sources they might not have manually linked. The hybrid AI-manual mode lets them validate automated thematic connections against domain expertise.

Technical Documentation Management DevOps^{↗ Bright Coding Blog} and platform engineers maintaining internal documentation can ingest architecture decision records, runbooks, and incident post-mortems. The graph structure surfaces related systems automatically, while manual curation preserves organizational-specific context that generic AI would miss.

Personal Learning & Skill Development Developers learning new technologies can capture tutorials, documentation, and experimental notes. The automatic linking reveals conceptual bridges between, say, a Rust async article and a earlier Tokio experiment—connections easily lost in folder hierarchies.

Content Curation & Newsletter Research Writers and editors using read-it-later workflows can process saved articles through Minne's pipeline, then query the accumulated knowledge base for thematic clusters when drafting. The iOS Shortcut enables mobile capture without breaking flow.

Compliance & Audit Trail Construction Teams in regulated industries can use Minne's self-hosted nature and AGPL license to maintain knowledge graphs with full data control, ingesting meeting transcripts, policy documents, and training materials with verifiable provenance.

Installation & Setup

The fastest path to running perstarkse/minne uses Docker^{↗ Bright Coding Blog} Compose, which provisions SurrealDB automatically:

# Clone the repository
git clone https://github.com/perstarkse/minne.git
cd minne

# Start Minne and its database
docker compose up -d

# Access at http://localhost:3000

Critical post-clone step: Replace your_openai_api_key_here in docker-compose.yml with your actual API key. If using a local provider like Ollama, also configure OPENAI_BASE_URL.

For Nix users, a one-command alternative exists:

nix run 'github:perstarkse/minne#main'

This fetches Minne and all dependencies through the Nix package manager.

Pre-built binaries for Windows, macOS, and Linux are available from GitHub Releases, though these require a separately provisioned SurrealDB instance.

Building from source requires Rust and SurrealDB in your PATH:

git clone https://github.com/perstarkse/minne.git
cd minne
cargo run --release --bin main

Real Code Examples

The README provides configuration through either environment variables or a config.yaml file, with environment variables taking precedence. Here is the documented example configuration:

surrealdb_address: "ws://127.0.0.1:8000"
surrealdb_username: "root_user"
surrealdb_password: "root_password"
surrealdb_database: "minne_db"
surrealdb_namespace: "minne_ns"
openai_api_key: "sk-YourActualOpenAIKeyGoesHere"
data_dir: "./minne_app_data"
http_port: 3000
# rust_log: "info"

This YAML configures the SurrealDB WebSocket connection, authentication credentials, and the OpenAI-compatible API key. The data_dir specifies where local files and caches reside, while http_port controls the web interface binding.

For enabling the optional FastEmbed reranking stage, the README documents:

reranking_enabled: true
reranking_pool_size: 2
fastembed_cache_dir: "/var/lib/minne/fastembed"  # optional override, defaults to .fastembed_cache

The reranking_pool_size: 2 default targets single-user deployments; the maintainer notes this "could work with a pool size on 1 as well." The explicit cache directory override is useful for containerized deployments where ephemeral storage should be minimized.

Environment variable equivalents follow standard conventions:

export SURREALDB_ADDRESS="ws://127.0.0.1:8000"
export SURREALDB_USERNAME="root_user"
export SURREALDB_PASSWORD="root_password"
export SURREALDB_DATABASE="minne_db"
export SURREALDB_NAMESPACE="minne_ns"
export OPENAI_API_KEY="sk-YourActualOpenAIKeyGoesHere"
export HTTP_PORT=3000

The README emphasizes that environment variables override config.yaml values, supporting secrets management through container orchestration or external vaults without modifying committed configuration files.

Advanced Usage & Best Practices

Model Selection Strategy Access the /admin endpoint to configure separate models for content processing and chat. The content processing model must support structured outputs—verify this capability with your provider before deployment. When switching embedding models, update the dimension setting (1536 for text-embedding-3-small, 768 for nomic-embed-text) to match.

Resource Planning for Reranking The ~1.1GB FastEmbed model download occurs on first startup with reranking enabled. Plan for this in bandwidth-constrained or air-gapped deployments by pre-seeding the cache directory. The CPU overhead per query makes this feature best suited for low-latency-tolerance scenarios rather than high-throughput ingestion pipelines.

Deployment Mode Selection The main binary suits most individual users. Separate server and worker binaries become relevant when horizontal scaling matters—run multiple workers behind a queue for high-volume ingestion while keeping the web interface responsive.

Data Portability Considerations As an AGPL project with self-hosted SurrealDB, Minne avoids vendor lock-in common in SaaS PKM tools. Regular database backups through SurrealDB's native tools provide recoverability without proprietary export formats.

Comparison with Alternatives

The maintainer explicitly acknowledges KaraKeep as "an excellent application in a similar space." Minne differentiates through its graph-native architecture and hybrid curation model, while KaraKeep may offer maturity advantages given its longer development history. Obsidian remains superior for users prioritizing offline-first, file-system-based workflows without server infrastructure.

FAQ

Does perstarkse/minne require OpenAI specifically? No—any OpenAI-compatible API supporting structured outputs works, including Ollama, vLLM, or commercial alternatives. Set OPENAI_BASE_URL accordingly.

What hardware resources does Minne need? Base requirements are modest (Rust + SurrealDB). Enabling reranking adds ~1.1GB disk and meaningful CPU per query.

Can I use Minne without AI features? Partially—manual entity and relationship creation works, but automatic content processing and chat require an AI provider.

Is there a mobile app? No native app, but an iOS Shortcut enables quick content capture. The HTMX frontend is mobile-responsive.

How does licensing affect commercial use? AGPL-3.0 requires source code disclosure for network use. Evaluate compatibility with your organization's open-source policy.

What's the database migration story? The README doesn't detail migrations—expect early-project volatility. Back up SurrealDB before updates.

Is there authentication beyond the demo? The read-only demo at minne.stark.pub uses separate credentials; self-hosted instances control their own auth.

Conclusion

perstarkse/minne occupies a well-defined niche: developers and technical professionals who want AI-assisted knowledge organization without surrendering structural control. Its Rust-based performance, SurrealDB graph backend, and explicit hybrid curation model distinguish it from both manual note tools and black-box automation services.

The project suits users comfortable with self-hosting infrastructure, willing to configure AI providers, and valuing data sovereignty over SaaS convenience. At 257 stars, it's early-stage—expect active evolution rather than polished stability. The maintainer's transparency about trade-offs and acknowledged alternatives builds credibility that marketing-heavy projects often lack.

For teams or individuals whose knowledge work spans formats and sources, and who've found existing tools either too manual or too opaque, Minne offers a technically credible middle path. Explore the repository, test the demo deployment, and evaluate whether its graph-powered approach fits your workflow at https://github.com/perstarkse/minne.

For related self-hosted tooling, see our coverage of [INTERNAL_LINK: SurrealDB deployment patterns] and [INTERNAL_LINK: Rust web framework comparisons].