feat(skills): add moon-agent skill for driving Moon from an AI agent - #749
Merged
Conversation
Moon covers what an agent normally needs three services for: scratch state
(KV + TTL), semantic recall (FT.* vector search), relations (Cypher graph),
full-text, and events (pub/sub). Nothing in the repo told an agent how to use
any of it — the SDK README shows a quick start, but not the failure modes, and
several of them are silent rather than loud.
The skill has two modes. OPERATE covers bringing an instance up (always pass an
explicit --dir; an empty one means CWD and reloads stale indexes), choosing
--shards, health-checking that the listener is actually Moon and not a stray
redis-server, and shutting down with a bounded wait plus a kill -9 fallback.
USE covers the five SDK namespaces with the constraints that are not guessable
from the signatures.
Every flow was executed against a live moon 0.8.7 before being written down,
which is how the constraints were found rather than assumed:
- vector FILTER expressions work only at --shards 1; a multi-shard instance
answers "FILTER not supported in multi-shard mode yet"
- the text index schema is a sequence of (name, type, opts) tuples, not a
dict — a dict raises "too many values to unpack"
- COSINE scores are DISTANCES, ascending, and an exact self-match scores
near-zero rather than zero because of quantization
- vector fields must be wrapped in encode_vector(); a plain list silently
fails to index
- semantic-cache entries are only visible to FT.CACHESEARCH when the key
falls under the index PREFIX — outside it, cache_hit is permanently false
and nothing is raised
Probing the cache path also surfaced moon#748: cache_hit is inverted for
COSINE and INNER_PRODUCT indexes, so a near-identical query misses and an
unrelated query hits. The skill routes around it (use L2, or apply your own
cut-off on the score) until it is fixed.
scripts/smoke.py exercises all of it and doubles as a regression detector: it
reports the #748 inversion as a SKIP with a diagnostic today and flips to PASS
once the predicate is corrected. Verified to exit 1 against a plain
redis-server and 0 against Moon, so it is not a gate that cannot fail.
author: Tin Dang
|
ⓘ Qodo reviews are paused because the subscription is no longer active. Ask your workspace admin to reactivate the subscription to resume reviews. Manage billing |
|
Warning Review limit reachedNext included review available in 47 minutes. View limit detailsLimit details: You’ve used the included review currently available. You've used all free OSS reviews for now. Wait for the free limit to reset to keep reviewing this public repository. Review configuration: ⚙️ Run configurationConfiguration used: defaults Review profile: CHILL Plan: Pro Plus Run ID: 📒 Files selected for processing (2)
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. Comment |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
Adds
.claude/skills/moon-agent/— a skill that teaches an AI agent to operate a Mooninstance and use it as an agent data plane, plus
scripts/smoke.pythat exercises everydocumented flow.
Why
Moon already covers what an agent usually needs three services for: scratch state (KV+TTL),
semantic recall (FT.* vector), relations (Cypher graph), full-text, and events (pub/sub).
Nothing in the repo told an agent how to drive it. The SDK README has a quick start, but not
the failure modes — and several of them fail silently rather than loudly.
Everything here was executed before it was written
The constraints below were found by running the flows against a live moon 0.8.7, not
inferred from signatures. First harness run: 26 of 29 passed; the three failures became
documentation.
FILTERneeds--shards 1FILTER not supported in multi-shard mode yet(name, type, opts)tuples, not a dictValueError: too many values to unpackencode_vector()scoreis a distance, ascendingPREFIXcache_hitpermanentlyFalse, no errorFound a bug on the way: moon#748
Probing the semantic-cache path surfaced that
cache_hitis inverted forCOSINE/INNER_PRODUCT(cache_search.rs:179treats a cosine distance as a similarity). Anear-identical query misses; an unrelated query hits.
L2is correct. Filed as #748 with athreshold sweep and the reason CI is blind to it — the unit tests assert the predicate in
isolation against the same wrong assumption.
The skill routes around it (use
L2, or apply your own cut-off onscore) rather thanpretending the path works.
The smoke test is not a gate that cannot fail
scripts/smoke.pywas verified in both directions:redis-server→ exit 1, 11 failures includingis moon (not redis)--shards 1, 21 + 1 skip at--shards 2(
FILTERcorrectly skipped, not failed)It also doubles as a regression detector for #748: reports the inversion as a SKIP with a
diagnostic today, flips to PASS once the predicate is fixed.
Notes
src/changes, so no runtime risk. Needsskip-changelog.