ContextMemory

# ContextMemory Agentic Gateway

**Give an LLM memory by swapping a URL. That same URL can also act when it needs to.**

ContextMemory is a context and agent proxy for applications that already talk to LLMs. The public wire format is **Ollama-compatible**: you keep using `POST /api/chat` with the same message schema and get back an Ollama-style response (`message.content` / `done`) — not OpenAI `choices[]`. Behind the scenes, the gateway enriches each turn with session memory (a per-session markdown wiki), optional **Global Wiki** retrieval via the `wiki_search` tool, optional web search, and — when enabled — an **agentic loop** with tools isolated per tenant.

OpenAI, Azure OpenAI, Anthropic, and similar providers are supported as **LLM backends**; the gateway maps them to the Ollama response shape your client already reads.

---

> ### Don't want to self-host?
> **[Kortexio Cloud](https://kortexio.io)** is the hosted version of this gateway — same request body and response schema, zero infrastructure, **bring your own LLM key** (no markup on tokens). Get an API key and point your chat endpoint at it in minutes. **[Start free →](https://kortexio.io)**
>
> Self-hosting this open-source core and running on Kortexio Cloud share the **same chat body and Ollama response**. The only differences are the API key prefix and whether you send `X-App-Id`. Prototype locally, move to the cloud without rewriting your chat payload — or the other way around.

---

## Why it exists

| Problem | ContextMemory solution |
|---|---|
| The LLM forgets context between messages | Per-session compiled wiki + recent history injected automatically |
| Product/ops docs live outside the chat session | **Global Wiki** — app-scoped knowledge base searched on demand via `wiki_search` |
| You need actions (shell, APIs, MCP) without a new endpoint | Agentic loop on the same `/api/chat`, invisible to the client |
| Each client/tenant needs different tools and rules | Per-app configuration: ACA, self-hosted sandbox, MCP, guardrails, prompts |
| Destructive actions need human control | Blocking human-in-the-loop with wiki checkpoints |
| Streaming with multi-step loops is complex | Internal buffer: client only receives final text; optional progress via metadata |

---

## Two ways to run it

| | **Kortexio Cloud** (hosted) | **Self-host** (this repo) |
|---|---|---|
| Infrastructure | None — managed for you | You run the .NET 9 gateway |
| LLM | BYOK via dashboard — set provider + model + key | You point the gateway at your own backend in `appsettings` |
| API key format | `cmk_live_...` | `cm_live_...` |
| Tenant selection | Bound to your key — no `X-App-Id` | `X-App-Id` header per app |
| Request body & response | **Identical** (Ollama schema) | **Identical** (Ollama schema) |
| Best for | Shipping fast, no ops | Full control, air-gapped / on-prem |
| Get started | [kortexio.io](https://kortexio.io) | [Quick start ↓](#quick-start--self-host) |

Both speak the **same `POST /api/chat`** contract. The only auth differences are the key prefix and whether you pass `X-App-Id`. Never `choices[]` — the response is always Ollama-style `message.content` / `done`.

---

## Quick start — Kortexio Cloud

The fastest path: no build, no database, no Ollama to run.

### 1. Get a key and connect your LLM (BYOK)

Create a free account at **[kortexio.io](https://kortexio.io)** and copy your API key (starts with `cmk_live_`).

Kortexio Cloud is **bring-your-own-key**: Kortexio orchestrates memory and agentic — text generation always uses your provider. In your app's **LLM provider** tab on the dashboard, pick a provider (OpenAI, Azure OpenAI, Anthropic, your own Ollama, …), set the model id, and paste your own provider key — **no markup on tokens**. Use **Test connection** to verify it before you ship. The `model` you send in each request must match the one configured there.

### 2. Point your endpoint here

If you already call an Ollama-compatible `POST /api/chat`, change one URL and keep the same body and response parsing:

```diff
- POST http://localhost:11434/api/chat
+ POST https://api.kortexio.io/api/chat
```

Coming from the OpenAI Chat Completions API? Keep a similar message body, but parse the **Ollama** response (`message.content` / `done`), not `choices[]`.

### 3. First chat request

```bash
# Turn 1 — teach it something
curl -X POST https://api.kortexio.io/api/chat \
  -H "Content-Type: application/json" \
  -H "X-User-Id: user-42" \
  -H "X-Session-Id: sess-abc" \
  -H "Authorization: Bearer cmk_live_..." \
  -d '{
    "model": "gpt-4o-mini",
    "messages": [{ "role": "user", "content": "Remember: KORTEX-PINEAPPLE" }]
  }'
```

```bash
# Turn 2 — same X-Session-Id, memory recalled automatically
curl -X POST https://api.kortexio.io/api/chat \
  -H "Content-Type: application/json" \
  -H "X-User-Id: user-42" \
  -H "X-Session-Id: sess-abc" \
  -H "Authorization: Bearer cmk_live_..." \
  -d '{
    "model": "gpt-4o-mini",
    "messages": [{ "role": "user", "content": "What was the secret word?" }]
  }'
```

**Response (Ollama schema — same as self-host):**

```json
{
  "model": "gpt-4o-mini",
  "message": { "role": "assistant", "content": "The secret word is KORTEX-PINEAPPLE." },
  "done": true
}
```

That's the entire integration. Session memory works on the next turn automatically — no embeddings, no vector DB, no retrieval logic to write.

**Required headers:** `X-User-Id`, `Authorization: Bearer cmk_live_...`  
**Optional:** `X-Session-Id` (generated by the API if omitted). Your tenant is inferred from the key — you do **not** send `X-App-Id` on Cloud.  
**`model`:** required in the body, and it must match the provider/model you configured in the **LLM provider** tab (BYOK).

---

## Quick start — self-host

Run the open-source gateway yourself — the path for **on-prem or fully local** deployments. Unlike Cloud (where the dashboard wires up your LLM for you), here **you point the gateway at your own LLM backend** — endpoint and model — in config. Same chat body, same Ollama response as Cloud; you supply the `X-App-Id` and use a `cm_live_` key.

### Prerequisites

- .NET 9 SDK
- Ollama (or another configured backend) reachable on the network
- Optional: PostgreSQL 14+ for production / multi-instance HA

### 1. Configure

The committed `appsettings.json` uses **safe placeholders** and `PersistenceProvider: File` (no database required). Seed app id: `demo-dev` with key `cm_live_dev_key_change_me` (change before any real use).

**Local secrets** — choose one approach (never commit real values):

| Method | How |
|---|---|
| User Secrets (recommended) | `cd src/ContextMemory.Api` then `dotnet user-secrets set "ContextMemory:MasterKey" "your-key"` |
| Environment variables | See [`.env.example`](.env.example) for the `__` naming convention |
| Development file | Create `src/ContextMemory.Api/appsettings.Development.json` (gitignored) with local overrides |

For **PostgreSQL** in production or multi-instance HA:

```json
{
  "ConnectionStrings": {
    "ContextMemory": "Host=localhost;Port=5432;Database=contextmemory;Username=...;Password=..."
  },
  "ContextMemory": {
    "PersistenceProvider": "Postgres",
    "DataPath": "../../data",
    "OllamaEndpoint": "http://localhost:11434",
    "MasterKey": "your-master-key",
    "Apps": {
      "my-app": {
        "ApiKey": "cm_live_...",
        "SystemPrompt": "You are a helpful assistant.",
        "LlmModel": "qwen3.5:9b"
      }
    }
  }
}
```

Use `"Postgres"` exactly (not `Postgresql`). Relative `DataPath` values resolve from the API content root.

#### `appsettings.json` field reference

| Field | Meaning |
|---|---|
| `ConnectionStrings:ContextMemory` | PostgreSQL connection string when `PersistenceProvider` is `Postgres` |
| `ContextMemory:PersistenceProvider` | `File` (default) or `Postgres` |
| `ContextMemory:DataPath` | Root for file-based persistence (apps, sessions, wiki) |
| `ContextMemory:OllamaEndpoint` | Default Ollama (or Ollama-compatible) backend base URL |
| `ContextMemory:DefaultLlmModel` | Fallback model when an app has no `LlmModel` |
| `ContextMemory:MasterKey` | Secret for Admin API / admin dashboard |
| `ContextMemory:AdminCorsOrigins` | Allowed browser origins for Admin UI CORS |
| `ContextMemory:WebSearch:*` | Tavily/Brave keys, default provider, timeout |
| `ContextMemory:Apps` | Seed map of tenant apps; each key is the **app id** (`X-App-Id`) |

Per-app runtime settings (agentic tools, wiki schema, web-search toggles, guardrails) are managed via the admin API or Admin UI host, not only this seed section.

### 2. Start the API

```bash
cd src/ContextMemory.Api
dotnet run
```

API defaults to `http://localhost:5100` (Swagger in Development at `/swagger`).

### 3. First chat request

```bash
curl -X POST http://localhost:5100/api/chat \
  -H "Content-Type: application/json" \
  -H "X-App-Id: demo-dev" \
  -H "X-User-Id: user-123" \
  -H "X-Session-Id: sess-abc" \
  -H "Authorization: Bearer cm_live_dev_key_change_me" \
  -d '{
    "model": "qwen3.5:9b",
    "messages": [{ "role": "user", "content": "Hi, do you remember my name?" }]
  }'
```

**Response (Ollama schema — identical to Cloud):**

```json
{
  "model": "qwen3.5:9b",
  "message": { "role": "assistant", "content": "..." },
  "done": true,
  "context_memory": {
    "message_id": "...",
    "agentic": {
      "phase": "Completed",
      "awaiting_confirmation": false,
      "steps": [{ "tool_name": "shell_execute", "success": true }]
    }
  }
}
```

**Required headers:** `X-App-Id`, `X-User-Id`, `Authorization: Bearer {API_KEY}`  
**Optional:** `X-Session-Id` (generated by the API if omitted).

### 4. Admin UI and Chat Lab

In a second terminal:

```bash
cd src/ContextMemory.Admin.Web
dotnet run
```

Open **[http://localhost:5200](http://localhost:5200)** → **Settings** → set API URL `http://localhost:5100` and your Master Key (`ContextMemory:MasterKey`) → **Test connection**.

- **Applications** — register apps, stats, rot