Skip to main content
Glama
premagentic

premagentic

Official
by premagentic
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Local

PremAgentic

On-premises, for agents: the name says what it is. Governed knowledge retrieval that runs entirely inside a customer's own network. Point it at a folder of Markdown, text, PDF, Word or Excel files (the last three through first-party extensions an administrator allows), write down who may read which folders, and its people and agents get cited answers out of them, with those rules enforced before anything is retrieved.

PremAgentic decides what the model is allowed to know. Every answer is a cited passage, marked with its trust, authorship and freshness.

PremAgentic decides what the model is allowed to know. Every answer is a cited passage, marked with its trust, authorship and freshness.

the customer's folders of documents -> connector -> chunk -> embed (locally)
-> plain PostgreSQL -> access, lifecycle, trust and freshness gates
-> lexical search in PostgreSQL + exact vector search in process, fused
-> cited answers
-> a golden set that proves it works on THIS corpus

At runtime, with the default local embedding provider, PremAgentic makes no outbound call, needs no third-party API key, and sends no document anywhere on its own. An assistant that runs on a hosted model does receive the passages each search returns: PremAgentic asks where each agent's model runs, writes the answer on every audit row, and can keep a folder from every agent registered as using one (see Connect an assistant). PremAgentic calls out to nothing else unless an administrator selects the optional openai embedding provider or installs and allows an extension that does; a reminder sink that sends mail is a sample, not a built-in. With an HTTPS certificate issued by a certificate authority, the runtime's TLS stack may also fetch the certificate's revocation status (OCSP) and missing intermediate certificates, more than once; the self-signed certificate setup makes by default names no such address.

How that claim is tested, and what installing needs from the internet once, is on What PremAgentic is.

What it reads

Markdown and plain text files are read by built-in readers. PDF, Word (.docx) and Excel (.xlsx and .xlsb) files are read by three first-party extensions in this repository, extensions/pdf-reader, extensions/docx-reader and extensions/xlsx-reader. They are built with the solution and, like any extension, load only once an administrator puts each one's build output in the extensions folder and allows it with prem extensions allow. All three read text and nothing else: no link, script, macro or embedded file in a document is followed or run, and a file that crosses a limit is reported with the limit it crossed, never read in part. A PDF passage is cited by its page, a Word passage by the document's own headings, and an Excel passage by its sheet. A file a reader recognizes and will not index is counted with its reason, such as .pdf (no text layer), .doc (legacy .doc) or .docm (macro-enabled), and a file no reader claims is counted by its extension, so a folder of them does not look like an empty run. Before any reader sees a file, the run reads no more than 256 MB of it, and one file the index cannot store never stops a run.

tests/Premagentic.Benchmark times the search path on a synthetic index, and anyone can rerun it on a throwaway database; every table it prints names the machine it ran on and which of its two modes it ran in (Measuring it yourself).

Related MCP server: nacre

What it does not do

  • It does not write to the source.

  • It does not generate prose.

  • It does not recognize text in pictures or scanned pages.

The first two are explained under What it does not do; what it reads is above. Sign-in through a company directory is next in PremAgentic for Teams.

Quick start

# 1. Local stock PostgreSQL 17, on 5434 to stay clear of any PostgreSQL already on 5432 or 5433
docker compose up -d

# 2. Use the local development database for this shell. PremAgentic connects to
#    nothing unless told where; this switch names the compose instance.
$env:PREM_DEV_DATABASE = "1"    # Linux or macOS: export PREM_DEV_DATABASE=1

# 3. One time: fetch the local embedding model (all-MiniLM-L6-v2 ONNX, ~90 MB)
./scripts/download-model.ps1          # Windows; on Linux or macOS: ./scripts/download-model.sh

# 4. Create the two groups the sample corpus and golden set name
dotnet run --project src/Premagentic.Cli -- groups add hr
dotnet run --project src/Premagentic.Cli -- groups add engineering

# 5. Ingest the sample corpus. Each folder gets its own rule, so the two go in
#    separately with different audiences.
dotnet run --project src/Premagentic.Cli -- ingest ./sample-docs/open --public --prefix open
dotnet run --project src/Premagentic.Cli -- ingest ./sample-docs/hr --principals group:hr --prefix hr

# 6. Ask it something
dotnet run --project src/Premagentic.Cli -- search "how long do I have to file an expense claim" --as group:engineering

# 7. Prove the gate. HR reaches the salary bands; engineering does not.
dotnet run --project src/Premagentic.Cli -- search "band four compensation review" --as group:hr
dotnet run --project src/Premagentic.Cli -- search "band four compensation review" --as group:engineering

# 8. Run the golden set, which asserts both of those outcomes. It is the starter
#    profile's own file, so the questions are the ones the profile applies.
dotnet run --project src/Premagentic.Cli -- eval samples/profiles/starter/golden-set.json eval/report.md

# Tests (unit plus a Testcontainers end-to-end slice; Docker required)
dotnet test

The same setup is a profile. On a fresh database, prem profile apply ./samples/profiles/starter creates the two groups, registers the two sources with their rules and sets the golden set in one step; applying it again changes nothing and says so. See Profiles.

