Skip to main content
Glama

Runar

Runar is a self-hosted, MCP-native context server for AI agents. It gives MCP clients a durable place to save project knowledge and retrieve only the context that is useful for the current task.

Runar does not call an LLM, proxy prompts, select models, or depend on a model provider. Your MCP client remains in control of orchestration and inference.

AI client ── MCP ──> Runar ──> PostgreSQL + Markdown
    │                   │
    │<── useful context─┘
    │
    └── model request ──> provider chosen by the client

What you can do with Runar

  • Save decisions, facts, constraints, preferences, and other reusable memories.

  • Search with PostgreSQL full-text search, metadata filters, and bounded relations.

  • Persist structured session notes without uploading complete chat transcripts.

  • Publish reusable skills and persona packs as declarative Markdown/YAML.

  • Build compact context packs with predictable item, character, and token-estimate budgets.

  • Run a fixed set of safe analytics without exposing arbitrary SQL.

  • Serve local clients over stdio or remote clients over Streamable HTTP.

Search results are intentionally concise. Clients can fetch full content later through MCP resources such as memory://<id> and session://<id>.

Related MCP server: MCP Shared Memory Hub

Quick start

You need Python 3.12 or 3.13, uv, Docker, and Docker Compose.

cp .env.example .env
uv sync
docker compose up -d postgres
uv run alembic upgrade head
uv run runar-mcp --transport stdio

The final command starts the local MCP server. A client configuration typically launches the same command from this repository:

{
  "command": "uv",
  "args": ["run", "runar-mcp", "--transport", "stdio"],
  "cwd": "/absolute/path/to/runar-mcp"
}

Exact client configuration keys vary by MCP host. Runar writes logs to stderr so stdout remains a clean MCP protocol stream.

To use Streamable HTTP during local development:

uv run runar-mcp --transport streamable-http

The endpoint is http://127.0.0.1:8080/mcp. Remote staging and production deployments require OAuth configuration and HTTPS; see the deployment guide.

Run everything with Docker

The Compose stack builds Runar, starts PostgreSQL, applies Alembic migrations, and runs both the MCP endpoint and administrative health API:

docker compose up --build -d
docker compose ps
curl --fail http://127.0.0.1:8000/health/ready

Connect MCP clients to http://127.0.0.1:8080/mcp. PostgreSQL data and canonical Runar documents are kept in named volumes. Stop the services with docker compose down; this preserves the data. See the deployment guide before exposing the endpoint outside a trusted development machine.

Main MCP capabilities

Area

Tools

Memory

memory.propose, memory.read, memory.search, memory.archive

Sessions

session.write, session.list

Context

context.build, memory.analyze

Skills

skill.list, skill.get, skill.validate, skill.enable, skill.disable

Persona

persona.list, persona.validate

Full payloads, filters, permissions, resources, and error behavior are documented in the MCP reference.

How data is stored

Runar uses two coordinated stores:

  • PostgreSQL holds metadata, revisions, search projections, relations, sessions, jobs, and audit events.

  • Markdown files hold canonical memory and session documents.

Both are required for a complete backup. Writes are recoverable across the two stores, and uv run runar-cli reconcile reports inconsistencies without deleting data automatically.

Development checks

uv run ruff check .
uv run ruff format --check .
uv run pyright
uv run pytest
uv run runar-eval --json

PostgreSQL integration tests use a database selected explicitly through TEST_DATABASE_URL:

TEST_DATABASE_URL=postgresql+psycopg://runar:runar@localhost:5432/runar_test \
  uv run pytest -m integration

Run ./scripts/mcp_inspector_smoke.sh for the MCP Inspector compatibility check.

Documentation

Start with the documentation guide, or go directly to architecture, the MCP reference, deployment, security, backup/restore, and migrations.

Current limits

Runar v1 uses deterministic lexical retrieval; semantic retrieval is not implemented. Relations are bounded rather than recursively traversed. The local Markdown adapter is the implemented canonical store, while the S3 setting is reserved for a future adapter. The built-in remote rate limiter is process-local, so multi-instance deployments need shared ingress rate limiting.

