FEGIS (Schema-Driven Memory) MCP server for AI agents

FEGIS is a runtime framework for structured cognition and persistent memory in language models built with Anthropic's Model Context Protocol. It allows schema-defined cognitive modes to be dynamically registered, invoked, and stored as structured memory using vector embeddings and semantic context. This system serves as a foundation for building custom cognitive systems with programmable thinking tools and recallable memory.

Installation Guide

Prerequisites

Before installing FEGIS, you need to set up a few dependencies:

Install uv (modern Python package/runtime manager)
Install Docker for running Qdrant vector database
Have Claude Desktop application installed

Step 1: Install uv and Clone the Repository

# macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows
winget install --id=astral-sh.uv -e

# Clone the repo
git clone https://github.com/p-funk/FEGIS.git

Step 2: Set Up Qdrant Vector Database

Make sure Docker is installed and running, then launch Qdrant:

docker run -d --name qdrant -p 6333:6333 -p 6334:6334 qdrant/qdrant:latest

If you don't have Docker yet, download and install Docker Desktop.

Step 3: Configure Claude Desktop

Create or edit the Claude Desktop configuration file at the appropriate location:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

Add the following configuration, replacing <FEGIS_PATH> with the full path to your local FEGIS clone:

{
  "mcpServers": {
    "mcp-fegis-server": {
      "command": "uv",
      "args": [
        "--directory",
        "<FEGIS_PATH>",
        "run",
        "fegis"
      ],
      "env": {
        "QDRANT_URL": "http://localhost:6333",
        "QDRANT_GRPC_PORT": "6334",
        "QDRANT_PREFER_GRPC": "true",
        "QDRANT_API_KEY": "",
        "COLLECTION_NAME": "cognitive_archive",
        "FAST_EMBED_MODEL": "nomic-ai/nomic-embed-text-v1.5",
        "CONFIG_PATH": "<FEGIS_PATH>/archetypes/example.yaml"
      }
    }
  }
}

Using FEGIS

Working with Cognitive Tools

FEGIS tools are made available to the Claude model at runtime, but they need to be explicitly prompted for use. They won't be used automatically by the model.

Priming the Model

To encourage Claude to use the cognitive tools, you should prime it with appropriate instructions. For example:

Throughout our conversation, use your tools naturally and fluidly. 
Feel free to reflect, introspect, stay aware, have an innermonologue
or use memory to recall past insights as needed. You can search past
thoughts using `search_memories`, or revisit specific artifacts with
`retrieve_memory`.

Using the Memory System

The FEGIS memory system provides several key capabilities:

Semantic Search: Find cognitive artifacts based on content similarity
Direct Retrieval: Look up specific artifacts by their UUID
Persistent Storage: Artifacts remain available across sessions and models

Creating Custom Archetypes

FEGIS is designed to be customizable through archetypes, which define cognitive modes and structures.

Custom Archetype Creation

To create your own cognitive archetypes:

Create a new YAML file in the archetypes directory
Define your own cognitive modes, fields, and facets
Update the CONFIG_PATH in the Claude Desktop configuration to point to your custom archetype

Custom archetypes can be designed for various purposes, such as:

Problem-solving processes
Creative workflows
Analytical thinking frameworks
Domain-specific reasoning patterns

Each archetype can define multiple cognitive modes with structured fields and metadata that guide how Claude thinks and stores information.

How to install this MCP server

For Claude Code

To add this MCP server to Claude Code, run this command in your terminal:

claude mcp add-json "mcp-fegis-server" '{"command":"uv","args":["--directory","<FEGIS_PATH>","run","fegis"],"env":{"QDRANT_URL":"http://localhost:6333","QDRANT_GRPC_PORT":"6334","QDRANT_PREFER_GRPC":"true","QDRANT_API_KEY":"","COLLECTION_NAME":"cognitive_archive","FAST_EMBED_MODEL":"nomic-ai/nomic-embed-text-v1.5","CONFIG_PATH":"<FEGIS_PATH>/archetypes/example.yaml"}}'

See the official Claude Code MCP documentation for more details.

For Cursor

There are two ways to add an MCP server to Cursor. The most common way is to add the server globally in the ~/.cursor/mcp.json file so that it is available in all of your projects.

If you only need the server in a single project, you can add it to the project instead by creating or adding it to the .cursor/mcp.json file.

Adding an MCP server to Cursor globally

To add a global MCP server go to Cursor Settings > Tools & Integrations and click "New MCP Server".

When you click that button the ~/.cursor/mcp.json file will be opened and you can add your server like this:

{
    "mcpServers": {
        "mcp-fegis-server": {
            "command": "uv",
            "args": [
                "--directory",
                "<FEGIS_PATH>",
                "run",
                "fegis"
            ],
            "env": {
                "QDRANT_URL": "http://localhost:6333",
                "QDRANT_GRPC_PORT": "6334",
                "QDRANT_PREFER_GRPC": "true",
                "QDRANT_API_KEY": "",
                "COLLECTION_NAME": "cognitive_archive",
                "FAST_EMBED_MODEL": "nomic-ai/nomic-embed-text-v1.5",
                "CONFIG_PATH": "<FEGIS_PATH>/archetypes/example.yaml"
            }
        }
    }
}

Adding an MCP server to a project

To add an MCP server to a project you can create a new .cursor/mcp.json file or add it to the existing one. This will look exactly the same as the global MCP server example above.

How to use the MCP server

Once the server is installed, you might need to head back to Settings > MCP and click the refresh button.

The Cursor agent will then be able to see the available tools the added MCP server has available and will call them when it needs to.

You can also explicitly ask the agent to use the tool by mentioning the tool name and describing what the function does.

For Claude Desktop

To add this MCP server to Claude Desktop:

1. Find your configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json

2. Add this to your configuration file:

{
    "mcpServers": {
        "mcp-fegis-server": {
            "command": "uv",
            "args": [
                "--directory",
                "<FEGIS_PATH>",
                "run",
                "fegis"
            ],
            "env": {
                "QDRANT_URL": "http://localhost:6333",
                "QDRANT_GRPC_PORT": "6334",
                "QDRANT_PREFER_GRPC": "true",
                "QDRANT_API_KEY": "",
                "COLLECTION_NAME": "cognitive_archive",
                "FAST_EMBED_MODEL": "nomic-ai/nomic-embed-text-v1.5",
                "CONFIG_PATH": "<FEGIS_PATH>/archetypes/example.yaml"
            }
        }
    }
}

3. Restart Claude Desktop for the changes to take effect