# Khwan

Khwan carries useful project facts into later sessions and subagents. Use it when an agent needs decisions or task context from earlier work.

- MCP server · `type=mcp` · Claude Code, Codex, Cursor, GitHub Copilot, Windsurf (Devin Desktop), Cline, Zed, Gemini CLI
- Author: khwanlabs
- License: MIT · policy=link-only · description only; the file stays with the author
- Source: https://github.com/khwanlabs/khwan-mcp
- Updated: 2026-08-27
- HTML: https://affpapa.org/en/nevibecode/mcp/khwan

## What it does

Khwan gives an MCP client a persistent store for distilled facts. An agent can look up relevant context with `khwan_recall` and save a durable decision with `khwan_remember`; a later session gets a compact set of facts rather than an old conversation replay. `KHWAN_CORE` and `KHWAN_USER` let you separate memories across projects and subagents.

It does not cut token use inside a live session: MCP memory is added to the context the host already sends. For Claude Code, the suggested pattern is to retrieve memory at the start, then save lasting facts as they come up instead of repeating the loop every turn. The HTTP setup command is below. Local `uvx` setup needs `KHWAN_API_KEY`, so keep the secret out of a project config that may be committed.

## Requirements
- Needs: Python and uv (commands run via uvx)
- Remote server: `https://mcp.khwan.ai/mcp/{core}/{user}`
- Environment variables: `KHWAN_API_KEY`, `KHWAN_CORE`, `KHWAN_USER`, `KHWAN_BASE_URL` — keys and tokens: ask the human for the values, never commit them or put them in shared files.

## Install

### Claude Code (native platform)

1. **Platform CLI**
```bash
claude mcp add --env KHWAN_API_KEY=<KHWAN_API_KEY> --env KHWAN_CORE=<KHWAN_CORE> --env KHWAN_USER=<KHWAN_USER> --env KHWAN_BASE_URL=<KHWAN_BASE_URL> --transport stdio khwan -- uvx khwan-mcp
```
Replace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from khwan-mcp <command>

2. **Platform CLI: remote server**
```bash
claude mcp add --transport http khwan-mcp https://mcp.khwan.ai/mcp/{core}/{user}
```

### Codex

1. **Platform CLI**
```bash
codex mcp add khwan --env KHWAN_API_KEY=<KHWAN_API_KEY> --env KHWAN_CORE=<KHWAN_CORE> --env KHWAN_USER=<KHWAN_USER> --env KHWAN_BASE_URL=<KHWAN_BASE_URL> -- uvx khwan-mcp
```
Replace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from khwan-mcp <command>

2. **Platform CLI: remote server**
```bash
codex mcp add khwan --url https://mcp.khwan.ai/mcp/{core}/{user}
```

### Cursor

1. **Config file**
File `.cursor/mcp.json`:
```json
{
    "mcpServers": {
        "khwan": {
            "command": "uvx",
            "args": [
                "khwan-mcp"
            ],
            "env": {
                "KHWAN_API_KEY": "<KHWAN_API_KEY>",
                "KHWAN_CORE": "<KHWAN_CORE>",
                "KHWAN_USER": "<KHWAN_USER>",
                "KHWAN_BASE_URL": "<KHWAN_BASE_URL>"
            }
        }
    }
}
```
Replace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from khwan-mcp <command>

2. **Config file**
File `.cursor/mcp.json`:
```json
{
    "mcpServers": {
        "khwan": {
            "url": "https://mcp.khwan.ai/mcp/{core}/{user}"
        }
    }
}
```

### GitHub Copilot

1. **Config file**
File `.vscode/mcp.json`:
```json
{
    "servers": {
        "khwan": {
            "type": "stdio",
            "command": "uvx",
            "args": [
                "khwan-mcp"
            ],
            "env": {
                "KHWAN_API_KEY": "<KHWAN_API_KEY>",
                "KHWAN_CORE": "<KHWAN_CORE>",
                "KHWAN_USER": "<KHWAN_USER>",
                "KHWAN_BASE_URL": "<KHWAN_BASE_URL>"
            }
        }
    }
}
```
Replace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from khwan-mcp <command>

2. **Config file**
File `.vscode/mcp.json`:
```json
{
    "servers": {
        "khwan": {
            "type": "http",
            "url": "https://mcp.khwan.ai/mcp/{core}/{user}"
        }
    }
}
```

### Gemini CLI

1. **Platform CLI**
```bash
gemini mcp add -e KHWAN_API_KEY=<KHWAN_API_KEY> -e KHWAN_CORE=<KHWAN_CORE> -e KHWAN_USER=<KHWAN_USER> -e KHWAN_BASE_URL=<KHWAN_BASE_URL> khwan uvx khwan-mcp
```
Replace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from khwan-mcp <command>

2. **Platform CLI: remote server**
```bash
gemini mcp add -t http khwan https://mcp.khwan.ai/mcp/{core}/{user}
```

## When to use it
- retrieve a decision from an earlier session
- give a subagent a concise task brief
- save a durable project fact or preference
- keep project and subagent memories separate

## Example prompts
- Use `khwan_recall` to retrieve deployment decisions relevant to this task.
- Save this lasting project decision with `khwan_remember`.
- Look up the task context with `khwan_recall` and pass it to a subagent.

## Similar
- [Agentic UX Design - Relationship-Centric Interfaces](https://affpapa.org/en/nevibecode/skills/agentic-ux-design-relationship-centric-interfaces.md) — skill · 3300 installs
- [mem0](https://affpapa.org/en/nevibecode/skills/mem0.md) — skill · 2300 installs
- [mem0-cli](https://affpapa.org/en/nevibecode/skills/mem0-cli.md) — skill · 773 installs
- [Persome](https://affpapa.org/en/nevibecode/mcp/persome.md) — MCP server · ★ 1328
- [Nautilus Compass Memory](https://affpapa.org/en/nevibecode/mcp/nautilus-compass-memory.md) — MCP server · ★ 1254
- [neural-memory](https://affpapa.org/en/nevibecode/mcp/neural-memory.md) — MCP server · ★ 242

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md