Advice Overall On Roadmap

[anthony-maio]

Checked for Existing Issues?

• Yes, I have checked existing issues and cannot find one related to this.

Software

Desktop Application

Operating System / Platform

Windows

Your Pieces OS Version

11

Early Access Program

• Yes, this is related to an Early Access Program feature.

Kindly describe the bug and include as much detail as possible on what you were doing so we can reproduce the bug.

As a Senior Software Engineer with 20 years of experience, I initially approached this product as a potential solution for managing high-volume context switching across multiple projects. However, after extensive testing on a high-end workstation (i9-13900KF, 64GB RAM, RTX 4080 + 2x3090), I encountered severe stability issues that degraded my system's performance to the point of usability failure.

Below is a detailed breakdown of the architectural flaws I observed, along with constructive feedback on product direction and system design.

1. Product Direction: Feature Bloat vs. Core Utility

The current marketing positioning as a "Developer Tool" for snippets and drive storage feels misaligned with the actual pain points of senior engineers.

• The "Clipboard Manager" Trap: Marketing an "AI-powered clipboard manager" undersells the potential value. Tools like Claude Code or existing snippet managers already saturate this space.
• The Real Value Proposition: The "Killer App" here is not snippet storage; it is Context Management. For a developer juggling 15+ active projects, the ability to automatically track and recall what I was working on is invaluable.
• Implementation Friction: The onboarding experience is fragmented. The VS Code extension prompts for a core platform installation but leads to a documentation loop rather than a seamless install.

2. Performance & Stability: Resource Contention

The application exhibits behavior characteristic of unmanaged resource contention, effectively acting as a denial-of-service on the local machine.

• Hardware Impact: On a machine specifically built for heavy AI/ML workloads, the application caused system-wide lag and instability so severe I initially diagnosed it as a CPU hardware failure.
• Stability: In contrast to a compiled Rust/C# implementation, the current Python-heavy architecture struggles to maintain stability under load, leading to lockups and dropped data.

3. Architectural Deep Dive: The Data Layer (Couchbase Lite)

The decision to use Couchbase Lite (CBL) as the primary persistence layer on a desktop application is the root cause of the performance issues.

• Architectural Mismatch: CBL is designed for mobile devices (iOS/Android) to handle offline-first sync over unstable networks. It is not optimized for high-frequency, high-throughput desktop telemetry.
• The Serialization Tax: Every system event (mouse move, focus switch) appears to be marshaled from the OS hook -> Python -> JSON Document -> CBL Native Interop -> Disk. This pipeline incurs massive CPU overhead for data that should be trivial to store.
• Memory Usage: I observed memory consumption exceeding 7GB. This suggests the native C++ library backing CBL is struggling with object graph retention or replicator overhead.
• Data Model Friction: Telemetry is Time-Series Data, not Document Data. Forcing linear event logs into a NoSQL document store requires aggressive indexing and compaction (MVCC), creating I/O jitter that manifests as IDE lag.
• Inference: It appears CBL was chosen to simplify backend synchronization (Sync Gateway) at the expense of local runtime performance. This is a "Sync-First" optimization that penalizes the user's immediate experience.

4. System Design: Process & Language Choices

The application attempts to run OS-level hooks, API servers, and AI workloads within a monolithic or tightly coupled architecture that fights the operating system rather than working with it.

• Language Choice for OS Hooks: Using Python for low-level Windows hooks (Win32 API) is inefficient due to the GIL and lack of first-class OS primitives.
• The "Monolith" Problem: Running global hooks (Keyboard/Mouse) in the same process loop as heavy AI summarization or data persistence is dangerous. If the AI worker stalls or GC pauses, the OS hook callback times out, breaking the clipboard chain or locking the input queue.
• Local Microservices Overhead: While a local HTTP/Websocket architecture is flexible, it introduces unnecessary latency for local IPC.
• Operational hygiene:
• Port Discovery: The reliance on random ports or varied default ports (1000 vs 5323) without a deterministic discovery file makes integration brittle.
• Logging: I discovered an on-device log folder exceeding 377 GB. This indicates a lack of log rotation policies, compression, or retention caps.

5. Constructive Recommendations

To fix these issues on Windows, the system requires decomposition into hard boundaries based on workload characteristics.

A. Decompose the Architecture
Do not run OS hooks and AI workloads in the same process.

