Skip to main content
Nowledge MemNowledge Mem

Threads

Capture, browse, search, and distill conversations from any AI tool.

Threads are your conversation layer. They keep the original flow of what happened in an AI session: what you asked, what the tool answered, and how the work evolved.

Their real value is not just storage. Threads become useful when you can search past conversations, reopen exact context, and distill the durable parts into memories.

Use threads when you need the full history

If you need the original messages, save or import a thread. If you only need the durable takeaway, distill it into memories and work from there.

Import onboarding map

If you are deciding how to bring existing conversations in (bulk file vs coding-agent scan vs browser vs one markdown file), read Import existing conversations first. This page remains the format and feature reference for Threads.

The First Useful Thread

If you are new, do one of these first:

  • import one conversation you already care about
  • let one supported tool capture a full session
  • capture one web conversation through the browser extension

Then open that thread and distill one useful memory from it. That is the core workflow.

I want to...Jump to
See every import path in one overviewImport existing conversations
Browse and search threadsBrowsing Threads
Distill threads into memoriesThread Distillation
Auto-import from coding agentsAuto-Sync
Capture from web AI chatsBrowser Extension
Import my ChatGPT, Claude, DeepSeek, or other account historyBulk Import
Import a conversation file (.md with ## User/## Assistant headers)Single Thread
Learn the .md conversation formatConversation Markdown
Import via APIImport API
Import via CLICLI

Browsing Threads

The Threads view shows all your imported conversations in one place.

  • Search threads by content or title
  • Filter by source (Claude Code, ChatGPT, Cursor, etc.)
  • Pin important threads to keep them accessible
  • View individual messages within any thread

Open Threads from the sidebar or press Cmd + 3 (macOS).

Rename a saved conversation

A backend with Thread rename enabled can change a saved title while preserving the conversation ID, messages, source, links and Memory relationships. Use the CLI rename command or the REST endpoint. The server flag NMEM_THREAD_TITLE_UPDATE_ENABLED=1 is required and is off by default. This feature adds no App title editor.

For MCP, use thread_title_update only when your connected server advertises it. The tool description and input schema are the parameter reference. Supply the exact Thread ID, Space ID and storage ID from the same scoped Thread read. Existing threads:sync OAuth permission does not grant rename access. For a Cloud destination, use that destination's admitted MCP connection.

After a change, read the Thread again to confirm the title. Later sync and automatic review preserve your manual title. Search can update later; a pending Search repair does not mean the rename failed.

Thread Distillation

The key workflow that connects threads to memories. Open any thread and trigger distillation. The system extracts individual memories from the conversation, each with its own title, labels, and importance score. The extracted memories enter your knowledge graph and become searchable alongside everything else.

This is how hours of AI conversation become connected knowledge you can find later.

For normal-sized threads, distillation runs right away. For very large threads, Mem now offers Smart Background Distillation instead: it starts a few seconds later, lets the Knowledge Agent read the thread progressively, and then saves a smaller set of durable memories. This is slower than a short-thread distill, but much safer than forcing one foreground request to read everything at once.

Also from the browser

The browser extension supports Smart Distill directly from web conversations, so you can capture memories without importing the full thread first.

How Threads Reach Mem

Threads can enter Nowledge Mem through several different paths. They are related, but they are not the same:

  • Dedicated plugins and extensions: tool-specific integrations like Claude Code, Grok Build, Codex, Gemini CLI, OpenClaw, Hermes Agent, Alma, Cursor, Droid, OpenCode, Craft Agent, and Copilot CLI
  • Local discovery/backfill: in-app import for supported coding-agent conversations on the machine running Mem
  • Shared skills or prompt packs: reusable setups like npx skills
  • Browser capture: the Exchange extension works with the focused web session you use in the panel (not your full chat account); see Import existing conversations
  • Manual import: files, exports, API calls, and CLI imports

The main thing to understand is this:

  • Full session capture means Mem receives the actual recorded conversation from that tool
  • Handoff summary means Mem stores a concise continuation note instead of the full session

Shared skills matter here too. They are useful across many agents, but they cannot honestly promise full session capture unless that host runtime exposes readable session files or a stable transcript API.

Most users only need one rule:

  • if your tool already has a real thread-save path, use it
  • if it only supports handoff summaries today, keep that mental model clear and use import or nmem t sync for full history

Auto-Sync

In-App Discovery

Scan your machine for conversations from local coding assistants. No file export needed.

Local-only discovery

This path scans conversation files on the machine running Nowledge Mem. It is excellent for local sync, but it is different from nmem t sync --from ..., which reads local session files client-side and can still upload normalized threads to a remote Mem server.

What happens after the first import

Importing saves that conversation as a thread right away. If Auto-Sync is on, Mem can then append new messages to that thread, and it can remember the detected project for later sessions when that app exposes a stable project path.

ClientSync ModeWhere
Claude CodeAuto-discovery + incremental syncThreads → Import → Find AI Conversations
CursorAuto-discovery + incremental syncThreads → Import → Find AI Conversations
CodexAuto-discovery + incremental syncThreads → Import → Find AI Conversations
OpenCodeBackfill older sessions; new work is captured by the native pluginThreads → Import → Find AI Conversations
Proma ChatImport regular Proma Chat history from ~/.proma/conversationsThreads → Import → Find AI Conversations

Native Capture And Save Paths

Different integrations expose different thread-save behavior. Some support full session capture. Some auto-capture on lifecycle events. Droid and Cursor currently keep plugin handoff summaries separate from full conversation import.

IntegrationWhat it savesHow it worksSetup
Claude CodeFull session captureStop hook auto-saves the session after each response. Also supports explicit /save. nmem reads local session files client-side before upload.Claude Code guide
Grok BuildFull session captureGrok Build loads the shared Claude-compatible connector, but hooks route saves through nmem t save --from grok so the source and session format stay correct.Grok Build guide
Grok BotMCP memory accessGrok Bot is cloud-hosted. Use a public HTTPS MCP endpoint; its plugin and hook surfaces may be available in Bot or team settings, but a Bot-specific transcript contract is not verified for automatic full-thread capture.Grok Bot guide
Gemini CLIFull session capture plus separate handoff summarysave-thread imports the recorded Gemini session through nmem t save --from gemini-cli. The extension also imports before compression and at session end. save-handoff stays a separate resumable summary.Gemini CLI guide
DroidHandoff summary in the pluginThe Droid plugin intentionally exposes save-handoff, not save-thread. It provides Working Memory, routed recall, and resumable checkpoints now, while leaving transcript-backed thread save for a future real importer.Droid guide
CursorFull session capture plus handoff fallbackThe plugin's stop hook captures the current transcript when Cursor provides its path. save-thread, Mem desktop discovery, and nmem t sync --from cursor cover explicit, historical, or missed imports.Cursor guide
AlmaFull session captureLive sync saves conversations after 2 min idle, on thread switch, and on quit (on by default).Alma guide
OpenClawFull session captureCaptures every agent session automatically at completion, with optional LLM distillation.OpenClaw guide
Hermes AgentCompleted-turn capture with final boundary flushThe native memory provider writes cleaned user / assistant turns as replies complete, then flushes remaining changes on clean exit, /new, and /reset.Hermes guide
CodexFull session captureStop hook captures the recorded Codex session after each turn. Explicit save remains available as a fallback.Codex guide
Copilot CLIFull session captureCapture hooks append newly recorded Copilot conversation content into Mem after each response, before compaction, and at session end. Explicit save/checkpoint requests still create a concise summary thread when needed.Copilot CLI guide
PiFull session captureThe native Pi package syncs completed conversations automatically. Older local sessions can be imported with nmem t sync --from pi.Pi guide
OpenCodeFull session captureThe native plugin captures when OpenCode reports idle and flushes before compaction. nowledge_mem_save_thread remains an explicit fallback; older sessions can be imported with nmem t sync --from opencode.OpenCode guide
PromaAgent capture + Chat importProma Agent sessions are captured by Proma lifecycle hooks. Regular Proma Chat conversations are imported from local history with the app or nmem t sync --from proma.Proma guide
Craft AgentSource-guided memory + importCraft uses a workspace source and guide for MCP-backed memory behavior. Older local Craft sessions can be imported from session.jsonl files with nmem t sync --from craft-agent.Craft Agent guide
OMPPlugin auto-capture plus older-session backfillThe dedicated OMP plugin captures new conversations automatically. Older local OMP sessions can still be backfilled with nmem t sync --from omp. Do not use the Pi package as the OMP connector.OMP guide
Generic npx skills agentsHandoff summary onlyUse save-handoff. Shared skills can guide saving, but they do not control the host runtime well enough to promise transcript-backed import everywhere.Connectors overview

Full session capture vs handoff summary

If you need exact past conversation history, use a full-session capture or import path. Handoff summaries are for resumable continuity, not full conversation storage.

File Import

Bulk Import

In Threads → Import, choose Import account history. ChatGPT, Claude, DeepSeek, and the other supported vendor exports all use this same entry.

SourceFile FormatHow to Export
ChatGPTchat.html after extracting the downloaded ZIPChatGPT Settings → Data controls → Export data
ClaudeThe manifest-<id>.json from Claude's export email, or a downloaded export ZIP containing conversations.jsonclaude.ai or Claude Desktop: avatar → Settings → Privacy → Export data (Anthropic guide). Not available from Claude mobile apps.
DeepSeekdeepseek_conversations.jsonchat.deepseek.com → Settings → Data → Export data
ChatWise.zip (contains JSON files)Export all chats from ChatWise app
Almaalma-backup-YYYY-MM-DD.zip (contains threads.json)Alma Settings → Data → Export all threads
Raycast AI.json (e.g. raycast_ai_chats.json)No vendor export, so use raycast-ai-exporter on macOS (see that README)

Importing a Claude export manifest

Choose the manifest-<id>.json file first. Mem shows every ZIP named by the manifest. Download the files while signed in to Claude, then select the completed ZIPs in Mem. When the files are ready, you will see a conversation preview before importing them. Claude's download links expire after 24 hours; if a link has expired, request a new export. Your Claude sign-in stays in your browser. A self-hosted Mem server receives only the files you select.

Search first, extract when it matters

Bulk Import saves the original conversations as Threads. They are searchable immediately, so you do not need to distill hundreds of imported chats before Mem can find them. Distillation is the second step: use it for conversations that contain decisions, procedures, preferences, or lessons worth keeping as long-term Memories. For a large archive, plan extraction in small batches from the Timeline or by selecting specific threads.

Single Thread

Import one conversation from a file.

FormatFile TypeNotes
Conversation Markdown.md## User / ## Assistant / ## System headers, optional YAML frontmatter
Cursor.mdCursor's native export format (auto-detected)
Generic Markdown.mdAny markdown file, imported as a document

Documents vs. conversations

If your .md file is a regular document (no ## User / ## Assistant headers), it belongs in the Library, not Threads. Drag it into the Timeline or import from the Library view.

Conversation Markdown Format

The portable format for conversation import. Any tool that writes ## User / ## Assistant headers produces a file Nowledge Mem can read.

Minimal Example

The simplest valid file, two turns, no frontmatter:

## User

What is Python's GIL?

## Assistant

The Global Interpreter Lock (GIL) is a mutex in CPython that allows only one thread to execute Python bytecode at a time. This means CPU-bound multi-threaded programs won't see speedups from threading: use multiprocessing or async I/O instead.

Full Example

With optional YAML frontmatter and a system message:

---
title: Python Async Patterns
source: chatgpt
date: 2025-06-15
---

## System

You are a senior Python developer who explains concepts clearly.

## User

How does async/await work in Python?

## Assistant

Python's `async`/`await` lets you write concurrent code that doesn't block while waiting for I/O. An `async def` function returns a coroutine, and `await` pauses it until the result is ready, meanwhile other coroutines can run.

## User

When should I use asyncio vs threading?

## Assistant

Use **asyncio** for I/O-bound work (HTTP requests, database queries, file reads): it's lighter and scales better than threads. Use **threading** when you need to call blocking libraries that don't support async. Use **multiprocessing** for CPU-bound work.

Format Rules

  • Headers: ## User, ## Assistant, or ## System, level-2 heading, one per message
  • Content: Everything between headers is one message. Markdown formatting, code blocks, and lists are preserved as-is
  • Frontmatter: Optional YAML block at the top. Supported fields: title, source, date, all optional
  • Detection: Files with at least one ## User or ## Assistant header are recognized as conversations automatically
  • Fallback: Files without recognized headers are imported as a single document message
  • Case: Role names are matched case-insensitively (## user and ## User both work)

Import API

POST /threads/import accepts JSON messages or Conversation Markdown, with single and batch modes.

Single Thread (JSON messages)

curl -X POST http://127.0.0.1:14242/threads/import \
  -H "Content-Type: application/json" \
  -d '{
    "title": "My Conversation",
    "source": "chatgpt",
    "messages": [
      {"role": "user", "content": "Hello!"},
      {"role": "assistant", "content": "Hi there! How can I help?"}
    ]
  }'

Single Thread (Markdown)

curl -X POST http://127.0.0.1:14242/threads/import \
  -H "Content-Type: application/json" \
  -d '{
    "markdown_content": "## User\n\nHello!\n\n## Assistant\n\nHi there! How can I help?"
  }'

Batch Import

curl -X POST http://127.0.0.1:14242/threads/import \
  -H "Content-Type: application/json" \
  -d '{
    "threads": [
      {
        "title": "Thread 1",
        "messages": [
          {"role": "user", "content": "Hello"},
          {"role": "assistant", "content": "Hi"}
        ]
      },
      {
        "title": "Thread 2",
        "markdown_content": "## User\n\nGoodbye\n\n## Assistant\n\nSee you!"
      }
    ]
  }'

