Capabilities

Feature guide

Every capability explained for both decision-makers and engineers - what it does, how to enable it, an example, the benefits, and the trade-offs.

Feature guide

Meivo is a memory framework for private enterprise AI. It is not a foundation model and it is not tied to one chat provider. Applications and agents use it to retain knowledge, retrieve it with evidence, understand how it changed, and reuse it with a customer-approved model.

The core engine is available through REST and MCP. The packaged enterprise product adds a supporting gateway and control panel for identity, permission resolution, connectors, guardrails, audit, provider configuration, and operations.

Remember, recall, and cited context

For the business. An assistant can retain durable decisions, policies, preferences, and outcomes across sessions without sending the underlying memory estate to a public memory service.

How it works. POST /v1/memories stores text asynchronously. Search can return ranked chunks and facts (mode: "recall") or assemble a token-budgeted context block with citations (mode: "context"). MCP offers the equivalent remember, recall, and get_context tools.

Benefits.

One memory layer can serve local/open-source models and approved hosted models.
Context carries provenance and citations rather than an untraceable text dump.
A token budget bounds how much retrieved material enters the downstream prompt.

Trade-offs. Ingestion is asynchronous, so a newly accepted memory can take a short time to become searchable. Retrieval quality depends on the corpus, chunking, embedding model, and query shape; validate it with representative customer data.

Hybrid retrieval

For the business. Meivo does more than nearest-neighbour vector search. It combines meaning, exact terms, known facts, and optional graph relationships so differently worded questions can still find the right evidence.

How it works. Semantic similarity, BM25/full-text, and fact results are fused with reciprocal-rank fusion and a recency signal. Optional usefulness weighting, lexical reranking, point-in-time fact filtering, and graph expansion refine the candidate set.

Enable. Hybrid retrieval is the default behavior of POST /v1/search and the recall and get_context MCP tools.

curl -s http://127.0.0.1:7437/v1/search \
  -H 'Content-Type: application/json' \
  -d '{"query":"what did we promise Acme about uptime?","mode":"recall","k":8}'

Trade-offs. More retrieval lanes do more work than one lookup. Meivo does not promise a universal latency figure: measure p50/p95/p99 on the target database, corpus size, ACL shape, and hardware.

Reranking

An optional lexical second pass reorders fused candidates before truncation. Set GM_RERANK=lexical, or leave the default none.

The built-in reranker is a lightweight lexical-overlap implementation. It can improve ordering for term-heavy queries without an external model, but it is not a cross-encoder and should not be described as one.

Bi-temporal knowledge graph

For the business. Meivo can answer both "what is true now?" and "what was believed at that point in time?" without overwriting every earlier value.

How it works. Extracted facts become graph edges with two time axes:

event time — when the relationship was valid in the world;
system time — when Meivo learned or retired that relationship.

A conflicting fact can supersede a current edge while retaining its history. Query the history with GET /v1/timeline or the timeline MCP tool. Pass an RFC 3339 as_of timestamp to recall-mode search for point-in-time facts.

Trade-offs. Fact extraction and automatic graph population need an LLM configured for the engine. History consumes more storage than a latest-value-only table, and an extracted fact should still be treated as model-produced evidence that may require human review.

Graph-aware retrieval

Set GM_GRAPH_EXPAND_HOPS=1 to let retrieval include facts connected to entities in the initial results. This is off by default at 0.

One hop is a sensible starting point. Additional hops broaden recall but can reduce precision and increase query work. The traversal is retrieval expansion, not a claim that the system independently reasons over every relationship.

Episodes

Episodes group related events under a named project, incident, case, meeting, or other narrative. Events are returned in time order so an application can reconstruct what happened rather than relying only on a compressed summary.

Use:

REST: POST /v1/episodes, POST /v1/episodes/{id}/events, GET /v1/episodes/{id}, and GET /v1/episodes;
MCP: create_episode, add_episode_event, get_episode, and list_episodes.

Episodes are deliberate application structure. Meivo does not automatically decide which events belong together.

Linked memory cards

A memory card is an atomic titled note with a summary, keywords, and tags. New cards link to related cards, creating a navigable knowledge web alongside raw documents and graph facts.

