fix/chunk-embed

[bernoussama]

Summary

• fix local semantic embedding for entries longer than the GGUF embedding context by chunking and averaging vectors
• add explicit clanker local search for local SQLite search without CLANKER_MODE=local
• extend unit and e2e coverage for long pending/immediate local embeddings
• bump @clankeroverflow/cli to 1.2.1

Validation

• pnpm run lint (passes with existing warnings)
• pnpm run format
• pnpm --filter @clankeroverflow/cli test -- --runInBand
• pnpm --filter @clankeroverflow/cli check-types
• pnpm --filter @clankeroverflow/cli build
• node packages/cli/e2e/local-mode.mjs
• pnpm test:e2e:local (Docker matrix: Node 22 and Node 24)
• git diff --check

Summary by CodeRabbit

Release Notes

• New Features

  • Added clanker local search subcommand to query the local SQLite database directly.

• Documentation

  • Expanded documentation for private local mode, including local semantic search enablement, configuration options, and environment variables for database and model path customization.

• Version

  • Bumped to version 1.2.1.

[coderabbitai]

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: a95fe0ca-ec2b-440e-ae84-dd456e72d498

📥 Commits

Reviewing files that changed from the base of the PR and between b9f0581 and 7a77cf2.

📒 Files selected for processing (13)

• README.md
• packages/cli/.claude-plugin/plugin.json
• packages/cli/.codex-plugin/plugin.json
• packages/cli/e2e/local-mode.mjs
• packages/cli/openclaw.plugin.json
• packages/cli/package.json
• packages/cli/skills/clankeroverflow-cli/SKILL.md
• packages/cli/skills/clankeroverflow-mcp/SKILL.md
• packages/cli/src/index.test.ts
• packages/cli/src/index.ts
• packages/cli/src/mcp/local-backend.test.ts
• packages/cli/src/mcp/local-semantic.test.ts
• packages/cli/src/mcp/local-semantic.ts

---

Walkthrough

Version 1.2.1 adds token-chunked weighted-average embedding for long local solutions in local-semantic.ts (bumping the format version to solution-v2), refactors shared search argument parsing into internal helpers in index.ts, and introduces a new clanker local search subcommand that queries the local SQLite database directly. Tests, e2e fixtures, and documentation are updated throughout.

Changes

Local mode v1.2.1: chunked embedding + local search

Layer / File(s)	Summary
Token-chunked embedding core packages/cli/src/mcp/local-semantic.ts	Bumps LOCAL_EMBEDDING_FORMAT_VERSION to solution-v2, adds EmbeddingVector/EmbeddingContext/EmbeddingModel internal types, exports maxEmbeddingChunkTokens, chunkEmbeddingTokens, weightedAverageEmbeddingVectors, and embedTextWithTokenChunks, and updates createLocalEmbedder to route through the new chunked path with an explicit contextSize.
Token-chunked embedding and backend tests packages/cli/src/mcp/local-semantic.test.ts, packages/cli/src/mcp/local-backend.test.ts	New local-semantic.test.ts suite verifies each chunking and weighted-averaging helper with mocked model/context. Two new local-backend.test.ts cases verify immediate embedding of long solutions and deferred embedPending() draining.
local search subcommand and shared search helpers packages/cli/src/index.ts	Extracts parseSearchLimit, parseSearchMode, and searchAndPrint as internal helpers. Refactors the top-level search command to use them, and adds a new clanker local search subcommand accepting --db, --limit, and --mode that constructs a LocalBackend and invokes searchAndPrint.
Unit and e2e tests for local search packages/cli/src/index.test.ts, packages/cli/e2e/local-mode.mjs	index.test.ts adds a node-llama-cpp vitest mock and two new local search tests (explicit DB without CLANKER_MODE; semantic mode). local-mode.mjs adds longPending/longImmediate fixtures, updates assertion counts, and verifies local search without CLANKER_MODE.
Docs updates and version bumps README.md, packages/cli/skills/.../*.md, packages/cli/package.json, packages/cli/*.plugin.json, packages/cli/.*/plugin.json	README and both SKILL.md files document clanker local search, clanker local embed, and env var overrides. All version fields are bumped from 1.2.0 to 1.2.1.

Sequence Diagram(s)

sequenceDiagram
  participant User
  participant CLI as clanker local search
  participant parseHelpers as parseSearchLimit / parseSearchMode
  participant LocalBackend
  participant searchAndPrint
  participant localSemantic as embedTextWithTokenChunks

  User->>CLI: clanker local search "query" --db ./db --mode semantic
  CLI->>parseHelpers: parse --limit, --mode
  CLI->>LocalBackend: construct(localConfig, semanticConfig)
  CLI->>searchAndPrint: query, limit, mode, allowHybridFallback=false
  searchAndPrint->>LocalBackend: searchWithAutoFallback(query, limit, mode)
  LocalBackend->>localSemantic: embedTextWithTokenChunks(model, context, query, dims)
  localSemantic->>localSemantic: tokenize → chunkEmbeddingTokens → getEmbeddingFor × N → weightedAverageEmbeddingVectors
  localSemantic-->>LocalBackend: float32 embedding buffer
  LocalBackend-->>searchAndPrint: results[]
  searchAndPrint-->>User: formatSearchResults output

Loading

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Possibly related PRs

• bernoussama/clankeroverflow#62: Introduced the async createLocalEmbedder flow in local-semantic.ts and local-backend.ts that this PR further refactors to add token-chunked weighted-average embedding.

Poem

🐇 Hop, hop, chunking text so long,
No embedding overflow shall go wrong!
I split the tokens, average with care,
Then local search finds answers anywhere.
Version bumped to v1.2.1 — done! 🎉

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix/chunk-embed

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}