The command line explains itself, with no database configured:

prem --help                  every command, with every option explained
prem <command> --help        one command's part
prem --version               the version, with the commit it was built from
prem reminders run [--plan]  what each source owner is reminded of: stale documents and the review queue

The full list is on The prem command, which is generated from the program.

Connect an assistant

Agents connect over MCP at /mcp in the same process, with their token. They get two read-only tools, search_knowledge and get_document_section, and no tool that writes, stores or remembers anything. For an agent that only speaks stdio, Premagentic.McpServer is a bridge. How to connect one: Connect an assistant.

A person can connect their own assistant at /portal/connect: the agent it makes acts as that person and nothing more, its token is shown once beside the configuration for the assistant they use, and they can revoke it there. An administrator bounds how many each person may have with agents.self_service_max (0 turns it off) and can reword any configuration with connect.snippets. An administrator can give every assistant the deployment's own instructions with prem settings set mcp.instructions "<text>": a client that reads what a server sends at connect receives them, they are served as the resource premagentic://instructions, and the connect page shows them for pasting into AGENTS.md, CLAUDE.md or a client's own instructions.

See it

Folder rules decide who may read what. The first entry that names the caller decides, and no match is a deny.

Folder rules decide who may read what. The first entry that names the caller decides, and no match is a deny.

Ask why for any person and any document, and PremAgentic shows the rule and every gate. Here a contractor is held back from the greenhouse notes.

Ask why for any person and any document, and PremAgentic shows the rule and every gate. Here a contractor is held back from the greenhouse notes.

Every agent carries where its model runs. Move one to a hosted model and the folders kept from hosted-model agents close to it on its next call.

Every agent carries where its model runs. Move one to a hosted model and the folders kept from hosted-model agents close to it on its next call.

The audit shows who asked, under which policy, where the model ran and every passage served, filtered here to what went to hosted-model agents.

The audit shows who asked, under which policy, where the model ran and every passage served, filtered here to what went to hosted-model agents.

Documentation

The index of all of them, with what each covers, is docs/README.md.

Get involved

To contribute see CONTRIBUTING.md; your first pull request asks you to sign the contributor license agreement, once. Questions and ideas go to the repository's Discussions, a first change starts with an issue labeled good first issue, and what comes next is on Roadmap.

Support

Support comes with PremAgentic for Teams, from Agave Information Solutions, LLC: help installing and upgrading, sizing the hardware, mapping an organization's directory and permissions into PremAgentic, and answers from the maintainers. Write to premagentic@agaveis.com.

Questions go to the repository's Discussions and bugs to its issues, where the maintainers read and triage them. Security reports are always answered; see SECURITY.md.

License

PremAgentic is free software under the GNU Affero General Public License, version 3 only (AGPL-3.0-only). See LICENSE and NOTICE. Dependency and model licenses are listed in THIRD-PARTY-NOTICES.md.

Agave Information Solutions, LLC also offers PremAgentic under a commercial license, for building it into a closed product, or running a changed copy for its users without offering them its source. Write to premagentic@agaveis.com.

PremAgentic for Teams is what an organization adds to run PremAgentic for many people. It carries directory group mapping, and audit retention and export. Next in it: sign-in through Microsoft, Google or another OIDC provider, with group sync; connectors that read a source's own permissions, for SharePoint, OneDrive and Windows file shares; the administration API; and a signed installer. Support comes with it.

The add-on installs as one extension on the same extension host, allowed by hash like any other, and it is free for a deployment of up to 10 users. Customers can read the add-on's source.

The PremAgentic name belongs to Agave Information Solutions, LLC and is not licensed with the code.

To report a vulnerability see SECURITY.md; to contribute see CONTRIBUTING.md.

Available Tools

2 tools
get_document_sectionA
Read-only

Fetch the full text of a section cited by search_knowledge, by document path plus heading. Use after a search hit when the excerpt is not enough context. Omit heading for the whole document. The same rules as search decide what this agent may read. Read-only. Every result says what it is. trust: how far the passage has been confirmed, one of unverified, machine-confirmed or human-reviewed. authorship: who wrote it, human, machine, or unknown for an ordinary file that does not say. stale: yes when the passage is past the date its author said it goes stale. concept: its concept id when it comes from a knowledge bundle, otherwise '-'. Treat a machine-written, unverified or stale passage as a lead to check, not as a settled fact.

ParametersJSON Schema
NameRequiredDescriptionDefault
pathYesDocument path exactly as cited, for example 'handbook/travel.md'.
headingNoHeading (or 'H1 > H2' heading path) from the citation, matched case-insensitively. Omit for the whole document.
includeHistoricalNoSet true ONLY when the citation came from a search with includeHistorical.

TDQS

