kimi-supermemory

name: kimi-supermemory description: Persistent memory for Kimi CLI using Supermemory. Provides 6 tools: add, search, get_context, list, forget, profile. Features hash-based scoping, privacy filtering, and configurability.

Kimi Supermemory

This skill enables persistent memory across Kimi CLI sessions using Supermemory.

Features

• 6 MCP Tools: add, search, get_context, list, forget, profile
• Hash-Based Scoping: User and project tags for organized memory
• Privacy Filtering: <private> tags protect sensitive content
• Configuration: JSONC config file with environment variable fallback
• Structured Logging: Timestamped logs to ~/.kimi-supermemory.log
• Project-Aware: Memories organized by project directory

Quick Start

Automatic Installation

# Run the install script
chmod +x install.sh && ./install.sh

This script:

• Builds the MCP server
• Registers with kimi-cli: kimi mcp add
• Installs SKILL.md to ~/.config/agents/skills/kimi-supermemory/
• Sets up basic configuration

Manual Installation

# Clone and setup
git clone https://github.com/dpolishuk/kimi-supermemory.git
cd kimi-supermemory/mcp-server
npm install && npm run build

# Register with kimi-cli
kimi mcp add --transport stdio supermemory -- node /path/to/kimi-supermemory/mcp-server/dist/server.cjs

# Set API key
export SUPERMEMORY_API_KEY="sm_..."

Get your API key at console.supermemory.ai.

Configuration

Configuration File

Create ~/.config/kimi/supermemory.jsonc or ~/.config/kimi/supermemory.json:

{
  // API settings (environment variables take precedence)
  "apiKey": "sm_...",
  "apiUrl": "https://api.supermemory.ai",

  // Debug mode (enables verbose logging to stderr)
  "debug": false,

  // Keyword patterns for automatic memory capture
  "keywordPatterns": ["decided:", "prefer:", "always:", "never:", "note: "],

  // Semantic search settings
  "similarityThreshold": 0.6,
  "maxResults": 10,

  // Memory limits
  "memoryTypes": 6,
  "compactSize": 50
}

Environment Variables

Privacy

<private> Tags

Wrap sensitive content in <private> tags to prevent storage:

<private>
My API key is: sk-12345
</private>

Privacy Rules:

• Content inside <private> tags is replaced with [REDACTED]
• Fully-private content (only [REDACTED] remains) is rejected
• Case-insensitive: <private>, <PRIVATE>, <PrIvAtE> all work
• Nested tags are handled correctly

Hash-Based Scoping

Memories are organized using hash-based tags:

User Tag:kimi_user_{sha256(KIMI_EMAIL)}- Unique identifier for your profile

• Falls back to USER or USERNAME if KIMI_EMAIL not set

Project Tag:kimi_project_{sha256(normalized_git_url)}- Stable across machines

• Falls back to directory name if not a git repo