Thread IDs are auto-generated when omitted. Titles are inferred from markdown frontmatter when available.

CLI

The nmem CLI supports thread import from files, JSON, or stdin.

# Import a conversation markdown file
nmem t import --file conversation.md

# Import with explicit title and source
nmem t import --file chat.md --title "Python Async" --source chatgpt

# Import from JSON messages
nmem t import --messages '[{"role":"user","content":"Hello"},{"role":"assistant","content":"Hi"}]'

# Bulk JSON from Raycast AI (raycast-ai-exporter output)
nmem t import --file ~/Desktop/raycast_ai_chats.json

# Pipe markdown from stdin
cat conversation.md | nmem t import --stdin --title "Piped Conversation"

Run nmem t import --help for all options. See the CLI Reference for the full command list.

Browser Extension

The Nowledge Mem Exchange extension works in the browser on supported AI chat pages, on the session you are actually using with the extension (for example the tab you open in the side panel). It is not a bulk downloader for your entire web chat history; for that, use each vendor’s export plus Bulk import in Mem, or see Import existing conversations. Auto-capture, manual distill, and backing up the current thread are covered in the Browser Extension guide.

MCP Tools

ToolWhat it does
thread_searchSearch threads by keywords or list recent threads
thread_fetch_messagesFetch full messages from a specific thread
search_thread_messagesSearch within a thread for messages matching keywords

MCP thread tools search and read threads that already exist in Mem. To capture local coding-agent transcripts, use the native connector for that tool. To backfill older sessions, run nmem t sync --from <source> on the client machine running the agent. Supported sources include claude-code, codex, craft-agent, cursor, gemini-cli, grok, hermes, kimi-code, kimi-work, mimo-code, omp, opencode, and pi. That keeps transcript discovery local and uploads the normalized thread to your Mem server.

Next Steps

  • Memories: What happens after distillation: create, search, and organize knowledge
  • Library: Import documents alongside your memories
  • Browser Extension: Capture conversations from web AI platforms
  • Connectors: Connect your AI tools through native connectors, reusable packages, or MCP
  • API Reference: Full REST API documentation

On this page