Runar
Runar is a self-hosted MCP-native context server that gives AI agents durable storage and retrieval of project knowledge.
Save and manage memories: propose, read, search, and archive canonical Markdown/PostgreSQL memories.
Persist structured session notes: write and list sessions with idempotency and resource URIs.
Build bounded context packs: assemble memories, skills, personas, relations, and sources under item, character, and token budgets.
Run safe analytics: execute closed, deterministic aggregates over memory metadata without arbitrary SQL.
Manage declarative skills: list, get, validate, enable, and disable skill versions.
Manage persona packs: list and validate persona packs.
Search with PostgreSQL full-text search, metadata filters, status/type filters, and bounded relation depth.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Runar search my memories for the database migration decision"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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 clientWhat 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 stdioThe 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-httpThe 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/readyConnect 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 |
|
Sessions |
|
Context |
|
Skills |
|
Persona |
|
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 --jsonPostgreSQL 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 integrationRun ./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 toolscontext.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
Scored across 15 tools
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'.
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.
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.
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
Related MCP Connectors
Private-by-default, local-first memory/context/task orchestrator for MCP apps and agents.
Hosted memory for AI agents over MCP. One memory shared by all your agents.
Persistent memory, knowledge graph, task management and more for AI agents via MCP.
Cross-tool persistent memory and context for AI assistants over MCP.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables AI agents to maintain and query project memory independently of the underlying model, with versioned, auditable storage and multi-stage retrieval through a single MCP gateway.MIT
- AlicenseNot gradedqualityCmaintenanceEnables 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
- AlicenseNot gradedqualityCmaintenanceProvides 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.2MIT
- AlicenseNot gradedqualityBmaintenanceProvides persistent, searchable memory across coding projects and machines, letting agents record and retrieve projects, reusable assets, sessions, decisions, commits, and handoffs via MCP.3Apache 2.0