Installation

PAMK has a zero-dependency core. Install only what you need:

Terminal 
# Core library (zero dependencies)
$ pip install pamk

# MCP server (for Claude Desktop, Claude Code, Cursor)
$ pip install pamk[mcp]

# Local semantic search (sentence-transformers)
$ pip install pamk[local]

# OpenAI embeddings
$ pip install pamk[openai]

# Ollama embeddings
$ pip install pamk[ollama]

# Everything
$ pip install pamk[all]

Python 3.10 or later is required.

MCP Server Setup

Add PAMK as an MCP server in your client's configuration file.

Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

claude_desktop_config.json 
{
  "mcpServers": {
    "pamk": {
      "command": "python",
      "args": ["-m", "pamk.mcp.server"],
      "env": {
        "PAMK_USER_ID": "your_user_id"
      }
    }
  }
}

Claude Code / Cursor / VS Code

Add to your project's .mcp.json file:

.mcp.json 
{
  "mcpServers": {
    "pamk": {
      "command": "pamk-mcp",
      "env": {
        "PAMK_PROJECT_DB": "pamk_memory.db",
        "PAMK_USER_ID": "default"
      }
    }
  }
}

Using the CLI entry point

If you installed pamk-mcp separately:

Terminal 
$ pip install pamk-mcp
$ pamk-mcp  # Starts MCP server via stdio

Environment Variables

Configure PAMK behavior through environment variables:

Variable Default Description
PAMK_USER_ID default Default user ID for operations
PAMK_PROJECT_DB pamk_memory.db Project-specific memory database path
PAMK_USER_DB ~/.pamk/user_memory.db Personal memory shared across projects
PAMK_ENTERPRISE_DB (empty) Enterprise/shared memory path (optional)
PAMK_LICENSE_KEY (empty) License key for Pro/Team features
PAMK_LICENSE_EMAIL (empty) Email associated with license key
PAMK_USE_TYPE personal personal or commercial
PAMK_TIMEOUT 30 Default operation timeout (seconds)
PAMK_CONSOLIDATION_TIMEOUT 120 Consolidation operation timeout

MCP Tools Reference

When running as an MCP server, PAMK exposes these tools:

Tool Description Key Parameters
add_user Create a new user in the memory system user_id
remember_fact Store a fact as namespace/key.path = value namespace, key, path, value, confidence
recall_fact Retrieve a stored fact by namespace and key namespace, key
forget_fact Delete a fact with audit trail namespace, key, path
ingest_event Record a conversation event into episodic memory content, role
search_memory Hybrid BM25 + semantic search over episodic memory query, k
get_context_pack Assemble state + episodic context within character budget query, max_chars, episodic_k
consolidate_daily Generate daily digest extracting decisions, entities, facts date (ISO format)
resurface_due Get items due for spaced repetition review (SM-2) limit
inspect_beliefs Check belief drift, stability scores, and change reports mode, path, days
manage_embeddings Embedding health checks and model migrations action, new_model_id
delete_user GDPR-compliant hard delete of all user data user_id

All tools accept optional user_id (defaults to PAMK_USER_ID) and scope (project, user, or enterprise) parameters.

Memory Scopes

PAMK organizes memory into three scopes:

Scope Storage Use Case
project ./pamk_memory.db (current directory) Project-specific knowledge, codebase context, decisions
user ~/.pamk/user_memory.db Personal preferences, cross-project knowledge
enterprise Configured via PAMK_ENTERPRISE_DB Shared organizational knowledge, team standards

Each scope maintains independent state memory, episodic memory, and consolidation history. The default scope is project.

Error Codes

PAMK returns structured error codes:

Range Category Examples
PAMK_E1xx Configuration / setup Missing DB path, invalid scope
PAMK_E2xx Validation Invalid user_id, bad date format
PAMK_E3xx Operation User not found, fact not found
PAMK_E4xx Resource Database locked, disk full
PAMK_E5xx Timeout Consolidation timeout, search timeout
PAMK_E6xx Rate limiting Too many operations
PAMK_E9xx Internal Unexpected errors

How Licensing Works

Community tier (free)

No license key needed. State memory, episodic memory, BM25 search, and basic consolidation work out of the box.

Pro tier and above

Set your license key and email as environment variables:

Environment 
export PAMK_LICENSE_KEY="PAMK-XXXX-XXXX-XXXX-XXXX"
export PAMK_LICENSE_EMAIL="your@email.com"

On first use, PAMK generates a local security code and activates your license. This device-pairing model ensures your license is bound to your installation.

What happens during activation

  1. PAMK generates a random security code locally
  2. The code is registered with the license server (one-time)
  3. Subsequent validations check key + email + security code
  4. Results are cached locally for 24 hours (7-day offline grace period)

14-day free trial

Personal users get a 14-day trial of Pro features without needing a license key. After the trial, Pro features require a valid license.

Commercial Use

If you're using PAMK in a commercial product or business context, set:

Environment 
export PAMK_USE_TYPE="commercial"

Commercial use requires a valid Pro or Team license immediately (no trial period). This applies to any use in a business context, commercial products, or revenue-generating activities.

View Pricing Plans