MoContext Human Guide

Use this page to help an AI client remember and use MoContext. Copy the short bootstrap into persistent custom instructions, or copy the longer session prompt into a single chat when you want to steer that session.

• Custom instructions: paste once into Codex or another AI client settings box.
• Session prompt: paste into a chat when custom instructions are not configured or you want a stronger reminder.
• Appendix: read the technical sections below when you want to understand how MoContext works.

Appendix: how MoContext works

Audience: Technical users and admins. Covers architecture, data flows, HTTP endpoints, and MCP tools. For internal codebase detail (service layer, file map, WinForms threading, startup sequence) see MoContext_Codebase.html.

1. What Is MoContext?

MoContext is a single-executable, local-loopback server that gives AI agents (and developers) grounded source retrieval from the MoSearch full-text index, a lightweight activity journal, explicit SaveContext/LoadContext digests, durable indexed memory files, and a recent working-set signal from MoSearch UriHistory. It exposes the same surface over two parallel entry points — a classic REST HTTP API and a Model Context Protocol (MCP) endpoint — and ships a WinForms system-tray dashboard for monitoring.

2. System Overview

MoContext sits between AI clients and the local filesystem. MoSearch's indexer is a fully separate process that writes MoSl.db; MoContext only reads it. The MoSearch Search UI is the original user-facing query tool — it reads the same MoSl.db and opens source files directly; HTTP and MCP are two new avenues into that same underlying index.

3. HTTP vs MCP — Parallel Entry Points

This is the most important structural point. MCP is not layered on top of HTTP. Both entry points call the same service singletons through ASP.NET Core DI. The MCP SDK registers a handler at /mcp alongside the /v1/ route handlers — they are peers, not stacked.

4. Database Architecture

MoContext works with two SQLite databases. They typically live in the same %LOCALAPPDATA%\Meauxsoft\Mo-Search<ver>\ AppData folder but are structurally independent. MoSearch owns and writes MoSl.db; MoContext only reads it. MoContext owns and reads/writes MoContext.db.

5. HTTP Endpoints GET/POST /v1/...

Read (no auth required)

  55:     private readonly JwtSecurityTokenHandler _handler;
  56:     private TokenValidationParameters _params;
› 57:     public bool ValidateJwtToken(string token) {
  58:         var r = _handler.ValidateToken(token, _params, out _);
  59:         return r.IsValid;
  60:     }

  81:     [HttpPost("login")]
  82:     public IActionResult Login([FromBody] LoginRequest req) {
› 83:         if (!_auth.ValidateJwtToken(req.Token)) return Unauthorized();
  84:         return Ok(GenerateSession(req));
  85:     }

  53:     private TokenValidationParameters _params;
  54:
  55:     public AuthService(IOptions<AuthOptions> opts) {
  56:         _params = BuildParams(opts.Value);
› 57:         _handler = new JwtSecurityTokenHandler();
  58:     }
  59:
  60:     public bool ValidateJwtToken(string token) {
  61:         return _handler.ValidateToken(token, _params, out _).IsValid;

Write (optional Bearer auth)

Every /v1/ request records an api_call event (fire-and-forget). Every /mcp request records an mcp_transport event. Individual MCP tools also record mcp_tool_call events.

6. MCP Tools (auto-discovered from MoContextMcpTools.cs)

MoContext exposes 15 MCP tools after the 2026-07 redesign (tool merges and deletions). Orientation and context-file tools: get_server_summary (embeds capabilities and context paths), get_usage_guide, get_health, get_diagnostics, list_context_files, read_context_file, and write_memory_file. Retrieval: find_files (search / browse / working set), get_evidence_pack, and read_file. Continuity and long-term memory: record_activity, get_recent_activity, get_activity_briefing, save_context_digest, and load_context_digest. MCP clients should trust tools/list for the exact current schema. The former saved-pack and start_session tools were removed; their REST routes remain for one release.

Read / retrieval tools

  55:     private readonly JwtSecurityTokenHandler _handler;
  56:     private TokenValidationParameters _params;
› 57:     public bool ValidateJwtToken(string token) {
  58:         var r = _handler.ValidateToken(token, _params, out _);
  59:         return r.IsValid;
  60:     }

  10:     // Shared validation params used by AuthService
  11:     public static class TokenHelper {
› 12:         public static bool ValidateJwtToken(string t, string secret) =>
  13:             new JwtSecurityTokenHandler().CanReadToken(t);
  14:     }

  53:     private TokenValidationParameters _params;
  54:
  55:     public AuthService(IOptions<AuthOptions> opts) {
  56:         _params = BuildParams(opts.Value);
› 57:         _handler = new JwtSecurityTokenHandler();
  58:     }
  59:
  60:     public bool ValidateJwtToken(string token) {
  61:         return _handler.ValidateToken(token, _params, out _).IsValid;

Continuity / write tools

The former save_pack / list_saved_packs / get_saved_pack and start_session MCP tools were removed in the 2026-07 redesign (saved packs duplicated record_activity's query_hint; sessions fold into record_activity.client_name). Their REST routes below remain for one release.

MCP uses ModelContextProtocol.AspNetCore 1.4.1. Transport: Streamable HTTP with stateful sessions (Mcp-Session-Id header). Protocol version: 2025-11-25. Tools are discovered via WithToolsFromAssembly() — all [McpServerTool] methods in the assembly are registered automatically.

7. Runtime File System Layout

Section 11 (Startup Sequence) — moved to MoContext_Codebase.html.

Generated from MoContext source — MoContext\src\MoContext.Server\docs\MoContext_Overview.html