Runar remains independent of whichever LLM, provider, or model router an MCP host chooses.

Available Tools

15 tools
context.buildC

Build a bounded secondary-context pack; the MCP host decides how to use it.

Inputs: debug, query, user_id, max_items, +15 more. Returns: skills, persona, sources, memories, +2 more

memory.analyzeC

Run a closed deterministic aggregate; arbitrary SQL is never accepted.

Inputs: intent (required), field, limit, value, +11 more. Returns: rows, count, route, intent

memory.archiveB

Archive a memory while preserving canonical documents and revision history.

Inputs: memory_id (required). Returns: id, status

memory.proposeD

Propose a canonical memory backed by Markdown and PostgreSQL metadata.

Inputs: title (required), content (required), memory_type (required), user_id, +8 more. Returns: id, scope, title, status, +3 more

memory.readA

Read a memory from canonical storage by its identifier.

Inputs: memory_id (required). Returns: id, scope, title, status, +3 more

memory.searchB

Find concise secondary-context candidates without loading full documents.

Inputs: text, exact, limit, user_id, +12 more. Returns: count, modes, results

persona.listA

List valid persona packs while leaving their content in lazy resources.

Inputs: no named parameters. Returns: count, results

persona.validateC

Return actionable diagnostics for declarative persona packs.

Inputs: persona_id. Returns: valid, results

session.listA

List concise session metadata; read full entries through the resource URI.

Inputs: limit, user_id, tenant_id, project_id, +2 more. Returns: count, results

session.writeD

Persist structured context supplied explicitly by the MCP host.

Inputs: client (required), entries (required), user_id, ended_at, +6 more. Returns: id, client, ended_at, started_at, +2 more

skill.disableC

Disable a validated skill version through the persistent status overlay.

Inputs: skill_id (required), version. Returns: id, name, status, version, +6 more

skill.enableC

Enable a validated skill version through the persistent status overlay.

Inputs: skill_id (required), version. Returns: id, name, status, version, +6 more

skill.getC

Resolve exact or latest skill metadata; instructions remain a lazy resource.

Inputs: skill_id (required), version. Returns: id, name, status, version, +6 more

skill.listA

List validated declarative skills without loading their full instructions.

Inputs: all_versions, include_disabled. Returns: count, results

skill.validateC

Return actionable diagnostics for declarative skill packages.

Inputs: skill_id. Returns: valid, results

Tool Schema Changelog

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

Loading tool schema changelog…

    TDQS

    B3.2/5.0

    Scored across 15 tools

    Disambiguation5/5

    Each tool is scoped to a distinct resource namespace and action, so memory, session, skill, persona, and context operations are easy to separate. The only conceptually adjacent pair, memory.search and context.build, is clearly distinguished by 'find candidates' versus 'build pack'.

    Naming Consistency5/5

    All tools follow a consistent lowercase namespace.action convention with predictable verbs like list, get, validate, enable, disable, read, and write. There is no mixing of separator styles or naming patterns, so agents can infer related tools across resource types.

    Tool Count5/5

    Fifteen tools is at the upper edge of the ideal range, but each tool maps to a necessary operation across the server's five related domains. There is no obvious redundancy or dead weight in the set.

    Completeness4/5

    Core workflows are covered: memories can be proposed, read, searched, archived, and analyzed; skills can be listed, inspected, validated, and toggled; sessions and contexts have write/build paths. Minor gaps exist—such as no direct memory update or persona activation tool—but archive-and-repropose and resource URI patterns provide reasonable workarounds.

    Maintenance

    ActivitySlowing
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables multiple MCP-compatible AI clients to share persistent, versioned project knowledge across sessions with conflict-safe updates, provenance, hybrid retrieval, stale-memory handling, and context-budgeted recall.
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Provides persistent, multi-project memory for AI agents via MCP, enabling them to store and retrieve tasks, decisions, errors, checkpoints, and documentation while keeping context isolated by project.
      2
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Provides persistent, searchable memory across coding projects and machines, letting agents record and retrieve projects, reusable assets, sessions, decisions, commits, and handoffs via MCP.
      3
      Apache 2.0