> ## Documentation Index
> Fetch the complete documentation index at: https://docs.4stax.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart

> Get persistent AI memory running locally in under 5 minutes using kontxt and MCP.

This guide gets you from zero to persistent AI memory in your MCP client (Cursor, Claude Desktop, or any MCP-compatible host) in under 5 minutes.

## Prerequisites

* Node.js 18 or newer
* An MCP-compatible client (Cursor or Claude Desktop)

## 1. Initialize kontxt

```bash theme={null}
npx -y @4stax/kontxt init
```

This creates your local vault and configuration:

* `~/.kontxt/vault.db` (SQLite vault)
* `~/.kontxt/config.json` (settings; may include keys if you add them)
* MCP host config entries for supported hosts

## 1.1 What `init` actually does

`init` is the core user flow. It prepares the local store and makes kontxt runnable as an MCP server.

It will:

* Create the `~/.kontxt/` directory if it does not exist
* Create `~/.kontxt/vault.db` if it does not exist
* Create or update `~/.kontxt/config.json`
* Attempt to write MCP host config files for supported hosts when it can locate them

If a host config write fails, you can still configure your host manually in step 3.

## 2. Verify your vault exists

```bash theme={null}
ls -la ~/.kontxt
```

You should see `vault.db`.

## 2.1 Confirm kontxt can read and write

Store one memory and immediately search for it:

```bash theme={null}
npx -y @4stax/kontxt add "I prefer TypeScript over JavaScript" -t preference
npx -y @4stax/kontxt search "TypeScript preference"
```

If search returns your entry, the vault is working.

## 3. (If needed) configure your MCP client manually

`kontxt init` can write MCP entries automatically. If your setup needs manual configuration, use these patterns.

<Tabs>
  <Tab title="Cursor">
    Cursor MCP config typically lives at `~/.cursor/mcp.json`:

    ```json theme={null}
    {
      "mcpServers": {
        "kontxt": {
          "command": "npx",
          "args": ["-y", "@4stax/kontxt", "serve"]
        }
      }
    }
    ```
  </Tab>

  <Tab title="Claude Desktop (macOS)">
    Claude Desktop MCP config typically lives at `~/Library/Application Support/Claude/claude_desktop_config.json`:

    ```json theme={null}
    {
      "mcpServers": {
        "kontxt": {
          "command": "npx",
          "args": ["-y", "@4stax/kontxt", "serve"]
        }
      }
    }
    ```
  </Tab>
</Tabs>

## 3.1 Validate the MCP server in a terminal

Before you restart your host, confirm the server starts:

```bash theme={null}
npx -y @4stax/kontxt serve
```

If it starts successfully, stop it with `Ctrl+C` and proceed.

## 4. Test it (CLI)

```bash theme={null}
# Store a memory
npx -y @4stax/kontxt add "I prefer TypeScript over JavaScript" -t preference

# Search your vault
npx -y @4stax/kontxt search "language preferences"
```

You should see your stored memory returned in the search results.

## 5. Use it in your AI client

Restart your MCP client. From now on, kontxt will automatically surface relevant memories from your vault into your AI sessions. Try asking your AI client something related to what you stored. It should already know.

<Check>
  You now have persistent memory running locally. Every session builds on the last.
</Check>

## 5.1 What “memory” looks like in practice

Ask your host something that should trigger retrieval:

1. Ask a question that depends on a stored preference, such as “What language should I use for this repo”.
2. If kontxt is connected and you previously stored “I prefer TypeScript”, the host should respond consistently with that preference.

If your vault is empty, your host may still confirm tool connectivity by reporting that there is no relevant context yet.

## Optional: embeddings

For better semantic search, you can store an OpenAI key during init:

```bash theme={null}
npx -y @4stax/kontxt init --key sk-...
```

Without it, kontxt can use offline embeddings (Transformers.js) or fall back to keyword matching depending on your environment.

## Troubleshooting

### `init` ran but `~/.kontxt/vault.db` is missing

Run init again and then check the directory:

```bash theme={null}
npx -y @4stax/kontxt init
ls -la ~/.kontxt
```

If the directory exists but the database does not, check for errors printed during init.

### My host does not show kontxt tools

Most hosts load MCP servers at startup. Fully quit and reopen the host.

If you configured the host manually, validate your JSON file is valid JSON and that it contains:

```json theme={null}
{
  "command": "npx",
  "args": ["-y", "@4stax/kontxt", "serve"]
}
```

Then run `npx -y @4stax/kontxt serve` in a terminal to confirm it starts without errors.

## Next steps

<CardGroup cols={2}>
  <Card title="How memory works" icon="brain" href="/memory/how-it-works">
    Understand relevance ranking and memory types
  </Card>

  <Card title="MCP tools reference" icon="plug" href="/developers/mcp-tools">
    Full reference for all exposed MCP tools
  </Card>

  <Card title="CLI reference" icon="terminal" href="/developers/cli">
    All CLI commands and flags
  </Card>

  <Card title="Self-hosting" icon="server" href="/developers/self-hosting">
    Run kontxt on your own server
  </Card>
</CardGroup>