Git URL normalization removes:- Protocols (https://, git@)

• Credentials (user:pass@)
• .git suffix

Memory Types

Use these 6 categories when adding memories:

MCP Tools

Unified Tool (Recommended)

1. supermemory

Manage and query Supermemory with a single tool using mode parameter.

Parameters:

• mode (required): "add", "search", "profile", "list", "forget", or "help"
• content (for add): Memory text to save
• query (for search/profile): Search query
• scope (optional): "user" (cross-project) or "project" (default)
• type (for add): Memory type classification
• memoryId (for forget): ID of memory to delete
• limit (for list/search): Max results

Examples:

# Add a memory
Use tool: supermemory
mode: "add"
content: "Uses TypeScript with strict mode"
scope: "project"
type: "project-config"

# Search memories
Use tool: supermemory
mode: "search"
query: "authentication"
scope: "user"

# Get help
Use tool: supermemory
mode: "help"

Individual Tools (Legacy)

2. supermemory_add

Save a memory for future recall.

Parameters:

• content (required): The memory text
• containerTag (optional): Project-specific tag
• metadata (optional): Additional context

Example:

Use tool: supermemory_add
content: "Decided to use PostgreSQL for transaction support"
metadata: { type: "conversation" }

3. supermemory_search

Search your coding history.

Parameters:

• query (required): Search query
• containerTag (optional): Project scope
• limit (optional): Max results (default: 10)

Example:

Use tool: supermemory_search
query: "authentication implementation"

4. supermemory_get_context

Fetch profile and project context (auto-called on session start).

Parameters:

• cwd (optional): Working directory (auto-detected)
• projectName (optional): Project name

Example:

Use tool: supermemory_get_context
cwd: "/path/to/project"
projectName: "my-app"

5. supermemory_list

List recent memories for a project.

Parameters:

• containerTag (optional): Project scope
• limit (optional): Max memories (default: 20)

Example:

Use tool: supermemory_list
limit: 10

6. supermemory_forget

Delete a specific memory.

Parameters:

• memoryId (required): ID of memory to delete

Example:

Use tool: supermemory_forget
memoryId: "123456"

7. supermemory_profile

Get user profile facts and preferences.

Parameters:

• query (optional): Filter profile facts

Example:

Use tool: supermemory_profile
query: "editor"

Environment Variables

Workflow

Session Start (Automatic)

1. Generate user tag from KIMI_EMAIL (or USER)
2. Generate project tag from git remote URL (or directory name)
3. Fetch user profile with supermemory_profile
4. Get project context with supermemory_get_context
5. Inject [SUPERMEMORY] context with relevant memories

During Development (Agent-Driven)

When you make decisions or solve problems, the agent should:

Use tool: supermemory_add
content: "Decided to use PostgreSQL over MongoDB for transaction support"
metadata: { type: "conversation" }

Key Decision Points to Remember:

• Architecture choices and trade-offs
• Performance optimizations
• Bug solutions and root causes
• Technology preferences and anti-patterns

Automatic Memory Capture

The agent watches for keywords indicating the user wants something remembered.

Trigger Keywords

When the user says any of these, automatically save to memory:

• "remember", "memorize", "save this"
• "note this", "keep in mind"
• "don't forget", "learn this"
• "jot down", "make a note"
• "take note", "commit to memory"
• "remember that", "never forget"

Memory Nudge

When trigger keywords are detected, the agent should save the information:

[MEMORY TRIGGER DETECTED]
The user wants you to remember something. 

Use the unified supermemory tool:
- mode: "add"
- scope: "project" (for project-specific) or "user" (for cross-project preferences)
- type: appropriate category (preference, project-config, etc.)

What to Remember

Using the Unified Tool

For automatic captures, use the unified supermemory tool:

Use tool: supermemory
mode: "add"
content: "User prefers arrow functions over regular functions"
scope: "user"
type: "preference"

Scope selection:

• scope: "user" - Cross-project preferences (coding style, tools)
• scope: "project" - Project-specific knowledge (default)

Privacy Filter

All outgoing content is stripped of <private> tags:

<private>secret_key_here</private>
<private></private>

Examples:

• ❌ <private>API key is sk-12345</private> → Rejects (fully private)
• ✓ <private>API key is sk-12345</private> Use env vars instead → Saves (strips key)
• ✓ Use the .env file for secrets → Saves (no private tags)

Logs

Logs are written to ~/.kimi-supermemory.log:

[2026-02-05T14:00:00.000Z] [INFO] Kimi Supermemory MCP server starting
[2026-02-05T14:00:01.123Z] [INFO] Memory saved successfully (ID: abc123)
[2026-02-05T14:00:02.456Z] [WARN] Config file not found, using defaults
[2026-02-05T14:00:03.789Z] [ERROR] API request failed: Connection timeout

Log Levels:

• INFO: Normal operations
• WARN: Non-critical issues
• ERROR: Failures with data loss risk
• DEBUG: Verbose (only when config.debug = true)

Project Structure

kimi-supermemory/
├── mcp-server/
│   ├── src/
│   │   ├── server.js           # MCP server with 6 tools
│   │   ├── lib/
│   │   │   └── supermemory-client.js  # API client
│   │   ├── services/
│   │   │   ├── config.ts       # Configuration loader
│   │   │   ├── logger.ts       # Structured logging
│   │   │   ├── privacy.ts      # Privacy filtering
│   │   │   └── tags.ts         # Hash-based scoping
│   │   └── format-context.js   # Context formatting
│   ├── dist/
│   │   └── server.cjs          # Built server (CommonJS)
│   └── test/
│       ├── config.test.ts
│       ├── logger.test.ts
│       ├── privacy.test.ts
│       └── tags.test.ts
├── skill/
│   └── SKILL.md                # This file
└── install.sh                   # Installation script