clipmem 0.4.1

macOS clipboard memory backed by SQLite and searchable from agent runtimes
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123

# Contributing

clipmem is a Rust CLI with a native SwiftUI macOS frontend. The
codebase is structured to make extension straightforward — export
commands, embeddings, OCR, richer source-app heuristics, and fuller
HTML parsing all fit the existing shape.

## Project layout

```
src/                           Rust source
  main.rs                      CLI entry point
  cli.rs                       Argument parsing (clap) and command dispatch
  cli/commands/                Command implementations
  cli/output/                  Output formatting (text, JSON, JSONL, MD, TOON)
  cli/service/                 Service and setup management
  cli/db_path.rs               Database path resolution
  db.rs                        Database connection and retrieval logic
  db/schema.sql                SQLite schema (tables, indexes, triggers, FTS5)
  db/store/                    Insertion and storage logic
  db/read/                     Query and search logic
  capture.rs                   Public capture facade
  model/                       Data structures
    clipboard.rs               ClipboardSnapshot, ClipboardItem, ClipboardRepresentation
    archive.rs                 SearchHit, TimelineEvent, CaptureEvent, SnapshotDetails
    kinds.rs                   ClipboardKind, SnapshotKind enums
    text_projection.rs         FlattenedTextProjection, TextFragment
    builders.rs                Snapshot, item, and representation builders
  platform/
    macos.rs                   NSPasteboard capture, restore, app detection via objc2
    unsupported.rs             Stubs for non-macOS platforms
  app.rs                       Watch state and capture line formatting
  sensitive.rs                 API key filter heuristics
  archive.rs                   Public archive facade

macos/ClipmemMenuBar/          Native SwiftUI menu bar app and Swift Testing suite

tests/
  cli_commands/                CLI integration tests
  database_roundtrip.rs        Schema and serialization tests
  skill_parity.rs              Agent skill package verification

skills/clipboard-memory/       Canonical public skill content
extras/openclaw/               OpenClaw-native skill package
extras/hermes/                 Hermes Agent-native skill package
extras/agent-skills/           Portable skill package mirror
extras/launchd/                LaunchAgent plist template

scripts/
  build_and_run_menubar.sh     Build Rust + SwiftUI app and launch
  clawhub_skill_sync.py        Check and publish the clipboard-memory skill on ClawHub
  install_launchagent.sh       Compatibility wrapper for clipmem setup
  uninstall_launchagent.sh     Compatibility wrapper for clipmem service uninstall
  install_openclaw_skill.sh    Compatibility wrapper for clipmem agents openclaw install-skill
```

## Platform gating

Clipboard capture is gated behind `cfg(target_os = "macos")`. The
database, search, and test layers compile on other platforms for
development, but actual capture and restore only work on macOS.

## Build and test

Build the Rust CLI (requires Rust 1.88+):

```bash
cargo build --release
```

Run the local validation suite before opening a PR:

```bash
cargo fmt --all --check
cargo clippy --all-targets --all-features -- -D warnings
python3 scripts/check_file_lengths.py
cargo test
```

The file-length lint checks tracked Rust, Swift, and Rust test files. The
default ceiling is 800 lines, with explicit per-file overrides in
`file-length-limits.json` when necessary. Treat those overrides as a ratchet,
not a free pass.

The CI workflow hard-fails on formatting, Clippy, the file-length lint, tests,
and crate packaging checks, so running the same commands locally keeps review
cycles short.

The CLI integration tests in `tests/cli_commands/` exercise every command,
flag combination, filter, and output format.

## Build and test the menu bar app

Build and launch the development app from the repo root:

```bash
scripts/build_and_run_menubar.sh
```

Or build and test directly with `xcodebuild`:

```bash
xcodebuild -project macos/ClipmemMenuBar/ClipmemMenuBar.xcodeproj \
  -scheme ClipmemMenuBar -configuration Debug \
  -derivedDataPath macos/ClipmemMenuBar/DerivedData build

xcodebuild -project macos/ClipmemMenuBar/ClipmemMenuBar.xcodeproj \
  -scheme ClipmemMenuBar -configuration Debug \
  -derivedDataPath macos/ClipmemMenuBar/DerivedData test
```

## Release workflow

See [RELEASING.md](../RELEASING.md) for the full release workflow,
including tag-driven builds, GitHub Actions CI, Homebrew formula
updates, and crates.io publishing.

## Next steps

- [Architecture](architecture.md) — understand the capture model,
  storage design, and search strategy
- [Command reference](command-reference.md) — exhaustive flag-level
  reference