Skip to main content

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.

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

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

ls -la ~/.kontxt
You should see vault.db.

​
2.1 Confirm kontxt can read and write

Store one memory and immediately search for it: 
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.
Cursor MCP config typically lives at ~/.cursor/mcp.json:
{
  "mcpServers": {
    "kontxt": {
      "command": "npx",
      "args": ["-y", "@4stax/kontxt", "serve"]
    }
  }
}

​
3.1 Validate the MCP server in a terminal

Before you restart your host, confirm the server starts: 
npx -y @4stax/kontxt serve
If it starts successfully, stop it with Ctrl+C and proceed.

​
4. Test it (CLI)

# 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.
You now have persistent memory running locally. Every session builds on the last.

​
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: 
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: 
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: 
{
  "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

How memory works

Understand relevance ranking and memory types

MCP tools reference

Full reference for all exposed MCP tools

CLI reference

All CLI commands and flags

Self-hosting

Run kontxt on your own server