Feature Request: Support Remote MCP Client for thread_persist

[ferstar]

Summary

The thread_persist tool currently assumes the MCP client runs on the same machine as the Nowledge Mem server, making it impossible for remote MCP clients to save conversation threads.

Current Behavior

The thread_persist tool requires a project_path parameter pointing to the local directory where session files are stored:

thread_persist(
    client="claude-code",
    project_path="/home/user/projects/myapp",  # Local filesystem path
    persist_mode="current"
)

Problem: When the MCP server runs on a remote machine (e.g., accessed over network via Tailscale/VPN), the server cannot access the client's local filesystem paths, making thread persistence impossible.

Use Case

Scenario:

• Nowledge Mem MCP server runs on Machine A (home server, always-on)
• User works from Machine B (laptop) via VPN/Tailscale
• User wants to persist conversation threads from Claude Code/Codex running on Machine B

Current limitation: The server on Machine A cannot read session files from Machine B's filesystem at paths like /home/user/.claude/sessions/.

Proposed Solutions

Option 1: Accept Session Content Directly (Recommended)

Add a new parameter to accept session file content instead of requiring a file path:

thread_persist(
    client="claude-code",
    session_content="<actual session JSON/data>",  # New parameter
    summary="Discussion about implementing auth",
    # No project_path needed
)

Benefits:

• Works seamlessly for both local and remote clients
• Client can read session files locally and pass content to server
• Backward compatible (keep existing project_path parameter)

Option 2: File Upload Endpoint

Provide a separate endpoint for clients to upload session files:

# Step 1: Upload session file
upload_session(
    client="claude-code",
    session_file_content="...",
    filename="session-2025-11-09.json"
)

# Step 2: Persist uploaded session
thread_persist(
    client="claude-code",
    session_id="uploaded-session-id",
    summary="..."
)

Option 3: Client-Side Helper Tool

Provide a client-side MCP tool that:

1. Reads local session files
2. Calls the server's thread_persist with content payload
3. Acts as a bridge between local filesystem and remote server

Implementation Considerations

Backward Compatibility

• Keep existing project_path parameter for local deployments
• Auto-detect: if session_content is provided, use it; otherwise fall back to project_path

Security

• Validate and sanitize session content
• Set reasonable size limits (e.g., 10MB per session)
• Optional: compress large session data

API Design

{
  "method": "thread_persist",
  "params": {
    "client": "claude-code",
    
    // Option A: Local filesystem (current)
    "project_path": "/home/user/projects/myapp",
    "session_id": "optional-session-id",
    
    // Option B: Direct content (new)
    "session_content": {
      "messages": [...],
      "metadata": {...}
    },
    
    // Common parameters
    "summary": "Brief summary",
    "persist_mode": "current",
    "truncate_large_content": false
  }
}

Workarounds (Current)

The only current workaround is to:

1. Run Nowledge Mem locally on each client machine, OR
2. Manually copy session files to the server machine before calling thread_persist

Both workarounds defeat the purpose of centralized knowledge management.

Related Issues

• #6 - Configurable Network Binding (enables remote access scenarios)
• #5 - Authentication Support (secures remote access)

Priority

P1 (High): This feature is essential for remote/multi-device workflows, which are core use cases for a centralized knowledge management system.

Willingness to Contribute

I'd be happy to help test this feature or provide sample session file formats for different clients.

---

Environment:

• Nowledge Mem Version: 0.4.9
• MCP Clients: Claude Code 2.0.36, Codex CLI
• Network Setup: Remote server on Tailscale (100.64.0.184)
• Current Limitation: Cannot persist threads from remote clients

[ferstar]

Solution: mem-persist Skill

I've implemented a client-side solution to solve this remote MCP client problem: mem-persist

How It Works

This Claude Code skill implements Option 1 from the proposed solutions - it reads session files locally and sends the content via HTTP API to the remote Nowledge Mem server:

┌─────────────────┐      HTTP POST /threads       ┌──────────────────┐
│  Client Machine │ ───────────────────────────► │  MCP Server      │
│  (Laptop)       │      with JSON payload        │  (Remote)        │
│                 │                                │                  │
│  1. Read local  │                                │  4. Store in     │
│     session     │                                │     database     │
│  2. Convert to  │                                │                  │
│     API format  │                                │  5. Build graph  │
│  3. Send via    │                                │                  │
│     HTTP API    │                                │  6. Index for    │
│                 │                                │     search       │
└─────────────────┘                                └──────────────────┘

Key Features

• ✅ Pure Python implementation - No shell scripts, uses Click CLI + uv
• ✅ Client-side execution - Runs on laptop, has direct filesystem access
• ✅ HTTP API integration - Sends session content to /threads endpoint
• ✅ Automatic session discovery - Handles Claude Code's path encoding rules
• ✅ Zero-config - Works out of the box with sensible defaults
• ✅ Built-in diagnostics - Troubleshooting tool included

Installation & Usage

Install as Claude Code skill:

git clone https://github.com/ferstar/mem-persist.git ~/.claude/skills/mem-persist

Save current session:

uv run python -m mem_persist save

With custom title:

uv run python -m mem_persist save --title "Implemented auth feature"

Configuration (optional .env file):

MEM_API_URL=http://your-server:14243
MEM_AUTH_TOKEN=your-token-here
MAX_MESSAGES=0  # 0 = unlimited

Why This Approach?

This skill solves the remote client problem without requiring server-side changes by:

1. Running locally where session files exist
2. Reading and parsing Claude Code session files (.jsonl format)
3. Converting to Nowledge Mem API format
4. Sending via HTTP API (works over any network: LAN, VPN, Tailscale)

Architecture Highlights

Session Discovery:

• Handles Claude Code's path encoding: /. → --, / → -
• Example: /home/user/.claude/skills → -home-user--claude-skills
• Automatically finds latest session file by modification time

API Request Format:

{
  "thread_id": "project_20251110_142918",
  "title": "Auto-generated or custom",
  "messages": [
    {"role": "user", "content": "...", "timestamp": "..."},
    {"role": "assistant", "content": "...", "timestamp": "..."}
  ],
  "participants": ["user", "claude"],
  "source": "claude-code",
  "project": "project-name",
  "workspace": "/absolute/project/path",
  "metadata": {...}
}

Extensibility

The implementation is modular and can easily support other AI coding tools (Cursor, Codex, etc.) by:

1. Adding new path patterns in session.py
2. Supporting different session file formats
3. Updating source field for tool identification

Status

✅ Production ready - v1.0.0 released, tested with remote Nowledge Mem server over Tailscale

This solution demonstrates that client-side session reading + HTTP API is a viable approach for remote MCP clients. While server-side support for session content (Option 1 from proposals) would be ideal for broader ecosystem adoption, this skill proves the concept works effectively.

Let me know if this helps or if you'd like me to contribute to server-side implementation!

[wey-gu]

Amazing work!