Use POST /v1/cards or the create_card, get_card, and list_cards MCP tools. Keyword/tag linking is the default. Set GM_CARDS_SEMANTIC_LINKING=true to embed cards and link them by semantic similarity.

Semantic linking can connect differently worded cards, but it adds embedding work and can create weak associations. Applications should expose the link strength and keep human review available for important knowledge.

Reflection

When an engine LLM is configured, prospective reflection can summarize each ingested document into a reusable memory card in the background. The feature is enabled by default but is a no-op when GM_LLM=none.

Turn it off with:

GM_REFLECTION=false gm-server serve
# or
gm-server serve --disable-reflection

Generated summaries are model output, not a replacement for the source. Keep source citations available and evaluate summaries for the intended domain.

Usefulness feedback

Applications can tell Meivo which retrieved chunks were actually used by posting their ids to POST /v1/feedback. The engine raises those chunks' usefulness score, and the retrieval prior can gently lift them in later results.

This is explicit feedback, not automatic proof that a returned chunk was correct. The current endpoint raises identified chunks; it does not infer user intent or automatically decay every unreported chunk. Disable its ranking effect with GM_USEFULNESS=false.

Trust and memory-poisoning defenses

Every result carries a trust score derived from provenance. The default trust policy also detects a set of prompt-injection-like patterns:

suspicious content is down-ranked;
it is stored so operators can investigate it;
when trust gating is enabled, it is not promoted into the structured fact graph;
retrieved content is returned as data for the consuming application.

Trust gating is enabled by default and can be disabled with GM_TRUST=false or gm-server serve --disable-trust.

This is defense in depth, not a guarantee that all malicious or incorrect text will be detected. Apply identity, source allow-lists, ACLs, model guardrails, and human review appropriate to the risk.

Storage choices

The main document/vector store supports:

Stage	Main store
Local development and smaller installations	SQLite
Server and managed-database deployments	Postgres with pgvector

Set GM_DB to a SQLite path or a postgres:///postgresql:// URL.

GM_GRAPH_BACKEND can keep the bi-temporal graph in the main store (store) or point it at a separate SQLite, Postgres, or MySQL database. MySQL support is for that separate graph role only. There is no current operator command that migrates a graph between backends; plan and test any database migration with the relevant database tooling.

REST and MCP interfaces

gm-server serve exposes versioned REST routes under /v1, OpenAPI at /v1/openapi.json, and streamable HTTP MCP at /mcp.

gm-server mcp runs stdio MCP directly against the configured data directory. The MCP server exposes 13 tools:

remember
recall
get_context
get_profile
timeline
create_episode
add_episode_event
get_episode
list_episodes
create_card
get_card
list_cards
forget

There is no separate Meivo client CLI in the current product. The gm-server binary has operational commands for serving REST/MCP, stdio MCP, container health checks, and embedding-model warmup. Use REST or MCP for memory operations.

Supporting enterprise gateway and control panel

The packaged product places a built-in gateway and web UI around the memory framework. They currently provide:

local users and LDAP/AD integration, roles, and permission-aware search;
local-folder, S3, Google Cloud Storage, Azure Blob, and IMAP connectors;
scheduled/delta sync, run history, rollback, purge, and deletion safety;
parsing for supported text, HTML, CSV, JSON, PDF, DOCX, XLSX, PPTX, and email content (scanned documents still need an OCR step);
rule-based and optional LLM guardrails;
encrypted provider configuration and an application-level local-provider gate;
tamper-evident audit history, checkpoints, export, and operational status.

Calling the engine directly does not automatically apply those gateway controls. See Architecture & integration for the boundary.

Deployment and resource posture

Single workspace: one packaged installation represents one customer workspace today. Engine space values are namespaces, not direct-API authorisation boundaries.
Offline-ready: preload the embedding model and use local model endpoints. A sealed environment additionally requires customer network controls.
Bounded ingestion memory: the repository includes a regression test that ingests 1,000 synthetic documents of about 50 KB each through the real local embed/store path and asserts peak RSS below 1 GB. That is a documented test envelope, not a promise that every model, parser, connector, or workload uses the same amount of memory.

Next: Local quickstart, Server command reference, MCP reference, and Data lifecycle.