AI configuration parameters

Prompt templates and usage limits

Property	Type	Description
ai.system.prompt.template	String	System prompt prepended to every general AI chat / MCP conversation. Supports the placeholders `{userId}`, `{userName}` and `{token}`, replaced at runtime with the current user and their authentication token. The built-in default explains to the model how OpenKM node references (`@[name](uuid:…
ai.rag.prompt.template	String	Prompt used for RAG (Retrieval-Augmented Generation) answers, i.e. the Chatbot and Smart Search over indexed documents. Must contain the placeholders `{question_answer_context}` (where the retrieved chunks are injected) and `{query}` (the user question). The built-in default restricts the model to answering only from the provided context and in the user’s language.
ai.usage.retention.days	Integer	Number of days that AI usage/cost accounting rows (`OKM_AI_USAGE`, one per provider call) are kept before the Purge AI Usage Crontab task deletes them. 365
ai.usage.budget.warn.cost	Integer	Estimated-cost threshold for the current calendar month. When the accumulated estimated cost crosses this value, OpenKM raises a warning notification but AI calls keep working. `0` disables the warning. The cost is an estimate derived from admin-entered pricing (`OKM_AI_PRICING`), USD by convention. 0
ai.usage.budget.limit.cost	Integer	Hard estimated-cost limit for the current calendar month. Once the accumulated estimated cost crosses this value, further AI calls are blocked until the next month. `0` disables the limit. Same cost-estimation caveat as ai.usage.budget.warn.cost. 0

AI Provider Configuration

The following parameters define which AI model to use for chat and embedding operations.

Property	Type	Description
spring.ai.model.chat	String	Specifies the chat model provider. openai
spring.ai.model.embedding	String	Specifies the embedding model provider. openai
spring.ai.openai.api-key	String	The API key for authentication. API key
spring.ai.openai.chat.options.model	String	The specific model version to use. gpt-5-mini
spring.ai.openai.chat.options.temperature	Float	Controls randomness in responses (0.0 to 1.0). Lower values make the output more focused and deterministic. 1

MCP Server Configuration

The Model Context Protocol (MCP) Server allows external applications to interact with OpenKM’s core functionalities.

Property	Type	Description
spring.ai.mcp.server.enabled	Boolean	Enables or disables the MCP server. Set to `true` to activate the MCP server and restart the service. false
spring.ai.mcp.server.instructions	String	Instructions and description for the MCP server. This server provides basic OpenKM application information and tools. OpenKM is a document management system that allows you to manage your documents. You can use this server to interact with OpenKM’s core functionalities through the MCP protocol.
spring.ai.mcp.server.request-timeout	Duration	Request timeout duration. 60s
okm.mcp.security.allowed.ips	String	Restricts which IP addresses can access the MCP service. Use * to allow all IP addresses, or specify a specific IP address (e.g., 10.0.0.50) to restrict access. *

MCP Client Configuration

OpenKM includes an MCP (Model Context Protocol) client that allows it to connect to external MCP servers.

Property	Type	Description
spring.ai.mcp.client.enabled	Boolean	Spring AI MCP client auto-configuration. Must always be `false`. false
okm.mcp.manual.client.enabled	Boolean	Enables or disables the manual MCP client configuration. false
okm.mcp.manual.connections.server1.url	String	URL of the first MCP server to connect to. http://localhost:8080
okm.mcp.manual.connections.server1.sse-endpoint	String	Server-Sent Events (SSE) endpoint for the MCP server. /openkm/sse
okm.mcp.manual.connections.server1.token	String	Authentication token for OpenKM. We recommend generating a token with a validity period of one year or more.

RAG (Retrieval-Augmented Generation) Configuration

RAG enhances AI responses by retrieving relevant information from a vector database. OpenKM supports different vector store backends.

MariaDB example configuration

Property	Value
spring.ai.model.embedding	openai
spring.ai.vectorstore.mariadb.initialize-schema	true
spring.ai.vectorstore.type	mariadb

PostgreSQL example configuration

Property	Value
spring.ai.model.embedding	openai
spring.ai.vectorstore.pgvector.initialize-schema	true
spring.ai.vectorstore.type	pgvector
spring.ai.vectorstore.similarity.threshold	0.7

Retrieval tuning parameters

These parameters control how chunks are retrieved and ranked once a question is asked, independently of which vector store backend is used.

Property	Type	Description
spring.ai.vectorstore.similarity.threshold	Float	Minimum cosine similarity (0.0 to 1.0) that a chunk must reach to be considered a match for a chatbot query. OpenAI-family embedding models compress similarity into a narrow band — even relevant matches often score 0.3 to 0.6 — so keep this low and tune per embedding provider. 0.3
spring.ai.vectorstore.sources.similarity.threshold	Float	Minimum cosine similarity (0.0 to 1.0) for a chunk’s document to be listed as a “source” in the chatbot response. Deliberately stricter than similarity.threshold above: a weak-but-useful chunk can still be included in the context sent to the model without being presented to the end user as an authoritative citation. The same per-embedding-provider tuning caveat applies to similarity.threshold. 0.5
spring.ai.vectorstore.sources.citation.enabled	Boolean	When enabled, an extra chat model call checks which of the sources that cleared sources.similarity.threshold the model actually cited in its answer, and narrows the “sources” list down to just those. This is needed for corpora where cosine similarity can’t discriminate between candidates at all — same-template legal/administrative documents, for example, can all score within a very narrow band regardless of relevance, well above any workable threshold. It costs one extra chat model call per query (latency and tokens). Validated against a real corpus where sources.similarity.threshold alone left 20 unrelated candidates within a 0.008 similarity band; citation extraction correctly narrowed that down to the single source the answer actually relied on. true
spring.ai.vectorstore.fetch.multiplier	Integer	Chunks are over-fetched by this factor (multiplied by top.k) before the final permission check runs, and also sizes the lexical candidate pool used for rank fusion when hybrid search is enabled. With acl-filter.enabled on by default, the vector store query itself already returns only accessible chunks, so this is now mostly a backstop for stale or not-yet-re-indexed ACL metadata rather than the main compensation mechanism. 2
spring.ai.vectorstore.acl-filter.enabled	Boolean	Filters by access permissions (requesting user or any of their roles with READ access) directly in the vector store query, instead of only discarding non-accessible candidates after fetching them. This keeps relevant results a user can read from being pushed out of the top.k window by results they can’t read. The final permission check still runs regardless, as defense in depth. Documents indexed before this property existed have no ACL metadata and stay invisible to the filter until re-indexed. true
spring.ai.vectorstore.top.k	Integer	Maximum number of chunks, after the permission filter, used as context to answer a chatbot query. 5
spring.ai.vectorstore.chunk.size	Integer	Target chunk size, in tokens, when feeding a document into the RAG vector store. Chunks are packed by paragraph up to this budget instead of being cut off mid-text. 800
spring.ai.vectorstore.chunk.overlap.paragraphs	Integer	Number of trailing paragraphs from a chunk that are carried over into the next one, so a chunk boundary doesn’t strip context from what follows it. Set to 0 to disable overlap. 1
spring.ai.vectorstore.hybrid.enabled	Boolean	Combines the vector similarity ranking with a lexical (keyword) ranking over the same documents’ extracted text, so exact terms, codes or acronyms that the embedding model doesn’t match well can still surface. When disabled, retrieval is vector-only. false
spring.ai.vectorstore.hybrid.rrf-k	Integer	Reciprocal Rank Fusion constant used to combine the vector and lexical rankings when hybrid search is enabled. Higher values flatten the influence of rank differences between the two rankings. 60

Indexing Documents into the RAG

Enabling the RAG through the configuration file is a necessary but not sufficient step. Simply activating it does not cause documents to be automatically vectorized or made available to the Smart Search or Chatbot features. Users must explicitly define which documents, or which areas of the repository, should be indexed in the vector store.

This selective indexing approach is intentional: indexing the entire repository is technically possible, but is generally not recommended, as it may introduce noise into AI responses and increase both storage and processing costs.

Configuring the Feed RAG Automation Rule

OpenKM ships with a built-in automation rule named Feed RAG, designed precisely for this purpose. This rule must be reviewed and activated through the Automation module and works as follows:

Event: The rule is triggered by the Document text extraction event, at the post phase, that is, after the text has been successfully extracted from a document.
Validation: A PathContains condition determines which documents qualify for indexing. Typically, this is configured with one or more repository folder paths so that only documents stored within those folders are vectorized.
Action: The FeedRAG action performs the actual vectorization and stores the document embeddings in the configured vector store.

The most common configuration involves targeting one or several specific folders in the repository, ensuring that only the relevant content is made available to the AI features.