cliwant-memory-tiers

name

cliwant-memory-tiers

description

Three-tier persistent memory (digest / working-set / long-term vector) for any Claude / Codex / Gemini session. Records the user's preferences, decisions, and project facts so they survive across sessions. Backed by the @cliwant/mcp-memory-tiers MCP server. Triggers on phrases like "remember this", "what did we decide about", "기억해줘", "覚えておいて", or whenever Claude needs persistent memory beyond the current session.

cliwant-memory-tiers

A Claude Code skill that wraps the @cliwant/mcp-memory-tiers Model Context Protocol server. Provides three-tier persistent memory (digest / working-set / long-term) accessible from any Claude / Codex / Gemini session.

When to use this skill

Use this skill (and call its underlying MCP tools) whenever:

1. The user asks to remember something — "remember this", "기억해", "覚えて", "save this for later"
2. The user references past context — "what did we decide", "지난번에 어떻게 했지", "前回どうだった"
3. The user changes a preference — "from now on always X", "이제부터 X로", "今後は X で"
4. You're starting a new session and want to load relevant prior context
5. You finished a meaningful sub-task and the takeaway should outlast the chat

Do not use this skill for trivia or facts that are common knowledge — only for things specific to this user, project, or context that wouldn't survive the next session otherwise.

Prerequisite: install the MCP server

The skill calls into MCP tools provided by @cliwant/mcp-memory-tiers. Make sure the MCP server is configured in your host (Claude Desktop, Claude Code, Codex CLI, Gemini CLI, Cursor, Cline, etc.).

Quick install (Claude Desktop / Claude Code)

Add to ~/.claude/claude_desktop_config.json (macOS / Linux) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "memory-tiers": {
      "command": "npx",
      "args": ["-y", "@cliwant/mcp-memory-tiers"],
      "env": {
        "CLIWANT_EMBEDDING": "openai",
        "OPENAI_API_KEY": "sk-..."
      }
    }
  }
}

Restart the host. The eight tools (store_context, retrieve_relevant, get_digest, set_active_digest, get_working_set, update_context, delete_context, get_context) become available.

Workflow patterns

1. Recording a preference

When the user says something like "from now on always use 2 spaces, not tabs":

Call: store_context
Args: {
  "topic": "<project or user id>",
  "tier": "long_term",
  "title": "Indent style",
  "content": "User prefers 2-space indentation, not tabs.",
  "tags": ["preference", "code-style"],
  "pinned": true
}

pinned: true ensures this preference is the first thing returned on every retrieval — it survives the rolling digest.

2. Recording a decision

When the user explicitly decides something ("we'll use Postgres, not MySQL"):

Call: store_context
Args: {
  "topic": "<project id>",
  "tier": "long_term",
  "title": "Database choice — Postgres",
  "content": "Decided 2026-04-29: project will use Postgres because of pgvector requirements.",
  "tags": ["decision", "architecture"],
  "pinned": false
}

3. Loading context at session start

At the start of any session where you might need prior memory:

1. Call: get_digest({ topic: "<project id>" })
   → loads the rolling summary
2. Call: get_working_set({ topic: "<project id>", limit: 8 })
   → loads recent raw facts
3. Call: retrieve_relevant({
     topic: "<project id>",
     query: "<the user's first message>",
     limit: 6
   })
   → pulls the most semantically-relevant long-term entries

Then inject the results into your reasoning. If digest + working_set + retrieve_relevant return nothing, you're working with a fresh topic — ask the user what they're working on.

4. Compacting on demand

When the working_set has grown large (say, > 30 entries) or the user explicitly asks "summarize what we've done":

1. Read working_set + recent long_term entries
2. Author a 200-400 word summary covering: ongoing concerns, settled
   decisions, recurring patterns, scheduled work, open questions
3. Call: set_active_digest({
     topic: "<project id>",
     title: "Rolling digest — <date>",
     content: "<summary>"
   })

The previous active digest is automatically archived (kept in long_term with the archived tag) so audit history is preserved.

5. Searching for past context

When the user asks "what did we decide about X":

Call: retrieve_relevant({
  topic: "<project id>",
  query: "X",
  limit: 5
})

Cite the matched entries verbatim (with their stored title) so the user can verify what's recalled vs. what's the model's guess.

Topic naming convention

Pick a stable identifier that scopes memory cleanly:

• Per-user: user/<email or id> — survives across all that user's projects
• Per-project: project/<repo-name> — useful for IDE / coding agents
• Per-client (B2B): client/<id> — used in CRM / accounting agents
• Per-session: session/<uuid> — short-lived, won't survive a restart

The topic is your isolation boundary. Cross-topic retrieval is impossible by API design — request it only when you need the explicit isolation guarantee.

Multi-language

This skill responds to memory-related triggers in English, Korean (한국어), and Japanese (日本語). The MCP server itself is language-agnostic — what you store is what you retrieve.

English	Korean	Japanese
"remember this"	"이거 기억해줘"	"これを覚えて"
"what did we decide"	"뭐로 결정했지"	"何を決めた"
"from now on always"	"이제부터 항상"	"今後は常に"
"summarize what we've done"	"지금까지 한 거 요약"	"今まで何をしたか要約"

Privacy

• All memory lives on the user's machine by default (~/.cliwant/memory.db).
• Postgres mode points at the user's own DB — nothing is sent to cliwant servers.
• Topic isolation is enforced at the storage layer; cross-topic queries don't exist in the API.

License

MIT — same as the underlying npm package. See @cliwant/mcp-memory-tiers.