1. Collectors (The "Fast" Lane): Tiny, native binaries (Rust or C#) responsible only for capturing events (Clipboard, Window, Input). These should push data to an IPC channel immediately and return control to the OS.
2. Core Daemon (The "Data" Lane): A background service that normalizes, deduplicates, and batches data for persistence.
3. AI Workers (The "Slow" Lane): Separate processes for embeddings and summarization, managed with strict resource budgets (CPU affinity, memory caps).

B. Appropriate Technology Stack

• Windows Collectors: Use .NET/C# (Native AOT) or Rust. Use AddClipboardFormatListener and UIAutomation rather than global hooks where possible to avoid locking the system.
• Persistence: Move high-velocity telemetry to SQLite (WAL mode) or memory-mapped files. Reserve the Document store/Vector DB for the resulting high-value summaries, not the raw firehose.

C. Governance & Budgeting

• Backpressure: Implement ring buffers for event capture. If the consumer falls behind, drop events rather than crashing the system.
• Resource Caps: Enforce hard limits on memory and CPU usage per worker.
• Batching: Aggressively batch embeddings and database writes. Do not write to disk on every mouse click.
• Cloud vs. Local: Provide an option to offload AI processing to the cloud. Local-only privacy is a valid feature, but not if it renders the machine unusable.

This is an AI generated summary of my overall concerns.

[pieces-support-bot]

Hi @anthony-maio - Thank you so much for creating this issue. Your issue has been automatically triaged and routed to the proper Pieces team member. Look for a follow-up within the next 24 hours.

In the meantime, please check out these helpful resources:

• Existing Issues: https://github.com/pieces-app/support/issues
• Documentation: https://docs.pieces.app
• YouTube Channel: https://www.youtube.com/@getpieces

We appreciate your patience and contribution to making Pieces better!

[robert-at-pieces]

@anthony-maio

Thank you for your detailed analysis and feedback. Such feedback is valuable and the summary is accurate in the majority of instances.

Many of the suggestions are currently on the roadmap and a few are in active development.

That being said I would like to clarify some of the cases where the suggestions offered may be operating under incorrect assumptions:

1. OS Hooks: The language of choice for OS hooks is not Python. Pieces OS utilizes purpose built native libraries compiled with Rust and use flutter-rust bridge to stream the obtained results to Pieces.

   • This is Phase 1 of the transition to decoupling our data ingestion sources from the "monolith" as you have suggested, but such refactors take time.

2. Port Discovery: There is absolutely room for improvement in this area. However, some of the suggestions need clarification and context:

   • Pieces does use a deterministic port file. You can find it located in C:\Users\<your username>\AppData\Local\Mesh Intelligent Technologies, Inc\Pieces OS\com.pieces.os\production\Config\.port.txt
   • Pieces no longer uses the varied default ports (1000 vs 5323). You may have come across these while exploring the code as they exist as the legacy ports to ensure backwards compatibility and prompt users for updates.
   • The "port scan" resolution, though far from ideal, originated from uses cases where plugins were accessing Pieces OS on the host machine through "remote" VSCode instances using WSL or docker through a bridge network without access to the host disk to read the configuration file.

3. Logging: As you suspected in a previous support ticket, the unacceptably large support folder is a result of a developer flag making its way to production. An automatic cleanup of the unnecessary information is being released with the next patch. No excuses here. This should not have happened and we failed in this instance. Additional safeguards are being put in place so this does not happen in the future.

---

As we implement refactors, improvements, and refine Pieces to focus on the "Core Utility" I hope that one day you will give Pieces another shot.
Thank you again, Anthony, for this incredibly detailed and insightful architectural review

[mark-at-pieces]

Thanks for the detailed feedback and analysis — really appreciate you taking the time.

If you’re willing, I’d love to set up a quick call to discuss your experience with Pieces and some of your goals with the product, as well as introduce you to a few key team members. Would be great to open a direct communication channel as well.

Calendar link:
https://calendar.app.google/WVUDtUfNy5Vst3sH7

[tsavo-at-pieces]

Spot on @anthony-maio our evolution has been quite and I'll admit we haven't done the best and updating our growth materials and storytelling but we will fix that here on the back half of January once our LTM-3.0 release is official out! (LTM = Long Term Memory). Decembers release was largely a precursor to LTM-3; that said, we're almost there!

Nevertheless, would love to connect directly @anthony-maio perhaps @mark-at-pieces, @robert-at-pieces, @brian-at-pieces and @mack-at-pieces could join as well. Will shoot over an email to you now!