Cortex is a local-first memory server exposed through the Model Context Protocol (MCP). It lets an MCP client store and recall project-scoped requirements, locations, todos, and notes.

The project is intentionally small and operationally explicit: everything local is run through PowerShell scripts, the app runs in Docker, data lives in PostgreSQL with pgvector, and embeddings are produced by a local container.

What Cortex Does

Stores memories inside explicit projects.
Supports four categories: requirement, location, todo, and note.
Finds memories with hybrid semantic and keyword search across one to four query texts.
Stores one default embedding per memory and optional additional embeddings for targeted discoverability.
Updates the default embedding whenever memory content changes.
Soft-deletes items so accidental deletes are recoverable at the database level.
Exposes everything through HTTP MCP tools.
Exposes a generated REST-compatible tool facade with OpenAPI metadata.
Provides an optional Blazor web UI for browsing and testing memories.

Stack

.NET 10 ASP.NET Core
MCP C# SDK over Streamable HTTP
PostgreSQL 17 with pgvector
Entity Framework Core migrations
Hugging Face Text Embeddings Inference
Embedding model: BAAI/bge-small-en-v1.5
Vector size: 384
Docker Compose
PowerShell local ops scripts
xUnit integration tests
Optional Blazor Server web UI

Local Ports

Service	Dev instance	Test instance
Cortex app	http://localhost:5117	http://localhost:5217
Web UI	http://localhost:5118	http://localhost:5218
MCP endpoint	http://localhost:5117/mcp	http://localhost:5217/mcp
OpenAPI document	http://localhost:5117/openapi/v1.json	http://localhost:5217/openapi/v1.json
PostgreSQL	`localhost:54329`	`localhost:55439`
Embeddings	http://localhost:8088	http://localhost:8188

Quick Start

Prerequisites:

Windows with PowerShell
Docker Desktop
.NET 10 SDK

Start the full local dev stack:

.\scripts\deploy-all.ps1

Optionally seed sample data:

.\scripts\seed-db.ps1

Check the app:

http://localhost:5117/health

Connect an MCP client to:

http://localhost:5117/mcp

Inspect the generated OpenAPI document:

http://localhost:5117/openapi/v1.json

Scripts

All local operations are script-first.

Script	Purpose
`scripts\build.ps1`	Restore, build, and build the app Docker image.
`scripts\test.ps1`	Run non-integration tests.
`scripts\deploy-db.ps1`	Start the dev PostgreSQL + pgvector container.
`scripts\reset-db.ps1 -Force`	Delete and recreate the dev database volume.
`scripts\migrate-db.ps1`	Apply EF Core migrations to the dev database.
`scripts\seed-db.ps1`	Add dev sample data.
`scripts\deploy-embeddings.ps1`	Start the dev embedding model container.
`scripts\deploy-app.ps1`	Build and start the dev app container.
`scripts\deploy-web.ps1`	Build and start the optional dev web UI.
`scripts\deploy-all.ps1`	Start db, embeddings, migrate, and start app.
`scripts\stop-web.ps1`	Stop the optional dev web UI.
`scripts\stop-all.ps1`	Stop dev containers without deleting data.
`scripts\logs.ps1`	Show dev container logs.
`scripts\deploy-test.ps1`	Start the isolated test stack.
`scripts\deploy-test-web.ps1`	Build and start the optional test web UI.
`scripts\test-integration.ps1`	Reset/deploy the test stack and run integration tests.
`scripts\stop-test-web.ps1`	Stop the optional test web UI.
`scripts\stop-test.ps1`	Stop test containers without deleting data.
`scripts\reset-test.ps1 -Force`	Delete and recreate the test database volume.

MCP Tools

Tool	Purpose
`CreateProject`	Create an explicit project.
`ListProjects`	List projects.
`AddRequirement`	Add a requirement with required statement and context fields.
`AddLocation`	Add a location with required item and place fields.
`AddTodo`	Add a todo with required task and priority fields.
`AddNote`	Add a note with required subject and body fields.
`FindItems`	Search memory items.
`ListItemEmbeddings`	List default and additional embeddings for an item.
`AddItemEmbedding`	Add an additional discoverability embedding.
`UpdateItemEmbedding`	Update an additional embedding.
`DeleteItemEmbedding`	Delete an additional embedding.
`UpdateRequirement`	Update a requirement item.
`UpdateLocation`	Update a location item.
`UpdateTodo`	Update a todo item.
`UpdateNote`	Update a note item.
`DeleteItem`	Soft-delete an item.

There is no default project. Add, update, and delete tools require an existing project. FindItems requires a project unless searchAllProjects is set to true.

Documentation

Useful Commands

Run the whole dev stack:

.\scripts\deploy-all.ps1

Run the full local integration pipeline:

.\scripts\test-integration.ps1

Keep the test stack running for Visual Studio Test Explorer:

.\scripts\test-integration.ps1 -KeepRunning

Show app logs:

.\scripts\logs.ps1 -Service app -Follow

Start the optional web UI:

.\scripts\deploy-web.ps1

Reset only the dev database:

.\scripts\reset-db.ps1 -Force

Reset only the test database:

.\scripts\reset-test.ps1 -Force

README.md

Cortex