A4.6/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already cover the safety profile (readOnlyHint=true, destructiveHint=false), yet the description adds real value: the permission model ('same rules as search decide what this agent may read'), the meaning of the trust/authorship/stale/concept result fields, and interpretive guidance ('treat a machine-written, unverified or stale passage as a lead to check'). That is substantial behavioral context beyond the annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with purpose and usage before the longer result-field explanation, and the sentence order is logical. The field-by-field result enumeration is slightly verbose but earns its place because there is no output schema to document the return values.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description carries the burden of explaining return values and does so (trust, authorship, stale, concept), while also covering permissions and the whole-document case. Nothing an agent needs to call or interpret this tool correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so path, heading and includeHistorical are already documented in the schema. The description only restates path/heading behavior ('Omit heading for the whole document') and adds nothing new about includeHistorical or matching semantics, so the baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb (fetch) and resource (full text of a section) plus the exact addressing scheme (document path plus heading). It explicitly ties itself to the sibling search_knowledge as the source of the citation, so an agent can distinguish the two without opening either schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives an explicit trigger ('Use after a search hit when the excerpt is not enough context') and the sibling it complements (search_knowledge). It also states the whole-document variant ('Omit heading for the whole document'), leaving no routing ambiguity.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

search_knowledgeA
Read-only

Search this organization's own documents. Returns cited evidence: path, heading and content, ranked by hybrid lexical and semantic relevance. Only documents this agent is authorized to read are eligible, and machine-written content no person has reviewed, and stale content, are left out unless this deployment allows them to agents. Superseded, archived, draft and expired material is excluded unless includeHistorical is set. Read-only. Every result says what it is. trust: how far the passage has been confirmed, one of unverified, machine-confirmed or human-reviewed. authorship: who wrote it, human, machine, or unknown for an ordinary file that does not say. stale: yes when the passage is past the date its author said it goes stale. concept: its concept id when it comes from a knowledge bundle, otherwise '-'. Treat a machine-written, unverified or stale passage as a lead to check, not as a settled fact.

ParametersJSON Schema
NameRequiredDescriptionDefault
topKNoNumber of results to return (1-10).
queryYesThe question or search query.
includeHistoricalNoSet true ONLY when the user explicitly wants historical, superseded or archived content.

TDQS

A4.4/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations only cover read-only/no-destruction, but the description adds substantial context beyond them: authorization filtering ("only documents this agent is authorized to read"), exclusion of unreviewed machine content and stale material, the includeHistorical override, and an interpretation caveat ("treat a machine-written, unverified or stale passage as a lead to check").

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loads purpose and result shape, then the exclusion rules, then the field glossary — a logical order. It is dense and long, and "Every result says what it is." is near-filler filler, but with no output schema the field enumeration largely earns its space.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description compensates by enumerating and defining the result fields (trust, authorship, stale, concept). Combined with the authorization, staleness and historical-exclusion rules, an agent has everything needed to call it and interpret what comes back.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so topK, query and includeHistorical are already documented at the schema level, and the description adds little about their syntax. The long trust/authorship/stale/concept explanation describes result fields rather than input parameters, so this is a baseline 3.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ("Search this organization's own documents") plus the return shape ("cited evidence: path, heading and content, ranked by hybrid lexical and semantic relevance"). That scope is clearly distinct from the sibling get_document_section, which fetches a known section rather than discovering passages.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives real conditional guidance: historical/superseded/archived/draft/expired material is excluded "unless includeHistorical is set," and machine-written or stale passages are framed as leads to verify rather than facts. It never names get_document_section or states when to prefer a direct fetch over a search, so routing against the sibling is left implicit.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 2 tool updatesv0.1.0
    • First observedget_document_section
    • First observedsearch_knowledge
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A4.5/5.0

Scored across 2 tools

Disambiguation5/5

The two tools are cleanly split between search-and-rank (search_knowledge) and fetch-full-text (get_document_section), and the second explicitly states it is used after a search hit. There is no realistic way to confuse them.

Naming Consistency5/5

Both names use a consistent snake_case verb_noun pattern (search_knowledge, get_document_section) and the verbs precisely describe the action. No mixed conventions.

Tool Count4/5

Two tools is on the thin side, but the server has a deliberately narrow, read-only retrieval purpose and each tool earns its place as a distinct step in a search-then-read workflow. It is slightly under-provisioned rather than over-scoped.

Completeness4/5

The search/retrieve pair covers the core read path for cited knowledge, including trust, authorship, staleness and concept metadata plus historical inclusion. Minor gaps like listing or browsing documents without a query exist, but agents can work around them.

Maintenance

ActivityMaintained
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • rag-retriever-mcp

    code-lawyer
    F
    license
    A
    quality
    D
    maintenance
    A local-first document retrieval engine that mounts as an MCP tool for agents to index files, search for relevant passages, and let the agent's own LLM answer.
    4
    -

  • nacre

    nacre-work
    A
    license
    Not graded
    quality
    A
    maintenance
    Provides a self-hosted knowledge index with document-level permissions, enabling AI agents to retrieve exactly the documents they are authorized to see via MCP. Supports OAuth 2.1, custom embedding models, and runs inside your network.
    76 npm
    1
    Apache 2.0

  • nexus-mcp

    jasleen27
    A
    license
    Not graded
    quality
    B
    maintenance
    An enterprise-grade MCP gateway and security router that gives AI agents secure, observable access to internal corporate knowledge through hybrid vector+BM25 retrieval, RBAC, and prompt injection protection.
    MIT